APPSOCOMDocs

Chat and Ticket Support

Messaging for your app: one-to-one chats, group chats, and support chats that work as tickets. Messages arrive instantly over a WebSocket, with files, replies, read receipts and "typing…". For support, the AI assistant can answer first from your Knowledge and hand the chat to your team when a person is needed. Every ticket has a number, a status, a priority, tags, an assignee and a history of who changed what.

Your app decides who may talk to whom. Your server makes the conversations and gives each person a chat token; their browser or phone app uses the token for everything else.

How it works

  1. Once, from your server: choose the settings with PUT /chat/config (retention, file size, support with or without the AI).
  2. When your app needs a conversation: your server makes it with POST /chat/conversations: a direct chat between two people, a group, or a support ticket.
  3. For each signed-in person: your server mints a chat token with POST /chat/tokens. Support staff get "role": "agent".
  4. In the browser or app: the person lists their conversations, reads and posts messages, and keeps a WebSocket open for new ones.
  5. When someone isn't looking: Appsocom sends your server a chat_message webhook listing the members who didn't see it, so you can send a push notification or an email.

Set it up

bash
curl -X PUT https://api.appsocom.dev/chat/config \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" -d '{
  "retentionDays": 365,
  "maxFileMB": 10,
  "messageWebhooks": "offline",
  "support": { "ai": true, "aiName": "Ada", "greeting": "Hi! How can I help?", "knowledge": "faq", "handOverLabel": "Talk to a person" }
}'
Setting What it does
retentionDays Messages older than this are deleted, with their files. 1 to 3650, default 365.
maxFileMB Largest file a person can send. Default 10, at most 25.
dailyMessages Most messages your project may post in a UTC day. Default and ceiling 20,000.
messageWebhooks offline (default): a chat_message webhook when a member didn't have the chat open. all: every message. none.
support.ai The AI assistant answers support chats first. Default off.
support.aiName, support.greeting The AI's name in the chat, and its first message in a new support chat.
support.knowledge The Knowledge collection the AI answers from (a person's token can name another).
support.tier standard, smart or best. Default: your assistant's default tier.
support.aiTools Let the AI use your assistant's tools as the person. Default off: it answers from Knowledge only.
support.handOverLabel, support.title The hand-over button's label, and the title of new support chats.

GET /chat/config reads the settings back.

Conversations

bash
# A group
curl -X POST https://api.appsocom.dev/chat/conversations \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" -d '{
  "type": "group", "title": "JSS1 parents",
  "members": [{ "userId": "u1", "name": "Ada Obi" }, { "userId": "t9", "name": "Mr Bello", "role": "owner" }],
  "metadata": { "class": "jss1" }
}'
  • direct has exactly two members. Asking again for the same two people returns the same conversation, with "existing": true.
  • group has up to 500 members. Add or change one with PUT /chat/conversations/:id/members, remove one with DELETE /chat/conversations/:id/members/:userId. A member may leave by themselves.
  • support is a ticket (see below).

Your server can also list conversations (GET /chat/conversations?userId=&type=&status=&assignee=&priority=), change one (PATCH /chat/conversations/:id with title, status, assignee, priority, tags, metadata), post into one (POST /chat/conversations/:id/messages: with no userId it is a system note like "Term starts on Monday", with a member's userId it is posted as them) and delete one with all its messages and files (DELETE /chat/conversations/:id). Closing a direct or group chat ("status": "closed") keeps it readable but stops new messages.

Tokens

bash
curl -X POST https://api.appsocom.dev/chat/tokens \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
  -d '{ "userId": "u1", "name": "Ada Obi", "ttlSeconds": 3600 }'
# → { "token": "eyJ…", "expiresAt": 1795190000 }
Field
userId, name Who this is. The name shows next to their messages.
role member (default) or agent: agents also see and answer the support queue.
knowledge Support chats this person opens answer from this Knowledge collection, for an app with many customers (one school's documents per school).
metadata Kept on support chats this person opens, and sent back in webhooks (string values, at most 2 KB).
ttlSeconds Default one hour, at most 24 hours.

In the browser or app

All of these take the person's token as Authorization: Bearer <token>.

GET /chat/inbox Their conversations, newest activity first, each with unread and the last message; unread in total.
GET /chat/conversations/:id/messages?before=&after=&limit= Messages, oldest first. seq numbers them 1, 2, 3…
POST /chat/conversations/:id/messages { "text": "…", "attachments": ["f_…"], "replyTo": "msg_…" }
PATCH / DELETE /chat/conversations/:id/messages/:messageId Change or delete your own message.
POST /chat/conversations/:id/read { "seq": 12 }: read up to here (the others see a read receipt).
POST /chat/conversations/:id/files The file's bytes, with Content-Type and X-File-Name. Returns { file: { id, name, type, size } }: put the id in a message's attachments.
GET /chat/conversations/:id/files/:fileId Download. ?token= works too, for <img src>.
GET /chat/conversations/:id/ws?token= WebSocket for one open conversation.
GET /chat/ws?token= WebSocket for everything else: activity in any of their conversations (and, for agents, the queue).
js
const ws = new WebSocket(`wss://api.appsocom.dev/chat/conversations/${id}/ws?token=${token}`);
ws.onmessage = (e) => {
  const ev = JSON.parse(e.data);
  // ev.type: "message", "message_updated", "read", "typing", "conversation", "members"
};
input.oninput = () => ws.send(JSON.stringify({ type: "typing" }));
ws.send(JSON.stringify({ type: "read", seq: lastSeenSeq }));

The inbox socket sends { type: "ready", unread } when it opens, then activity (a new message somewhere, with a preview), conversation (a conversation changed), removed, and for agents queue. Send { "type": "ping" } every 30 seconds or so to keep a socket open through proxies.

A person may post 30 messages a minute in one conversation. Messages are up to 4,000 characters, with up to 10 files.

Ticket Support

A support chat is a ticket. It has a number (1001, 1002… per project, for people to quote), a priority (low, normal, high, urgent), tags, an assignee and a status:

Status Meaning
bot The AI assistant is answering (only with support.ai on).
waiting In your team's queue, waiting for a person.
open An agent has it.
closed Done. If the person writes again, it reopens: to the same agent if it had one.

Opening one. The person opens it themselves with their token: POST /chat/support with { "text": "How much are the fees?", "subject": "Fees" }. Your server can open one too, with POST /chat/conversations and "type": "support" (and priority, tags).

The AI first. With support.ai on, the AI answers each message while the ticket is bot, from your Knowledge, as the AI assistant does in your app. When the person asks for a human, is unhappy, or the AI can't help, it hands over: the ticket becomes waiting, the chat says "Connecting you to a person", and you get a chat_support_waiting webhook. The person can also ask for a person at any time (POST /chat/conversations/:id/handover, for your "Talk to a person" button). If the AI can't answer (its daily cap, say), the ticket goes to your team too. Once an agent has the ticket the AI stays quiet.

Agents (tokens with "role": "agent"):

GET /chat/queue?status=waiting Tickets by status (waiting by default; also bot, open, closed), with priority= and assignee= (none for unassigned) filters.
POST /chat/conversations/:id/claim Take a ticket. Replying to an unassigned ticket takes it too.
PATCH /chat/conversations/:id status, assignee (transfer: the new agent joins the chat), priority, tags, title.
POST /chat/conversations/:id/close / reopen The person may close their own ticket too.
GET /chat/conversations/:id/history Who changed what and when: created, status, assignee, priority, tags, members.
GET /chat/tickets/:number A ticket by its number (1001 or T-1001).

Agents can read every ticket, and delete messages in tickets. Your server can do all of this with your API key (claim then takes { "userId", "name" } for the agent).

Tickets by email

Give Chat a support mailbox on Appsocom Mail (for example help@yourschool.com) and email becomes another way in:

  • A new email opens a ticket (channel: "email"), titled with its subject. The sender joins as a member (userId email:<address>), and the email's files are attached, up to your maxFileMB.
  • Replies stay in their ticket. An email answering one of the ticket's emails joins it, and so does one from the same person with the ticket's number in the subject ([#1001]). Quoted earlier text is left out.
  • What your team writes goes back by email: an agent's reply, or the AI's answer while the ticket is with the AI, is sent from the support mailbox to the person, in the same email thread, with the subject Re: <subject> [#1001] and any files attached. System notes are not emailed. If an email can't be sent, the ticket says so.
  • The AI answers first and hands over exactly as in a chat, so an emailed question can be answered in under a minute.
  • Auto-replies, mailing lists and the mailbox's own mail never open tickets.
bash
curl -X PUT https://api.appsocom.dev/chat/email \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" \
  -d '{ "address": "help@yourschool.com", "password": "<the mailbox password>", "name": "Bright School" }'

Live signs in to the mailbox straight away, so a wrong address or password is refused there and then. The password is kept encrypted and never shown again; send PUT again without it to change name or enabled, or with it after you change the password. name is shown as the sender ("Grace at Bright School").

GET /chat/email The mailbox, whether it's on, when it was last checked, the last error and the emails read so far.
POST /chat/email/poll Check the mailbox now. It is also checked every minute by itself.
DELETE /chat/email Stop email tickets (the tickets stay).

Emails are read from the mailbox's Inbox, 25 at a time, and marked as read there. Use a mailbox just for support: everything that arrives in it becomes a ticket. Each email read counts as one chat message, like any other message; sending replies costs nothing extra.

Webhooks

Chat events go to your project's webhook, signed the same way. roomId is the conversation's id, and chat holds the details.

Event When chat
chat_message A message was posted and a member didn't have the chat open (or every message, with messageWebhooks: "all"). conversation, message, offline (userIds who didn't see it)
chat_conversation A conversation was created, updated, claimed, closed, reopened or deleted. conversation, change, by
chat_support_waiting A ticket is waiting for your team. conversation

Server SDKs

ts
import { SfuKit } from "@appsocom/node";
const kit = new SfuKit({ url: "https://api.appsocom.dev", adminKey: process.env.APPSOCOM_API_KEY! });

await kit.setChatConfig({ support: { ai: true, aiName: "Ada" } });
const { conversation } = await kit.createChatConversation({ type: "direct", members: [{ userId: "u1", name: "Ada" }, { userId: "t9", name: "Mr Bello" }] });
const { token } = await kit.createChatToken({ userId: "u1", name: "Ada" });
await kit.postChatMessage(conversation.id, { text: "Report cards are ready." });
const ticket = await kit.getTicket(1001);
await kit.setChatEmail({ address: "help@yourschool.com", password: process.env.SUPPORT_MAILBOX_PASSWORD!, name: "Bright School" });
go
client := sfukit.NewClient("https://api.appsocom.dev", os.Getenv("APPSOCOM_API_KEY"))
tok, err := client.CreateChatToken(ctx, sfukit.ChatTokenRequest{UserID: "u1", Name: "Ada", Role: "agent"})
conv, err := client.CreateChatConversation(ctx, sfukit.CreateChatConversation{Type: "group", Title: "JSS1 parents", Members: members})
queue, err := client.ListChatConversations(ctx, sfukit.ChatConversationFilter{Type: "support", Status: "waiting"})

Usage and price

GET /chat/usage?days=30 (API key) shows messages per day and conversations by type and status. The console shows the month's chat messages with your other meters.

Each message posted counts once, whoever posts it (a person, the AI or your server); system notes like "Grace joined the chat" are free. 10,000 messages a month are free for each account, then $0.013 per 1,000 messages. Files count as file sharing. The AI's answers in support chats are also billed as AI assistant messages and count toward its daily cap.

Private Cloud deployments have chat too, on their own Cloudflare account and their own AI keys.