Mercurial > prosody-modules
comparison mod_component_http/README.markdown @ 2957:0f813e22e3fa
Merge commit
author | JC Brand <jc@opkode.com> |
---|---|
date | Tue, 27 Mar 2018 10:51:25 +0200 |
parents | 1f06a7fe75a8 |
children |
comparison
equal
deleted
inserted
replaced
2956:d0ca211e1b0e | 2957:0f813e22e3fa |
---|---|
1 --- | |
2 summary: 'Allows implementing a component or bot over HTTP' | |
3 ... | |
4 | |
5 Introduction | |
6 ============ | |
7 | |
8 This module allows you to implement a component that speaks HTTP. Stanzas (such as messages) coming from XMPP are sent to | |
9 a configurable URL as a HTTP POST. If the POST returns a response, that response is returned to the sender over XMPP. | |
10 | |
11 See also mod_post_msg. | |
12 | |
13 Example usage | |
14 ------------- | |
15 | |
16 Example echo bot in PHP: | |
17 | |
18 ``` php | |
19 <?php | |
20 | |
21 // Receive and decode message JSON | |
22 $post_data = file_get_contents('php://input'); | |
23 $received = json_decode($post_data)->body; | |
24 | |
25 // Send response | |
26 header('Content-Type: application/json'); | |
27 echo json_encode(array( | |
28 'body' => "Did you say $received?" | |
29 )); | |
30 | |
31 ?> | |
32 ``` | |
33 | |
34 Configuration | |
35 ============= | |
36 | |
37 The module is quite flexible, but should generally be loaded as a component like this: | |
38 | |
39 ``` | |
40 Component "yourservice.example.com" "component_http" | |
41 component_post_url = "https://example.com/your-api" | |
42 ``` | |
43 | |
44 Such a component would handle traffic for all JIDs with 'yourservice.example.com' as the hostname, such | |
45 as 'foobar@yourservice.example.com'. Although this example uses a subdomain, there is no requirement for | |
46 the component to use a subdomain. | |
47 | |
48 Available configuration options are: | |
49 | |
50 | |
51 Option Description | |
52 ------------------------------------ ------------------------------------------------------------------------------------------------------------------------------------------------- | |
53 component\_post\_url The URL that will handle incoming stanzas | |
54 component\_post\_stanzas A list of stanza types to forward over HTTP. Defaults to `{ "message" }`. | |
55 | |
56 Details | |
57 ======= | |
58 | |
59 Requests | |
60 -------- | |
61 | |
62 Each received stanza is converted into a JSON object, and submitted to `component_post_url` using a HTTP POST request. | |
63 | |
64 The JSON object always has the following properties: | |
65 | |
66 Property Description | |
67 -------------------------- ------------ | |
68 to The JID that the stanza was sent to (e.g. foobar@your.component.domain) | |
69 from The sender's JID. | |
70 kind The kind of stanza (will always be "message", "presence" or "iq". | |
71 stanza The full XML of the stanza. | |
72 | |
73 Additionally, the JSON object may contain the following properties: | |
74 | |
75 Property Description | |
76 -------------------------- ------------ | |
77 body If the stanza is a message, and it contains a body, this is the string content of the body. | |
78 | |
79 | |
80 Responses | |
81 --------- | |
82 | |
83 If you wish to respond to a stanza, you may include a reply when you respond to the HTTP request. | |
84 | |
85 Responses must have a HTTP status 200 (OK), and must set the Conent-Type header to `application/json`. | |
86 | |
87 A response may contain any of the properties of a request. If not supplied, then defaults are chosen. | |
88 | |
89 If 'to' and 'from' are not specified in the response, they are automatically swapped so that the reply is sent to the original sender of the stanza. | |
90 | |
91 If 'kind' is not set, it defaults to 'message', and if 'body' is set, this is automatically added as a message body. | |
92 | |
93 If 'stanza' is set, it overrides all of the above, and the supplied stanza is sent as-is using Prosody's normal routing rules. Note that stanzas | |
94 sent by components must have a 'to' and 'from'. | |
95 | |
96 Presence | |
97 -------- | |
98 | |
99 By default the module automatically handles presence to provide an always-on component, that automatically accepts subscription requests. | |
100 | |
101 This means that by default presence stanzas are not forwarded to the configured URL. To provide your own presence handling, you can override | |
102 this by adding "presence" to the component\_post\_stanzas option in your config. | |
103 | |
104 | |
105 Compatibility | |
106 ============= | |
107 | |
108 Should work with all versions of Prosody from 0.9 upwards. |