README.markdown
1---
2summary: 'Allows implementing a component or bot over HTTP'
3...
4
5Introduction
6============
7
8This module allows you to implement a component that speaks HTTP. Stanzas (such as messages) coming from XMPP are sent to
9a configurable URL as a HTTP POST. If the POST returns a response, that response is returned to the sender over XMPP.
10
11See also mod_post_msg.
12
13Example usage
14-------------
15
16Example 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
26header('Content-Type: application/json');
27echo json_encode(array(
28 'body' => "Did you say $received?"
29));
30
31?>
32```
33
34Configuration
35=============
36
37The module is quite flexible, but should generally be loaded as a component like this:
38
39```
40Component "yourservice.example.com" "component_http"
41 component_post_url = "https://example.com/your-api"
42```
43
44Such a component would handle traffic for all JIDs with 'yourservice.example.com' as the hostname, such
45as 'foobar@yourservice.example.com'. Although this example uses a subdomain, there is no requirement for
46the component to use a subdomain.
47
48Available 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
56Details
57=======
58
59Requests
60--------
61
62Each received stanza is converted into a JSON object, and submitted to `component_post_url` using a HTTP POST request.
63
64The 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
73Additionally, 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
80Responses
81---------
82
83If you wish to respond to a stanza, you may include a reply when you respond to the HTTP request.
84
85Responses must have a HTTP status 200 (OK), and must set the Conent-Type header to `application/json`.
86
87A response may contain any of the properties of a request. If not supplied, then defaults are chosen.
88
89If '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
91If 'kind' is not set, it defaults to 'message', and if 'body' is set, this is automatically added as a message body.
92
93If '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
94sent by components must have a 'to' and 'from'.
95
96Presence
97--------
98
99By default the module automatically handles presence to provide an always-on component, that automatically accepts subscription requests.
100
101This means that by default presence stanzas are not forwarded to the configured URL. To provide your own presence handling, you can override
102this by adding "presence" to the component\_post\_stanzas option in your config.
103
104
105Compatibility
106=============
107
108Should work with all versions of Prosody from 0.9 upwards.
109