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
- Once, from your server: choose the settings with
PUT /chat/config(retention, file size, support with or without the AI). - When your app needs a conversation: your server makes it with
POST /chat/conversations: adirectchat between two people, agroup, or asupportticket. - For each signed-in person: your server mints a chat token with
POST /chat/tokens. Support staff get"role": "agent". - In the browser or app: the person lists their conversations, reads and posts messages, and keeps a WebSocket open for new ones.
- When someone isn't looking: Appsocom sends your server a
chat_messagewebhook listing the members who didn't see it, so you can send a push notification or an email.
Set it up
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
# 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 withDELETE /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
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). |
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 (userIdemail:<address>), and the email's files are attached, up to yourmaxFileMB. - 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.
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
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" });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.