equal
deleted
inserted
replaced
4 summary: RESTful XMPP API |
4 summary: RESTful XMPP API |
5 --- |
5 --- |
6 |
6 |
7 # Introduction |
7 # Introduction |
8 |
8 |
9 This is yet another RESTful API for sending stanzas via Prosody. |
9 This is yet another RESTful API for sending and receiving stanzas via |
|
10 Prosody. It can be used to build bots and components implemented as HTTP |
|
11 services. |
10 |
12 |
11 # Usage |
13 # Usage |
12 |
14 |
13 Note that there is currently **no authentication**, so be careful with |
15 Note that there is currently **no authentication**, so be careful with |
14 exposing the API endpoint to the Internet. |
16 exposing the API endpoint to the Internet. |
47 --data-binary '<iq type="get" to="example.net"> |
49 --data-binary '<iq type="get" to="example.net"> |
48 <ping xmlns="urn:xmpp:ping"/> |
50 <ping xmlns="urn:xmpp:ping"/> |
49 </iq>' |
51 </iq>' |
50 ``` |
52 ``` |
51 |
53 |
|
54 ## Receiving stanzas |
|
55 |
|
56 TL;DR: Set this webhook callback URL, get XML `POST`-ed there. |
|
57 |
|
58 ``` {.lua} |
|
59 Component "rest.example.net" "rest" |
|
60 rest_callback_url = "http://my-api.example:9999/stanzas" |
|
61 ``` |
|
62 |
|
63 Example callback looks like: |
|
64 |
|
65 ``` {.xml} |
|
66 POST /stanzas HTTP/1.1 |
|
67 Content-Type: application/xmpp+xml |
|
68 Content-Length: 52 |
|
69 |
|
70 <message to="bot@rest.example.net" from="user@example.com" type="chat"> |
|
71 <body>Hello</body> |
|
72 </message> |
|
73 ``` |
|
74 |
|
75 ### Replying |
|
76 |
|
77 To accept the stanza without returning a reply, respond with HTTP status |
|
78 code `202` or `204`. |
|
79 |
|
80 For full control over the response, set the `Content-Type` header to |
|
81 `application/xmpp+xml` and return an XMPP stanza as an XML snippet. |
|
82 |
|
83 ``` {.xml} |
|
84 HTTP/1.1 200 Ok |
|
85 Content-Type: application/xmpp+xml |
|
86 |
|
87 <message type="chat"> |
|
88 <body>Yes, this is bot</body> |
|
89 </message> |
|
90 ``` |
|
91 |
52 # Compatibility |
92 # Compatibility |
53 |
93 |
54 Requires Prosody trunk / 0.12 |
94 Requires Prosody trunk / 0.12 |