Chat module

Chat inside your app

Your server signs a short-lived token for each user. Chatmode keeps the thread. You choose who draws the chat.

Create your account API docs
The token

One token, two doors

Sign HS256 with the channel identity secret. The same sub stays the same person. Use the token in the embed, or exchange it for a guest session.

HS256 Within 24 hours
iss
workspace / channel
sub
Your user id
name
Display name
exp
Within 24 hours
01 Fastest Team in Chatmode 02 Your screen Your own screen

01 · Fastest

Your users chat. Your team replies in Chatmode.

Add the embed and pass the signed token. A known user opens their own thread. Agents reply from the Chatmode inbox, with assignment, templates, automatic replies, and a satisfaction rating.

<script src="/embed.js"
  data-workspace="…"
  data-channel="…"
  data-user-token="eyJ…">
</script>

The embed snippet does not include an API key.

02 · Your screen

Draw the chat in your own interface.

Your server calls the visitor session endpoint with a workspace API key that can write guests, plus the same user token. The response is a guest bearer and a websocket path. Each call issues a new bearer.

Browser calls need the origin on the channel allowlist. Server-to-server calls work without that list.

API docs
POST /api/v1/visitor/session
  • API keyguests:write
  • Rate limit60 req/min
200 You receive
  • Guest bearerbearer
  • socket/ws/…

03 · Your backend

Your app drives the agent side.

Subscribe to signed webhooks for new and updated messages, assignment, resolve and reopen, satisfaction ratings, and template button clicks. Post replies with the API. Users can still enter through the embed or a visitor session.

  1. message.createdSigned
  2. message.updatedSigned
  3. thread.assignedSigned
  4. thread.resolvedSigned
  5. thread.reopenedSigned
  6. csat.submittedSigned
  7. template.button_clickedSigned

04 · Open visitors

A bubble for people who are not logged in.

The same embed without a user token asks for a display name. Use it on a public page, then pass the token once that person has an account in your app.

Display name
Visitor
Your user id
Support

Start with a workspace

Create the channel, then sign tokens for your users.

Create your account API docs