Exchange a token for a session
const url = 'https://app.mondochat.io/v1/session';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"app_id":"0199d6a0-0000-7000-8000-000000000001","token":"example-client-token"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.mondochat.io/v1/session \ --header 'Content-Type: application/json' \ --data '{ "app_id": "0199d6a0-0000-7000-8000-000000000001", "token": "example-client-token" }'Trades a client token your server signed for a session token. This route is public: the token in the body is the proof. With no token and guests.enabled on, it creates a guest and returns a guest_token; with a stored guest token it resumes that guest. With a client token and a guest token of the same app, it merges the guest into the member while guests.merge_on_login is on.
Errors: 401 unauthorized for an expired token, a lifetime over 600 seconds, a wrong issuer, a guest token of another app, or a replayed jti; 403 banned; 403 forbidden while a test app already has 50 users, or when the tenant is suspended; 429 rate_limited above 300 exchanges per IP per minute.
Guide: Sessions and tokens.
Request Bodyrequired
Section titled “Request Bodyrequired”Responses
Section titled “Responses”Successful Response
A session, with a guest token when the user is a guest.
object
The app’s settings for this viewer.
object
Colours, fonts, logo and launcher.
object
Show the people’s pictures; off draws the initial on the primary colour.
Background color.
CSS font family.
The inbox close button is a 30px tinted chip.
Tint the inbox background on every layout, not only two-pane.
Launcher bubble.
object
Show the launcher bubble.
Show the inbox close button on the inline page on a screen with a mouse.
Flat bubble colour, and Arial in the unread badge and the toast.
Launcher corner.
Text on the primary color.
Primary color.
Corner radius in pixels.
Surface color.
Text color.
Call settings, without prices unless per-minute is on.
object
Agora area code, e.g. EUROPE.
Agora video codec.
Ask before starting a call.
Every call takes the whole window, the chat button docks the call as a strip or a side rail beside the thread, and a minimise button shrinks it to a bubble.
Video calls enabled.
Calls end after this.
After calling an offline peer, note in the thread that they may not answer.
Per-minute charging of calls through the call_minute callout.
Ring time before missed.
An incoming call opens the chat and rings while it is closed; off shows the toast and sound, and the ring when the chat opens.
Show buyers a locked call button with a tip when they cannot call a seller.
One card per call that reads Call ended when it is over, and a busy callee closes the caller’s call screen instead of showing an error.
Camera capture settings.
object
Capture frame rate.
Capture height in pixels.
Capture width in pixels.
Warn before calling an offline peer.
Message, photo, video and voice rules.
object
Users may upload their own picture; it shows only after photo moderation approves it, and it wins over the host’s avatar.
The photo consent prompt puts Don’t allow before Allow; off puts Allow first.
Older messages load when the thread scrolls to its top; off shows a Load earlier button.
Senders may edit a text message this long after sending; 0 turns edits off.
Maximum photo upload size in bytes.
Photo messages enabled.
A message to someone who blocked the sender is refused (403 forbidden, reason undelivered) and not stored; off accepts it and drops it silently.
Day separators read day and month only; off adds the weekday, and the year for earlier years.
Maximum message length.
Senders may delete a message for everyone this long after sending; 0 turns it off. Deleting for oneself is always allowed.
Maximum video size in bytes; the browser converts to fit.
Maximum video length in seconds.
Video messages enabled.
Senders may mark a photo, video or voice note view once.
Voice notes enabled.
Maximum voice note size in bytes.
Maximum voice note length in seconds.
Commerce modes and flags only.
object
Catalog from the catalog callout or the dashboard.
An amount the buyer types, in the catalog currency.
object
Buyers may type an amount, such as a tip.
Largest amount in minor units.
Smallest amount in minor units.
Selling in conversations enabled.
How purchases are paid.
Where checkout and top-up pages open.
Show the balance the catalog callout returns.
A euro price on a purchase card reads 5 € or 5.50 €, never grouped.
Guest nudge and notify prompt for the viewer.
object
Show the notify prompt to this viewer.
The prompt’s button opens the sign-up.
Keep the prompt until done.
Languages and copy overrides.
object
Text overrides per language and message key.
object
object
Language when nothing else decides.
Languages offered.
Links to your site.
object
The conversation header opens the profile of sellers only.
With services_page, buyers also get a Services menu item.
Buyers can open the seller’s services page from a conversation.
Sound, banner and toast behaviour.
object
Show a banner on new messages.
At most one banner per 5 seconds.
Play a sound on new messages.
Clicking the launcher toast opens its conversation, or only the panel.
Onboarding for the viewer’s role.
object
Whether onboarding slides are on.
Show the slides again after this many hours.
The slides for the viewer’s role.
One onboarding slide.
object
Body per language.
object
Icon bullets.
An icon bullet on an onboarding slide.
object
Body per language.
object
Bullet icon.
Link text per language that opens guests.nudge.signup_url.
object
Title per language.
object
Highlighted note per language.
object
Title per language.
object
The origins allowed to embed the chat.
The viewer’s resolved policy per role.
object
What a role may do toward another role.
object
May block the peer.
May buy from the peer.
May start calls.
May send messages.
May send ad hoc offer cards.
The receiver must accept photos per conversation.
May send photos.
Starting needs a vouch token or the session’s peer.
May see the peer’s presence.
May start a conversation.
Online status settings.
object
Presence enabled.
Also push presence changes to each peer’s own channel. Turn off once every client subscribes with presence_pass.
Show the online dot and last seen in inbox rows.
Show “last seen” times.
The app’s roles.
A user role. Roles are referenced by policy, limits, guests and the role claim.
object
Role key, the value of the role claim.
Display name per language.
object
Users with this role sell services.
Blocking and reporting settings.
object
The banned panel has its own Close button.
A report asks for a reason; off is a plain confirm.
Inbound is true only where the app has guests; queue, notes and tiers as set.
object
Users may give peers a private name.
Sellers may set a reply sent for them, once a day per chat, while away.
Members may take messages from members only.
Users may keep a private note on a peer.
Users may pin up to 10 conversations.
Inbox views, archive, search, spent and purchases, and the sign-up invite.
Sellers keep up to 20 saved replies and send one with a tap.
Conversations with a seller carry her typical reply time.
Client tiers, lowest first; users get one by key.
A client tier a user can hold.
object
Badge color.
Tier key, the value of a user’s tier.
Display name per language.
object
When the session token expires.
The realtime address for this user.
object
The user’s own channel, /users/{user id}.
Host of the realtime HTTP endpoint.
WebSocket URL of the realtime endpoint.
Bearer token for the user routes; valid 15 minutes.
The signed-in user.
object
True once the user dismissed Get the app or has had a device.
The user’s id on your site, the sub claim.
The user’s id in mondochat.
Members: guests may not message this user.
member for a user your server signed in, guest for an anonymous one.
Nobody hides this user’s last seen from everyone and everyone’s from them.
Display name.
True once the viewer tapped or dismissed the notify prompt.
False while the onboarding slides are due, and again onboarding.repeat_hours after they were shown when that is set.
False: this user neither sends nor sees read ticks in any conversation.
A role key from the app’s roles.
Example
{ "app": { "branding": { "primary": "#2f6fed" }, "calls": { "enabled": false }, "chat": { "text_max_length": 4000 }, "commerce": { "enabled": false }, "guests": { "notify_prompt": false, "notify_prompt_signup": false, "notify_prompt_sticky": false, "nudge": { "enabled": false } }, "i18n": { "default_lang": "en", "languages": [ "en" ] }, "limits": { "messages_per_minute": 30 }, "links": { "support_email": "help@example.test" }, "notifications": { "banner": true, "banner_throttle": true, "sound": true, "toast_opens": "conversation" }, "onboarding": { "enabled": false, "reshow_hours": 24, "slides": [] }, "origins": [ "https://example.test" ], "policy": { "member": { "call": false, "message": true } }, "presence": { "enabled": true }, "roles": [ { "key": "member", "label": { "en": "Member" }, "seller": false } ], "safety": { "report_reasons": true }, "workspace": { "queue": false } }, "expires_at": "2026-11-01T12:15:00Z", "realtime": { "channel": "/users/0199d6a0-1000-7000-8000-000000000001", "http_host": "example.appsync-api.eu-west-1.amazonaws.com", "ws_url": "wss://example.appsync-realtime-api.eu-west-1.amazonaws.com/event/realtime" }, "session_token": "example-session-token", "user": { "app_prompt_done": false, "avatar": "https://example.test/alice.jpg", "external_id": "alice", "id": "0199d6a0-1000-7000-8000-000000000001", "inbound": "everyone", "kind": "member", "lang": "en", "last_seen": "everyone", "name": "Alice", "notify_prompt_done": false, "onboarding_done": true, "onboarding_shown_at": "2026-11-01T09:00:00Z", "read_receipts": true, "role": "member" }}Problem
An RFC 9457 problem: the body of every error answer.
object
The stable error code to branch on, such as policy_denied.
What went wrong this time, when there is more to say.
For validation, one entry per invalid field.
One invalid field.
object
The path to the field.
What is wrong with it.
The path of the request.
For policy_denied and limit_reached, the rule or limit that refused the request; for forbidden, a short cause such as you_blocked; for banned, temporary when the ban expires.
The HTTP status code.
A short summary of the problem.
A URL that names the problem, https://app.mondochat.io/problems/<code>.
Example
{ "code": "policy_denied", "detail": null, "instance": "/v1/conversations/0199d6a0-2000-7000-8000-000000000001", "reason": "pins", "status": 403, "title": "Policy denied", "type": "https://app.mondochat.io/problems/policy_denied"}