Mercurial > prosody-modules

comparison mod_rest/README.markdown @ 3795:f51308fcba83

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_rest: Allow specifying a webhook/callback to handle incoming stanzas
author Kim Alvefur <zash@zash.se>
date Mon, 30 Dec 2019 04:07:25 +0100
parents 4b258329e6e4
children d1ad10b76b00
comparison
equal deleted inserted replaced
3794:4b258329e6e4 3795:f51308fcba83
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