Messaging
Chat has two halves:
- REST for loading a conversation, paging through history and uploading attachments.
- A real-time socket for sending text, receiving messages as they arrive, typing indicators, presence and read receipts.
The socket uses the standard Phoenix Channels protocol, so you can use the official phoenix JavaScript client, any Phoenix-compatible client library for your platform, or the dependency-free client in the Chat Client Reference.
All requests here are made as the traveller (see Authentication).
Load The Conversation
GET /api/v2/issues/:issue_id/conversation
{
"id": "a4e2c1d7-9b8f-4e6a-b5c3-1d2e3f4a5b6c",
"issue_id": "0d9b3a40-5f3c-4c9e-8a7e-2f6a1b8c9d01",
"participant_ids": ["6b0c6f8e-2b1f-4a8e-9d55-0d6f1d3c2a10"],
"participants": [ { "id": "6b0c6f8e-...", "first_name": "...", ... } ],
"messages": [
{
"id": "e1f2...",
"client_id": "c7d8...",
"type": 3,
"status": 1,
"body": "Please stand by. Your issue has been received by our staff and is being reviewed. Someone will reply to help you soon. ...",
"user_id": "6b0c6f8e-...",
"conversation_id": "a4e2c1d7-...",
"asset": null,
"created_at": "2026-10-12T14:03:11Z",
"updated_at": "2026-10-12T14:03:11Z"
}
],
"created_at": "2026-10-12T14:03:11Z",
"updated_at": "2026-10-12T14:03:11Z"
}
The response embeds every message in the conversation, which is fine for short chats. Sort them by created_at before displaying them. If you already know the conversation id, GET /api/v2/conversations/:id returns the same shape. For long conversations, page through the history instead.
Message History
GET /api/v2/conversations/:conversation_id/messages?page=1&page_size=50
Returns the conversation's messages newest first: the first page is the most recent activity, and later pages go back in time. page_size defaults to 50 (maximum 100). The standard pagination headers (total, total-pages, per-page, page-number and Link) tell you how much history there is.
[
{ "id": "...", "client_id": "...", "type": 0, "status": 2, "body": "We've found the nearest consulate.", "user_id": "...", "created_at": "2026-10-12T14:09:42Z", ... },
{ "id": "...", "client_id": "...", "type": 0, "status": 2, "body": "My passport was stolen", "user_id": "...", "created_at": "2026-10-12T14:04:02Z", ... }
]
Load the first page when the chat opens, then fetch the next page as the traveller scrolls up.
Participants change as agents join, so look up message authors by user_id and refresh the conversation if you see a user_id you don't recognise.
Connect To The Socket
Get a socket token:
POST /api/v2/tokens/for_socketโ{"token": "..."}(see Authentication).Connect, passing the token as the
tokenparameter:wss://sockets.sitata.com/socket/websocket?token=<socket token>Staging is
wss://staging.sitata.com/socket/websocket. If you use a Phoenix client library, give it the endpoint without the/websocketsuffix (wss://sockets.sitata.com/socket) and pass the token in itsparamsoption; the library appends the suffix itself.Join the topic
conversation:<conversation_id>with an empty payload{}.Send a heartbeat (topic
phoenix, eventheartbeat) every 30 seconds. Phoenix client libraries do this for you.
A traveller can join the conversations they participate in. Joining any other conversation is rejected.
import { Socket } from "phoenix";
const { token } = await api.post("/tokens/for_socket");
const socket = new Socket("wss://sockets.sitata.com/socket", { params: { token } });
socket.connect();
const channel = socket.channel(`conversation:${conversationId}`, {});
channel.on("new:message", ({ message }) => upsertMessage(message));
channel.on("list:messages", ({ messages }) => messages.forEach(upsertMessage));
channel.on("read:message", ({ id, client_id }) => markRead(id, client_id));
channel
.join()
.receive("ok", () => channel.push("load:messages", {}))
.receive("error", (resp) => console.error("Could not join", resp));
When the connection drops, reconnect with a fresh socket token, re-join, and reload the first page of message history to pick up anything you missed.
Events
Events you send
| Event | Payload | What it does |
|---|---|---|
create:message | {"type": 0, "status": 0, "body": "...", "client_id": "<uuid>"} | Sends a text message. The server replies ok (or error) and broadcasts new:message to everyone in the conversation, including you. |
user:typing | {"typing": true} / {"typing": false} | Starts or stops your typing indicator, which everyone else sees through presence. |
read:message | {"client_id": "<the message's client_id>", "user_id": "<your user id>"} | Marks a message as read and broadcasts a read receipt. |
mark_read:conversation | {} | Marks the whole conversation as read, which resets its unread_count. Replies {"last_read_at": "..."}. |
load:messages | {} | Asks for recent history; the server answers with list:messages. |
Events you receive
| Event | Payload | Meaning |
|---|---|---|
new:message | {"message": {...}} | A new message, from an agent, the traveller (including your own echo), or the system. |
list:messages | {"messages": [...]} | The reply to load:messages. |
read:message | {"client_id": "...", "id": "...", "user_id": "..."} | A participant read a message. Set that message's status to 2. The payload echoes what the reader sent, plus the message id. |
conversation:read | {"user_id", "conversation_id", "last_read_at"} | The traveller read the conversation on one of their devices. Clear the unread badge on the others. |
presence_state / presence_diff | Phoenix Presence payloads | Who's online and who's typing. See below. |
translation:updated | {"conversation_id", "translate_locale", "translation_enabled", ...} | Live translation settings changed for the conversation. |
caution
list:messages returns at most 100 messages, starting from the oldest. Use it as a quick catch-up for short conversations, but load history from the paginated message history endpoint.
Sending Messages
Send text over the socket with create:message. Generate a UUID client_id for every message: it lets you show the message immediately (status 0, sending) and then match it to the server's new:message echo, which carries the same client_id plus the server id.
function sendText(body) {
const message = { type: 0, status: 0, body, client_id: crypto.randomUUID() };
upsertMessage({ ...message, user_id: me.id, created_at: new Date().toISOString() });
channel
.push("create:message", message)
.receive("error", () => upsertMessage({ ...message, status: 3 }))
.receive("timeout", () => upsertMessage({ ...message, status: 3 }));
}
Merge incoming messages by id, or by client_id when you only have the optimistic copy, so each message is shown once.
tip
Prefer the socket for text. You get an immediate reply and the echo arrives on the channel you're already listening to. If your integration can't hold a socket open (for example, a server-side relay), POST /api/v2/conversations/:id/messages with {"message": {"type": 0, "body": "..."}} works too. Either way the message is broadcast to the conversation, and participants who aren't online get Sitata's "missed message" notification.
Typing indicators and presence
When a participant joins, the server tracks them in Phoenix Presence with metadata like:
{ "user_id": "...", "name": "Maria (Assistance)", "online_at": "1760277791", "typing": false }
presence_state arrives right after you join, followed by a presence_diff whenever someone joins, leaves or changes their typing state. A participant is typing if any of their metas has "typing": true (they may be connected from more than one device).
Push user:typing with true when the traveller starts typing and false after about 3 seconds without a keystroke, or when they send.
Read receipts
When an agent's message is visible on screen, push read:message with its client_id and the traveller's user_id. Everyone in the conversation receives a read:message receipt, and the message's stored status becomes 2 (read). Push mark_read:conversation when the traveller opens the chat to reset the issue's unread_count.
Attachments
Upload photos, videos and documents with a multipart REST request. The message is broadcast on the socket as a normal new:message once it's saved.
POST /api/v2/conversations/:conversation_id/messages
Content-Type: multipart/form-data
| Field | Value |
|---|---|
message[type] | 4 (asset) |
message[asset][type] | 0 image, 1 video, 6 document |
message[asset][photo] / [video] / [document] | The file, in the field matching the asset type |
message[body] | Optional caption |
message[client_id] | Optional UUID, so you can match the broadcast to an optimistic copy |
async function sendFile(file, caption = "") {
const kind = file.type.startsWith("image/") ? ["0", "photo"]
: file.type.startsWith("video/") ? ["1", "video"]
: ["6", "document"];
const form = new FormData();
form.append("message[type]", "4");
form.append("message[asset][type]", kind[0]);
form.append(`message[asset][${kind[1]}]`, file);
form.append("message[body]", caption);
// Don't set Content-Type yourself: the browser adds the multipart boundary.
await fetch(`${API_BASE}/conversations/${conversationId}/messages`, {
method: "POST",
headers: { Authorization: `TKN ${travellerToken}`, Organization: COMPANY_ID },
body: form,
});
}
Clients that can't send multipart can send JSON instead, with the file as a base64 string (no data: prefix): {"message": {"type": 4, "asset": {"type": 0, "photo": "<base64>"}}}.
The message's asset contains signed download URLs:
"asset": {
"id": "...",
"type": 0,
"photo": { "original": "https://...", "large": "https://...", "thumb": "https://..." },
"video": null,
"document": null
}
Images come with original, large (up to 1280ร960) and thumb versions; videos and documents have original only. Signed URLs expire after 24 hours, so don't store them. Reload the conversation to get fresh URLs.
Reference
Message types
| Value | Type | Notes |
|---|---|---|
0 | Text | |
1 | Bot | Automated message. |
2 | Deleted | Show as "message deleted". |
3 | Announcement | System notice, such as "please stand by" or "Maria has joined the conversation!". Render it centred, not as a chat bubble. |
4 | Asset | Attachment; see asset. May have a caption in body. |
5 | SMS | Sent or received over SMS. Display it like text. |
6 | Sent or received by email. Display it like text. |
Message statuses
| Value | Status |
|---|---|
0 | Sending (client-side only) |
1 | Delivered to the server |
2 | Read by a participant |
3 | Failed (client-side only) |
Translation
Conversations can have live translation enabled by the assistance team. When a message has been translated, source_locale holds the language it was written in and translations maps locales to translated text. Display translations[<traveller's locale>] when present, otherwise body.