TalqingChat from @talqing/client. You build the UI.
You need: an LLM provider key, a personal access token with the EDITOR role on your server, and a stable id for each signed-in user. Text has no per-minute fee; see pricing.
1. Create and publish the text agent
A chat can only start on a published agent.llm your key covers from GET /v1/catalog. To let a returning user’s next chat remember earlier ones, set conversation.context — see conversation memory.
2. Start the chat and mint a token on your server
app/api/chat/token/route.ts
contact_keyidentifies the person across chats. Derive it from your session, never from browser input. The prefixesphone:,telegram:,whatsapp:,sip:andstream:are reserved.userdatais what the agent knows about them —{{userdata.name}}in the prompt and tools. Because your server writes it, identity comes from your session, not from what the user types. See userdata.- One open chat per contact and agent.
POST /v1/chatsends the existing open one, so look it up first. That also makes this endpoint safe to call on every page load and token refresh.
3. Render the chat
components/Chat.tsx
TalqingChat refetches the token shortly before it expires. What a turn returns:
A chat token never sees tool calls, handoff rows, cost, analysis or userdata. Your server’s token and the dashboard see the full record. Full reference: text conversations and React and client SDK.
4. Decide what ends a chat
An open chat is not analysed and does not sendsession.completed. Left alone, it ends 24 hours after the user’s last message (inactivity_timeout). To end it sooner:
- The agent, with an
end_calltool, when the conversation is over. - The user, with a “New chat” button that calls
chat.end(). - Your server, on a schedule:
GET /v1/chats?status=open, thenPOST /v1/chats/{chat_id}/endfor chats older than you want to keep.
on_exit hook and post-chat analysis, and sends session.completed.
5. Accept files
Send the files and the caption as one message.talqingFileDataUrl encodes a File (downscaling a photo first) and throws a user-facing message when the file is refused.
vision: true), PDFs and Word files; anything else is stored for you and the agent is told it cannot open it. See vision and images.
6. Give the agent a tool that reads your data
Key the lookup onaccount_id from userdata, which your server set, so the model cannot ask about another account.
get_account_summary.json
NORTHWIND_INTERNAL_TOKEN secret first. Saving the tool warns that {{userdata.account_id}} is read but never written by a tool; that is expected, because your token route sets it. Then attach the tool with PATCH /v1/agents/{agent_id} — {"config": {"tools": [{"tool_id": "…"}]}}, including any tools already attached, since the list is replaced whole — and publish the agent again. See versions.
7. Escalate to a person
Text has no transfer to a human: thetransfer operation works only on phone calls. A person at your business can still answer inside an open chat by posting agent_text, sent as the agent’s message. Escalation is a routing decision your server owns — the agent files a ticket, and your app stops minting tokens for that user and routes them to your support desk.
POST /v1/chats/{chat_id}/end.
Test it
- Use Test chat on the agent’s page in the dashboard before wiring anything.
- Send from your page and watch
events:assistant.started, deltas,assistant.completed,turn.result. - Reload mid-chat. The same transcript should repaint; an empty panel means your token route started a new chat instead of reusing the open one.
- Sign in as a second user. Each should see only their own history.
- Ask something only the tool knows, then confirm the
function_callitem inGET /v1/chats/{chat_id}/itemswith your workspace token. - End the chat.
GET /v1/chats/{chat_id}showsstatus: "ended", thenanalysisa few seconds later.
Limits of this setup
- Every chat needs your server to start it and mint its token; there is no public agent id a browser can use.
- No typing indicator or read receipts are reported on web; the “Thinking…” state is inferred from the request in flight.
- Each turn re-sends the whole chat to the model, so long threads grow input-token cost on your key.
Next
Text conversations
Chats, streaming, items and browser tokens in full.
React and client SDK
Every export of @talqing/client and @talqing/react.