|
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 ``` |
|
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 Option Description |
|
38 ------------------------------------ ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
39 component\_post\_url The URL that will handle incoming stanzas |
|
40 component\_post\_stanzas A list of stanza types to forward over HTTP. Defaults to `{ "message" }`. |
|
41 |
|
42 Details |
|
43 ------- |
|
44 |
|
45 Requests |
|
46 ======== |
|
47 |
|
48 Each received stanza is converted into a JSON object, and submitted to `component_post_url` using a HTTP POST request. |
|
49 |
|
50 The JSON object always has the following properties: |
|
51 |
|
52 Property Description |
|
53 -------------------------- ------------ |
|
54 to The JID that the stanza was sent to (e.g. foobar@your.component.domain) |
|
55 from The sender's JID. |
|
56 kind The kind of stanza (will always be "message", "presence" or "iq". |
|
57 stanza The full XML of the stanza. |
|
58 |
|
59 Additionally, the JSON object may contain the following properties: |
|
60 |
|
61 Property Description |
|
62 -------------------------- ------------ |
|
63 body If the stanza is a message, and it contains a body, this is the string content of the body. |
|
64 |
|
65 |
|
66 Responses |
|
67 ========= |
|
68 |
|
69 If you wish to respond to a stanza, you may include a reply when you respond to the HTTP request. |
|
70 |
|
71 Responses must have a HTTP status 200 (OK), and must set the Conent-Type header to `application/json`. |
|
72 |
|
73 A response may contain any of the properties of a request. If not supplied, then defaults are chosen. |
|
74 |
|
75 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. |
|
76 |
|
77 If 'kind' is not set, it defaults to 'message', and if 'body' is set, this is automatically added as a message body. |
|
78 |
|
79 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 |
|
80 sent by components must have a 'to' and 'from'. |
|
81 |
|
82 Presence |
|
83 ======== |
|
84 |
|
85 By default the module automatically handles presence to provide an always-on component, that automatically accepts subscription requests. |
|
86 |
|
87 This means that by default presence stanzas are not forwarded to the configured URL. To provide your own presence handling, you can override |
|
88 this by adding "presence" to the component\_post\_stanzas option in your config. |
|
89 |
|
90 |
|
91 Compatibility |
|
92 ------------- |
|
93 |
|
94 Should work with all versions of Prosody from 0.9 upwards. |