Mercurial > prosody-modules

comparison mod_component_http/README.markdown @ 2950:18e6d437003f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_component_http: Allow implementing a component over HTTP
author Matthew Wild <mwild1@gmail.com>
date Mon, 26 Mar 2018 13:49:13 +0100
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.