Software `/` code `/` prosody-modules

---
labels:
- 'Stage-Alpha'
summary: RESTful XMPP API
---

# Introduction

This is yet another RESTful API for sending and receiving stanzas via
Prosody. It can be used to build bots and components implemented as HTTP
services.

# Usage

## Enabling

``` {.lua}
Component "rest.example.net" "rest"
rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K"
```

## Sending stanzas

The API endpoint becomes available at the path `/rest`, so the full URL
will be something like `https://your-prosody.example:5281/rest`.

To try it, simply `curl` an XML stanza payload:

``` {.sh}
curl https://prosody.example:5281/rest \
    --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
    -H 'Content-Type: application/xmpp+xml' \
    --data-binary '<message type="chat" to="user@example.org">
            <body>Hello!</body>
        </body>'
```

The `Content-Type` **MUST** be `application/xmpp+xml`.

### Replies

A POST containing an `<iq>` stanza automatically wait for the reply,
long-polling style.

``` {.sh}
curl https://prosody.example:5281/rest \
    --oauth2-bearer dmVyeSBzZWNyZXQgdG9rZW4K \
    -H 'Content-Type: application/xmpp+xml' \
    --data-binary '<iq type="get" to="example.net">
            <ping xmlns="urn:xmpp:ping"/>
        </iq>'
```

Replies to other kinds of stanzas that are generated by the same Prosody
instance *MAY* be returned in the HTTP response. Replies from other
entities (connected clients or remote servers) will not be returned, but
can be forwarded via the callback API described in the next section.

## Receiving stanzas

TL;DR: Set this webhook callback URL, get XML `POST`-ed there.

``` {.lua}
Component "rest.example.net" "rest"
rest_credentials = "Bearer dmVyeSBzZWNyZXQgdG9rZW4K"
rest_callback_url = "http://my-api.example:9999/stanzas"
```

Example callback looks like:

``` {.xml}
POST /stanzas HTTP/1.1
Content-Type: application/xmpp+xml
Content-Length: 52

<message to="bot@rest.example.net" from="user@example.com" type="chat">
<body>Hello</body>
</message>
```

### Replying

To accept the stanza without returning a reply, respond with HTTP status
code `202` or `204`.

HTTP status codes in the `4xx` and `5xx` range are mapped to an
appropriate stanza error.

For full control over the response, set the `Content-Type` header to
`application/xmpp+xml` and return an XMPP stanza as an XML snippet.

``` {.xml}
HTTP/1.1 200 Ok
Content-Type: application/xmpp+xml

<message type="chat">
<body>Yes, this is bot</body>
</message>
```

## Payload format

``` {.xml}
<message type="" id="" to="" from="" xml:lang="">
...
</message>
```

An XML declaration (`<?xml?>`) **MUST NOT** be included.

The payload MUST contain one (1) `message`, `presence` or `iq` stanza.

The stanzas MUST NOT have an `xmlns` attribute, and the default/empty
namespace is treated as `jabber:client`.

# Compatibility

Requires Prosody trunk / 0.12
author	Kim Alvefur <zash@zash.se>
date	Tue, 31 Dec 2019 03:37:46 +0100
parent	3801:d59fb4dcf100
child	3808:02164f8aebac