Frontend Integration

For web (React/Next.js) and mobile developers. After this page you can build the inbox without asking a backend engineer.

Messaging endpoints authenticate with the admin login JWT (not an API key):

Authorization: Bearer <jwt>

Required permission

Messaging access is graded per provider (read | create | update | delete) at levels A > G > M > D (see Authorization):

Read the caller's chat_rights[] from the login response (data.user) and hide actions the level forbids — the backend also enforces it (403 if you don't).

The flow

1. Login            POST /admin/auth/login            → read chat_rights[]
2. List sessions    GET  /messaging/sessions/lookup
3. List chats       GET  /messaging/chats/all         → filter, paginate
4. Load messages    GET  /messaging/messages/:chatSlug
5. Send             POST /messaging/messages/send/:chatSlug/:type
6. Realtime         WS   /messaging/events            → live updates

Send a message

// text
await fetch(`${BASE}/messaging/messages/send/${chatSlug}/text`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ body: 'Hi 👋', front_id: clientMsgId }),
});

type is one of text | image | video | audio | document | file. For media, send multipart/form-data with a files field (see Examples).

Subscribe to realtime

Connect Socket.IO to the /messaging/events namespace, passing the JWT in the handshake. You auto-join your visible session rooms and receive live events:

import { io } from 'socket.io-client';
const socket = io(`${WS_HOST}/messaging/events`, { auth: { token: jwt } });
socket.on('message', (e) => addMessage(e.payload));      // new message
socket.on('message-ack', (e) => updateAck(e));           // sent/delivered/read
socket.on('chat-read', (e) => markChatRead(e));

Full event list: Events.

UI concerns

• Optimistic send — render the message immediately with your front_id; the send response and the WS message event both echo front_id, so reconcile on it.
• Loading — the send endpoint returns before the provider delivers; show a "sending" state and flip it on the message-ack event.
• Pagination — GET /messaging/messages/:chatSlug and GET /messaging/chats/all take page / limit. Load older messages on scroll-up.
• Errors — see Troubleshooting for 401 / 403 / 400 causes.

Next

• Copy-paste code → Examples
• Every endpoint → REST API