Mercurial > prosody-modules
comparison mod_component_http/README.markdown @ 2950:18e6d437003f
mod_component_http: Allow implementing a component over HTTP
author | Matthew Wild <mwild1@gmail.com> |
---|---|
date | Mon, 26 Mar 2018 13:49:13 +0100 (2018-03-26) |
parents | |
children | 01ed9eb111d4 |
comparison
equal
deleted
inserted
replaced
2949:39994c6bb314 | 2950:18e6d437003f |
---|---|
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. |