Aoba XMPP Messaging API 1.0.0 documentation

Aoba XMPP Messaging API 1.0.0

MIT
application/xml

XMPP-based real-time messaging API using WebSocket transport (RFC 7395).

Purpose

This API provides real-time chat functionality including:

Direct messaging (1:1 chat)
Group chat (Multi-User Chat / MUC)
Presence (online/offline/away status)
Message delivery receipts (XEP-0184)

Protocol

Uses XMPP (Extensible Messaging and Presence Protocol) over WebSocket. Messages are XML stanzas following XMPP Core (RFC 6120) and relevant XEPs.

Authentication

Client opens WebSocket to /xmpp
Server validates JWT from auth_token cookie during upgrade
XMPP stream negotiation begins with pre-authenticated session
SASL authentication auto-succeeds (cookie already validated)
Client sends initial presence to indicate availability

XEPs Implemented

XEP-0045: Multi-User Chat (MUC) for group messaging
XEP-0184: Message Delivery Receipts
XEP-0199: XMPP Ping (keepalive)

Servers

ws://localhost:8082/wsdevelopment
Local development server
wss://staging.aoba.chat/wssstaging
Staging server (TLS required)
wss://api.aoba.chat/wssproduction
Production server (TLS required)

Operations

SEND /xmpp
XMPP over WebSocket endpoint following RFC 7395.

Authentication: JWT token must be present in auth_token cookie. Connection uses XMPP framing (urn:ietf:params:xml:ns:xmpp-framing).

JID Format: {username}@{domain}/{resource}

Example: alice@localhost/web-abc123
Send direct message to user
Send a 1:1 chat message to another user. The message is routed through the XMPP server to the recipient's connected clients.

Operation IDsendChatMessage
Available only on servers:
object
method
GET
object
Cookie
string
Must contain auth_token={jwt}

Sec-WebSocket-Protocol
string
WebSocket subprotocol

Const:"xmpp"
Additional properties are allowed.
Accepts the following message:
Direct Chat MessageChatMessage
1:1 chat message between users
application/xml
Message IDChatMessage
object
XMPP message stanza for direct chat

to
required
string
Recipient JID (bare or full)

from
string
Sender JID (set by server on incoming messages)

type
required
string
Message type

Allowed values:
"chat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
Examples
#1 Example - Simple text message
Hello Bob!
RECEIVE /xmpp
XMPP over WebSocket endpoint following RFC 7395.

Authentication: JWT token must be present in auth_token cookie. Connection uses XMPP framing (urn:ietf:params:xml:ns:xmpp-framing).

JID Format: {username}@{domain}/{resource}

Example: alice@localhost/web-abc123
Receive direct message from user
Receive a 1:1 chat message from another user.

Operation IDreceiveChatMessage
Available only on servers:
object
method
GET
object
Cookie
string
Must contain auth_token={jwt}

Sec-WebSocket-Protocol
string
WebSocket subprotocol

Const:"xmpp"
Additional properties are allowed.
Accepts the following message:
Direct Chat MessageChatMessage
1:1 chat message between users
application/xml
Message IDChatMessage
object
XMPP message stanza for direct chat

to
required
string
Recipient JID (bare or full)

from
string
Sender JID (set by server on incoming messages)

type
required
string
Message type

Allowed values:
"chat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
Examples
#1 Example - Simple text message
Hello Bob!
SEND /xmpp
XMPP over WebSocket endpoint following RFC 7395.

Authentication: JWT token must be present in auth_token cookie. Connection uses XMPP framing (urn:ietf:params:xml:ns:xmpp-framing).

JID Format: {username}@{domain}/{resource}

Example: alice@localhost/web-abc123
Send message to group
Send a message to a MUC room. The message is broadcast to all room participants by the server.

JID Format: group-{uuid}@{domain}

Operation IDsendGroupMessage
Available only on servers:
object
method
GET
object
Cookie
string
Must contain auth_token={jwt}

Sec-WebSocket-Protocol
string
WebSocket subprotocol

Const:"xmpp"
Additional properties are allowed.
Accepts the following message:
Group Chat MessageGroupChatMessage
Message to a MUC room
application/xml
Message IDGroupChatMessage
object
XMPP message stanza for group chat (MUC)

to
required
string
Group JID (format: group-{uuid}@domain)

from
string
Sender JID. On outgoing: your JID. On incoming: group-{uuid}@domain/{senderUsername}

type
required
string
Message type (always groupchat for MUC)

Allowed values:
"groupchat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
Examples
#1 Example - Group message
Hello everyone!
#2 Example - Received group message (from server)
Hello everyone!
RECEIVE /xmpp
XMPP over WebSocket endpoint following RFC 7395.

Authentication: JWT token must be present in auth_token cookie. Connection uses XMPP framing (urn:ietf:params:xml:ns:xmpp-framing).

JID Format: {username}@{domain}/{resource}

Example: alice@localhost/web-abc123
Receive message from group
Receive a group chat message. The from JID includes the sender's nickname in the resource part.

From Format: group-{uuid}@{domain}/{senderUsername}

Operation IDreceiveGroupMessage
Available only on servers:
object
method
GET
object
Cookie
string
Must contain auth_token={jwt}

Sec-WebSocket-Protocol
string
WebSocket subprotocol

Const:"xmpp"
Additional properties are allowed.
Accepts the following message:
Group Chat MessageGroupChatMessage
Message to a MUC room
application/xml
Message IDGroupChatMessage
object
XMPP message stanza for group chat (MUC)

to
required
string
Group JID (format: group-{uuid}@domain)

from
string
Sender JID. On outgoing: your JID. On incoming: group-{uuid}@domain/{senderUsername}

type
required
string
Message type (always groupchat for MUC)

Allowed values:
"groupchat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
Examples
#1 Example - Group message
Hello everyone!
#2 Example - Received group message (from server)
Hello everyone!
SEND /xmpp
XMPP over WebSocket endpoint following RFC 7395.

Authentication: JWT token must be present in auth_token cookie. Connection uses XMPP framing (urn:ietf:params:xml:ns:xmpp-framing).

JID Format: {username}@{domain}/{resource}

Example: alice@localhost/web-abc123
Send presence update
Broadcast presence status to contacts and joined rooms. Initial presence must be sent after authentication to appear online.

Operation IDsendPresence
Available only on servers:
object
method
GET
object
Cookie
string
Must contain auth_token={jwt}

Sec-WebSocket-Protocol
string
WebSocket subprotocol

Const:"xmpp"
Additional properties are allowed.
Accepts the following message:
Presence StanzaPresenceUpdate
User availability status
application/xml
Message IDPresenceUpdate
object
XMPP presence stanza

to
string
Recipient JID (optional, for directed presence)

from
string
Sender JID (set by server)

type
string
Presence type (absent for available)

Allowed values:
"unavailable"
"subscribe"
"subscribed"
"unsubscribe"
"unsubscribed"
"probe"
"error"
show
string
Availability sub-state:

away: Temporarily away

chat: Actively interested in chatting

dnd: Do not disturb

xa: Extended away

Allowed values:
"away"
"chat"
"dnd"
"xa"
status
string
Human-readable status message

Additional properties are allowed.
Examples
#1 Example - Available (online)

#2 Example - Away status
away Be right back

#3 Example - Unavailable (offline)
RECEIVE /xmpp
XMPP over WebSocket endpoint following RFC 7395.

Authentication: JWT token must be present in auth_token cookie. Connection uses XMPP framing (urn:ietf:params:xml:ns:xmpp-framing).

JID Format: {username}@{domain}/{resource}

Example: alice@localhost/web-abc123
Receive presence update
Receive presence updates from contacts and room participants.

Operation IDreceivePresence
Available only on servers:
object
method
GET
object
Cookie
string
Must contain auth_token={jwt}

Sec-WebSocket-Protocol
string
WebSocket subprotocol

Const:"xmpp"
Additional properties are allowed.
Accepts the following message:
Presence StanzaPresenceUpdate
User availability status
application/xml
Message IDPresenceUpdate
object
XMPP presence stanza

to
string
Recipient JID (optional, for directed presence)

from
string
Sender JID (set by server)

type
string
Presence type (absent for available)

Allowed values:
"unavailable"
"subscribe"
"subscribed"
"unsubscribe"
"unsubscribed"
"probe"
"error"
show
string
Availability sub-state:

away: Temporarily away

chat: Actively interested in chatting

dnd: Do not disturb

xa: Extended away

Allowed values:
"away"
"chat"
"dnd"
"xa"
status
string
Human-readable status message

Additional properties are allowed.
Examples
#1 Example - Available (online)

#2 Example - Away status
away Be right back

#3 Example - Unavailable (offline)
SEND /xmpp
XMPP over WebSocket endpoint following RFC 7395.

Authentication: JWT token must be present in auth_token cookie. Connection uses XMPP framing (urn:ietf:params:xml:ns:xmpp-framing).

JID Format: {username}@{domain}/{resource}

Example: alice@localhost/web-abc123
Send message with delivery receipt request
Send a message with XEP-0184 receipt request. The recipient should respond with a delivery receipt when the message is received.

Operation IDsendMessageWithReceipt
Available only on servers:
object
method
GET
object
Cookie
string
Must contain auth_token={jwt}

Sec-WebSocket-Protocol
string
WebSocket subprotocol

Const:"xmpp"
Additional properties are allowed.
Accepts the following message:
Message with Receipt RequestDeliveryReceiptRequest
Message requesting delivery confirmation (XEP-0184)
application/xml
Message IDDeliveryReceiptRequest
object allOf
Message with XEP-0184 receipt request

object
XMPP message stanza for direct chat

to
required
string
Recipient JID (bare or full)

from
string
Sender JID (set by server on incoming messages)

type
required
string
Message type

Allowed values:
"chat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
object
object
XEP-0184 receipt request element

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
Examples
#1 Example - Message with receipt request
Did you get this?
RECEIVE /xmpp
XMPP over WebSocket endpoint following RFC 7395.

Authentication: JWT token must be present in auth_token cookie. Connection uses XMPP framing (urn:ietf:params:xml:ns:xmpp-framing).

JID Format: {username}@{domain}/{resource}

Example: alice@localhost/web-abc123
Receive delivery receipt
Receive confirmation that a sent message was delivered. The receipt contains the original message ID.

Operation IDreceiveDeliveryReceipt
Available only on servers:
object
method
GET
object
Cookie
string
Must contain auth_token={jwt}

Sec-WebSocket-Protocol
string
WebSocket subprotocol

Const:"xmpp"
Additional properties are allowed.
Accepts the following message:
Delivery ReceiptDeliveryReceipt
Confirmation of message delivery (XEP-0184)
application/xml
Message IDDeliveryReceipt
object
XEP-0184 delivery receipt acknowledgment

to
required
string
Original sender's JID

from
string
Acknowledger's JID

type
required
string
Allowed values:
"chat"
id
required
string
Receipt message ID (not the original message ID)

required
object
Receipt element containing original message ID

id
string
ID of the message being acknowledged

Additional properties are allowed.
Additional properties are allowed.
Examples
#1 Example - Receipt acknowledgment

Messages

#1Direct Chat MessageChatMessage
1:1 chat message between users
- application/xml
Message IDChatMessage
object
XMPP message stanza for direct chat

to
required
string
Recipient JID (bare or full)

from
string
Sender JID (set by server on incoming messages)

type
required
string
Message type

Allowed values:
"chat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
#2Group Chat MessageGroupChatMessage
Message to a MUC room
- application/xml
Message IDGroupChatMessage
object
XMPP message stanza for group chat (MUC)

to
required
string
Group JID (format: group-{uuid}@domain)

from
string
Sender JID. On outgoing: your JID. On incoming: group-{uuid}@domain/{senderUsername}

type
required
string
Message type (always groupchat for MUC)

Allowed values:
"groupchat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
#3Presence StanzaPresenceUpdate
User availability status
- application/xml
Message IDPresenceUpdate
object
XMPP presence stanza

to
string
Recipient JID (optional, for directed presence)

from
string
Sender JID (set by server)

type
string
Presence type (absent for available)

Allowed values:
"unavailable"
"subscribe"
"subscribed"
"unsubscribe"
"unsubscribed"
"probe"
"error"
show
string
Availability sub-state:

away: Temporarily away

chat: Actively interested in chatting

dnd: Do not disturb

xa: Extended away

Allowed values:
"away"
"chat"
"dnd"
"xa"
status
string
Human-readable status message

Additional properties are allowed.
#4Message with Receipt RequestDeliveryReceiptRequest
Message requesting delivery confirmation (XEP-0184)
- application/xml
Message IDDeliveryReceiptRequest
object allOf
Message with XEP-0184 receipt request

object
XMPP message stanza for direct chat

to
required
string
Recipient JID (bare or full)

from
string
Sender JID (set by server on incoming messages)

type
required
string
Message type

Allowed values:
"chat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
object
object
XEP-0184 receipt request element

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
#5Delivery ReceiptDeliveryReceipt
Confirmation of message delivery (XEP-0184)
- application/xml
Message IDDeliveryReceipt
object
XEP-0184 delivery receipt acknowledgment

to
required
string
Original sender's JID

from
string
Acknowledger's JID

type
required
string
Allowed values:
"chat"
id
required
string
Receipt message ID (not the original message ID)

required
object
Receipt element containing original message ID

id
string
ID of the message being acknowledged

Additional properties are allowed.
Additional properties are allowed.

Schemas

object
XMPP message stanza for direct chat

to
required
string
Recipient JID (bare or full)

from
string
Sender JID (set by server on incoming messages)

type
required
string
Message type

Allowed values:
"chat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
object
XMPP message stanza for group chat (MUC)

to
required
string
Group JID (format: group-{uuid}@domain)

from
string
Sender JID. On outgoing: your JID. On incoming: group-{uuid}@domain/{senderUsername}

type
required
string
Message type (always groupchat for MUC)

Allowed values:
"groupchat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
object
XMPP presence stanza

to
string
Recipient JID (optional, for directed presence)

from
string
Sender JID (set by server)

type
string
Presence type (absent for available)

Allowed values:
"unavailable"
"subscribe"
"subscribed"
"unsubscribe"
"unsubscribed"
"probe"
"error"
show
string
Availability sub-state:

away: Temporarily away

chat: Actively interested in chatting

dnd: Do not disturb

xa: Extended away

Allowed values:
"away"
"chat"
"dnd"
"xa"
status
string
Human-readable status message

Additional properties are allowed.
object allOf
Message with XEP-0184 receipt request

object
XMPP message stanza for direct chat

to
required
string
Recipient JID (bare or full)

from
string
Sender JID (set by server on incoming messages)

type
required
string
Message type

Allowed values:
"chat"
id
required
string
Unique message identifier (UUID format)

body
required
string
Message text content

Additional properties are allowed.
object
object
XEP-0184 receipt request element

Additional properties are allowed.
Additional properties are allowed.
Additional properties are allowed.
object
XEP-0184 delivery receipt acknowledgment

to
required
string
Original sender's JID

from
string
Acknowledger's JID

type
required
string
Allowed values:
"chat"
id
required
string
Receipt message ID (not the original message ID)

required
object
Receipt element containing original message ID

id
string
ID of the message being acknowledged

Additional properties are allowed.
Additional properties are allowed.
JID
string
must match: ^([^@/]+@)?[^@/]+(\/[^@/]+)?$
Jabber ID (JID) following RFC 7622.

Formats:

Bare JID: localpart@domain (e.g., alice@localhost)

Full JID: localpart@domain/resource (e.g., alice@localhost/web-123)

Domain JID: domain (e.g., conference.localhost)

Examples values:
"alice@localhost"
"alice@localhost/web-abc123"
"group-uuid@conference.localhost"
object
XMPP error stanza

type
string
Error type category

Allowed values:
"auth"
"cancel"
"continue"
"modify"
"wait"
condition
string
Error condition (e.g., not-authorized, item-not-found)

text
string
Human-readable error description

Additional properties are allowed.

Aoba XMPP Messaging API 1.0.0

Purpose

Protocol

Authentication

XEPs Implemented

Servers

Operations

SEND /xmpp

Examples

#1 Example - Simple text message

RECEIVE /xmpp

Examples

#1 Example - Simple text message

SEND /xmpp

Examples

#1 Example - Group message

#2 Example - Received group message (from server)

RECEIVE /xmpp

Examples

#1 Example - Group message

#2 Example - Received group message (from server)

SEND /xmpp

Examples

#1 Example - Available (online)

#2 Example - Away status

#3 Example - Unavailable (offline)

RECEIVE /xmpp

Examples

#1 Example - Available (online)

#2 Example - Away status

#3 Example - Unavailable (offline)

SEND /xmpp

Examples

#1 Example - Message with receipt request

RECEIVE /xmpp

Examples

#1 Example - Receipt acknowledgment

Messages

Schemas