AI assistant in your app
Put a Claude-powered assistant inside your own app. It answers your users' questions, looks things up in your app with tools you define, finds the right page, answers from your organisation's documents, and makes changes only after the person presses Confirm on a card. People can type or talk to it. Appsocom runs the model, the conversation, the safety checks and the billing; your app keeps its own data and decides what each person may do.
This page is about an assistant inside your app. To connect Claude, ChatGPT or another assistant to your Appsocom account, see AI assistants (MCP).
How it works
- Once, from your server: tell the assistant about your app: its name, your instructions, the tools it may call, the pages of your app, and the address (
toolsUrl) where your server runs those tools. - For each signed-in person: your server mints an assistant token that says who they are, their role, and what they may use. The browser or phone app uses that token to chat.
- When the assistant needs data: Appsocom calls your
toolsUrl, signed with your webhook secret, as that person. Your server checks the signature, runs the tool with that person's permissions, and returns the result.
The assistant never sees your database or your API keys. It only gets what your tools return, for the person who asked.
You need an API key from the console and a webhook set on the project, because tool calls are signed with the webhook's secret.
Set it up
PUT /assistant/config replaces the whole configuration. GET /assistant/config reads it back. Both use your project's API key.
curl -X PUT https://api.appsocom.dev/assistant/config \
-H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" -d '{
"name": "Ada",
"instructions": "You help parents and staff at Hilltop School. Fees are in naira.",
"toolsUrl": "https://your-app.example/assistant-tools",
"tools": [
{ "name": "list_unpaid_invoices", "description": "Unpaid invoices for one of the parent'"'"'s children. Returns invoice number, term and amount.",
"parameters": { "type": "object", "properties": { "child": { "type": "string" } }, "required": ["child"] },
"risk": "read", "pinned": true, "cacheSeconds": 60 },
{ "name": "cancel_invoice", "description": "Cancel one invoice.",
"parameters": { "type": "object", "properties": { "invoiceId": { "type": "string" } }, "required": ["invoiceId"] },
"risk": "destructive", "summary": "Cancel invoice {invoiceId}" }
],
"appMap": [
{ "label": "Fees", "path": "/fees", "description": "Invoices, receipts and payment plans", "aliases": ["bursary", "school fees"] }
],
"defaultTier": "standard",
"roleTiers": { "staff": "smart" },
"handOver": { "label": "Contact the office", "path": "/messages/new", "notify": true },
"dailyBudgetUsd": 3
}'| Field | What it does |
|---|---|
name |
What the assistant calls itself. At most 60 characters. |
instructions |
Your app's own rules, context and tone, added after Appsocom's rules. At most 8,000 characters. |
tools |
Up to 300 tools your server runs. |
toolsUrl |
The https address that runs your tools. Required when there are tools. |
appMap |
Up to 300 pages of your app the assistant may point people to. |
defaultTier |
"standard" (default), "smart" or "best". See Quality tiers. |
roleTiers |
A tier per role, for example { "staff": "smart", "parent": "standard" }. Up to 50 roles. |
knowledge |
Answer from the project's knowledge base. Default true. |
retentionDays |
Days a conversation is kept after its last message, 1 to 730. Default 90. |
dailyBudgetUsd |
Stop answering for the rest of the UTC day once the assistant has cost this much, in US dollars. See Limits. |
handOver |
Let the assistant hand the person to your staff. |
A bad value is refused with 400 and a message that names the field. Changes take effect within 30 seconds.
Assistant tokens
Your server mints a token for each signed-in person with POST /assistant/tokens and gives it to their browser or app. Never give your API key to a browser.
curl -X POST https://api.appsocom.dev/assistant/tokens \
-H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" -d '{
"userId": "u_42", "name": "Ngozi Okafor", "role": "parent",
"context": "School: Hilltop School, Lagos. Term: First term 2026/27.\nChildren: Ada (JSS2), Tobi (Primary 4).",
"metadata": { "school": "hilltop" },
"monthlyMessages": 200
}'
# → {"token":"eyJ…","conversationId":"5b0c…","expiresAt":1763560000}| Field | What it does |
|---|---|
userId |
Required. Your id for the person (letters, numbers, . _ : @ -, up to 128). |
name |
Shown to the model, so it can address them. |
role |
Their role in your app. It picks the tier from roleTiers and is sent with every tool call. |
context |
What your app knows about this person that the assistant should always have: their organisation and term, the classes they teach, the children they follow, modules that are switched off. Plain lines, at most 3,000 characters. It is given to the model with who they are. It is inside the signed token, which the person can read, so never put a secret here. |
conversationId |
Continue an earlier conversation. A new one is started when you leave it out, and its id comes back. |
tools |
Only these of your tools (by name). Leave it out for all of them. |
paths |
Only the pages of your app map under these paths. |
tier |
Overrides the role's tier for this person. |
retentionDays |
Keep this conversation fewer days than the project's setting. |
monthlyMessages |
This person's cap on billed messages per calendar month (UTC). |
metadata |
Your own ids, string values, at most 2 KB. Sent back with every tool call. |
instructions |
This conversation's own role and rules, used in place of the project's instructions: for a conversation that is not your app's general assistant, such as a tutor on one topic. At most 6,000 characters. Appsocom's own rules still apply. Pair it with "tools": [] and "paths": [] for a conversation with no tools and no pages, and a conversationId of your own (one per lesson, say). |
reportUsage |
Add the tier, billed units, cost and tokens to each answer's done event. For a backend that relays answers and bills its own customers. Leave it off for tokens a browser holds. |
ttlSeconds |
How long the token works: 60 to 43,200 seconds. Default 3,600. |
A person can only reach their own conversation: the conversation is chosen by the project, the userId and the conversationId in the signed token. Assistant tokens can't be used to join calls, and join tokens can't be used to chat.
Show it in your app
The SDKs give you a ready-made panel, or a hook or client to build your own. Each takes the API URL and the person's token (or a function that returns a fresh one).
// React (web): @appsocom/react
import { AssistantPanel } from "@appsocom/react";
<AssistantPanel
url="https://api.appsocom.dev"
token={() => fetch("/api/assistant-token").then((r) => r.text())}
page={location.pathname}
suggestions={["What do I owe this term?", "Where do I download report cards?"]}
onOpenPage={(path) => navigate(path)}
voice
/>| Platform | Package | What you get |
|---|---|---|
| React (web) | @appsocom/react |
AssistantPanel, the useAssistant hook, useAssistantVoice, and AssistantClient for a UI of your own |
| React Native | @appsocom/react-native |
AssistantPanel and useAssistant |
| Flutter | appsocom_flutter |
AssistantPanel and AssistantController (a ChangeNotifier) |
The panel streams answers, shows the cards (open a page, confirm a change, contact a person), keeps the conversation when the page reloads, and has thumbs up and down on every answer. Pass page (the path the person is on) so "this page" means something to the assistant. The microphone button (voice) is in the React panel; on other platforms use the voice API directly.
The chat API
If you build your own client, these routes take the person's assistant token as Authorization: Bearer …:
| Route | What it does |
|---|---|
POST /assistant/chat |
{"message", "page"?, "attachments"?}. One answer, streamed as server-sent events. Messages are at most 8,000 characters. See Attachments. |
GET /assistant/conversation |
The answers so far (answers) and any changes still waiting for a confirm (pending). |
POST /assistant/approvals/:approvalId |
{"decision": "confirm" | "cancel", "page"?}. Answers a change card. |
POST /assistant/feedback |
{"answerId", "rating": "up" | "down", "comment"?}. |
POST /assistant/voice, DELETE /assistant/voice |
Start or end a voice call. |
Attachments
A message can carry up to 8 attachments, each either a file or text:
- A file:
{"name", "type", "data"}withtypeone ofimage/png,image/jpeg,image/gif,image/webporapplication/pdf, anddatain base64. Images at most 5 MB each, PDFs 10 MB, 15 MB in all. The model sees the file itself. - Text:
{"name", "text"}, for a document your app has already read (a spreadsheet or Word file, say) or a record the person tagged. At most 150,000 characters in all. It goes with the message, marked as data rather than instructions.
The message may be empty when it has attachments. Attachments go to the model with that one message and are not stored: the conversation keeps a line naming them, so send them again with a later question about them. They add input tokens, so a heavy message is billed as two on Standard.
The chat stream sends these events:
| Event | Data |
|---|---|
text |
{"text"}, the next piece of the answer |
card |
Something to show under the answer: {"type":"open_page","path","label"}, {"type":"approval","approvalId","tool","risk","summary","expiresAt"} or {"type":"hand_over","label","path"?} |
applied |
First event after a confirm: {"approvalId","ok"} |
done |
{"answerId"}. With a reportUsage token also tier, units (billed messages), costMicros (millionths of a US dollar) and usage (the model and its token counts). |
error |
{"error"} |
One answer is written at a time in a conversation. A second message while one is being written gets 409.
Tools
A tool is something your server can do for the person: look up their invoices, list a class, book a meeting. You describe each one, and the model decides when to call it.
| Field | What it does |
|---|---|
name |
1 to 64 letters, numbers, _ or -, starting with a letter. find_tools, search_knowledge, open_page and hand_over are taken. |
description |
Written for the model: when to use it and what it returns. At most 1,024 characters. |
parameters |
A JSON Schema of the arguments, at most 8 KB. |
risk |
"read" (default), "write", "destructive" or "bulk". Only read tools run straight away. |
summary |
The sentence on the confirm card, with {argument} filled in, for example "Cancel invoice {invoiceId}". |
pinned |
Always offered to the model, even when you have many tools. |
assistantAllowed |
false keeps the tool in your list but the assistant never runs it. |
cacheSeconds |
read tools only, 1 to 3,600: the same person asking with the same arguments reuses the result for this long. A confirmed change in the conversation clears it. |
With 24 tools or fewer, every tool is offered on every turn. With more, the model gets your pinned tools and a find_tools tool that finds up to 8 more by matching words in their names and descriptions, so good descriptions matter.
What your toolsUrl receives
Each call is a POST with a JSON body, signed in the X-SfuKit-Signature header exactly like webhooks:
{
"type": "tool_call",
"kind": "assistant",
"conversationId": "5b0c…",
"userId": "u_42",
"role": "parent",
"callId": "toolu_01…",
"name": "list_unpaid_invoices",
"arguments": { "child": "Ada" },
"metadata": { "school": "hilltop" }
}Reply with 200 and {"result": …} (a string or any JSON), or {"error": "…"} to tell the model what went wrong. Run every tool as userId, with that person's permissions in your app: the model chooses the arguments, so never trust them to stay inside what the person may see. Keep results small; the first 16,000 characters are read. Your server has 15 seconds to answer, and redirects are not followed.
A confirmed change also has approvalId and approvedAt, with the same callId as when it was proposed. Use callId to make sure a change runs only once.
SDK helpers
Every server SDK (0.7.0 and later) can answer your toolsUrl for you: it checks the signature (5 minutes' tolerance), runs the matching handler with the arguments and the call, and replies in the right shape. A handler that throws an AssistantToolError shows its message to the model; any other error is shown only as "The tool failed." and passed to your onError.
// Node: @appsocom/node
import { SfuKit, assistantTools, AssistantToolError } from "@appsocom/node";
const kit = new SfuKit({ url: "https://api.appsocom.dev", adminKey: process.env.APPSOCOM_API_KEY! });
const { token } = await kit.createAssistantToken({ userId: user.id, name: user.name, role: user.role });
const tools = assistantTools(process.env.APPSOCOM_WEBHOOK_SECRET!, {
list_unpaid_invoices: async ({ child }, call) => db.unpaidInvoices(call.userId, child),
cancel_invoice: async ({ invoiceId }, call) => {
if (!(await db.canCancel(call.userId, invoiceId))) throw new AssistantToolError("You can't cancel that invoice.");
return db.cancelInvoice(invoiceId, { once: call.callId });
},
});
app.post("/assistant-tools", express.text({ type: "*/*" }), async (req, res) => {
const out = await tools.handle(req.body, req.get("x-sfukit-signature"));
res.status(out.status).type("application/json").send(out.body);
});
// Or, where handlers take a web Request: export const POST = (req: Request) => tools.fetch(req);| Language | Helper | Config and tokens |
|---|---|---|
| Node | assistantTools(secret, handlers), .handle() or .fetch() |
setAssistantConfig, getAssistantConfig, createAssistantToken, deleteAssistantConversation, getAssistantUsage |
| Python | assistant_tools(secret, handlers), .handle(raw_body, signature) returns (status, body) |
set_assistant_config, get_assistant_config, create_assistant_token, delete_assistant_conversation |
| PHP | new SfuKit\AssistantTools($secret, $handlers), ->handle($rawBody, $signature) returns [$status, $body] |
setAssistantConfig, getAssistantConfig, createAssistantToken, deleteAssistantConversation |
| Go | sfukit.NewAssistantTools(secret, handlers) is an http.Handler |
SetAssistantConfig, AssistantConfig, CreateAssistantToken, DeleteAssistantConversation |
| Dart | AssistantTools(secret, handlers), .handle(rawBody, signature) |
setAssistantConfig, getAssistantConfig, createAssistantToken, deleteAssistantConversation |
Pass the raw request body to the helper: the signature is over the exact bytes.
Changes need a confirm
A tool with risk "write", "destructive" or "bulk" never runs when the model calls it. Instead:
- The assistant proposes it. The person sees a card with your
summary(or the tool's name and arguments) and Confirm and Cancel, and the assistant asks them to confirm. - Confirm sends the call to your
toolsUrlonce, withapprovalId. The assistant then tells the person what happened. Cancel runs nothing.
The approval is bound to the tool and its exact arguments (a SHA-256 of both), so nothing can change between the card and the call. It can be answered once, only by the same person, and waits 10 minutes; after that it expires and the person asks again. Before running a confirmed change, Appsocom checks again that the tool still exists, is still allowed for that person, and still changes something. One answer can propose at most 3 changes. A spoken "yes" never confirms a change: during a voice call the card appears on screen.
Built-in tools
The assistant also has these, without any work on your side:
| Tool | When it's there | What it does |
|---|---|---|
find_tools |
More than 24 tools | Finds more of your tools for the task. |
open_page |
You have an app map | Shows a button that opens a page from your app map, or a record page under one. |
search_knowledge |
knowledge is on |
Searches the project's knowledge base (5 passages a search) and names the document it quotes. |
hand_over |
You set handOver |
Hands the person to your staff. |
Pages of your app
The app map tells the assistant where things are, so it can say "Fees, under Payments" and offer a button instead of guessing. Each page has a label (at most 80 characters), a path starting with /, an optional description and up to 12 aliases, the other names people use ("bursary" for Fees). The assistant only offers pages from the map, or record pages under them (/students/123 under /students). A token's paths narrows the map for one person.
The panel opens a page with your onOpenPage, or a normal link when you don't set it.
Hand-over to people
With handOver, the assistant can pass the person to your staff when they ask for a human, complain, or need something it can't do. It shows a button with your label that opens path. With "notify": true it also calls your toolsUrl with the tool name hand_over and {"reason": "…"}, a sentence for your staff, so you can open a ticket or alert someone. notify needs a toolsUrl.
Knowledge
When knowledge is on (the default), the assistant searches the project's knowledge base: your approved policies, handbooks and FAQs. It says which document an answer comes from. Typed answers and voice calls both search it.
Voice
People can talk to the same assistant. POST /assistant/voice (with the person's token, and {"page"} if you like) starts a one-to-one voice room with an AI Agent built from the same settings, and returns {roomId, token, expiresAt, agentId, cardTopic}. Join the room with that token (microphone only). DELETE /assistant/voice ends the call. If the person stays quiet for 40 seconds the agent asks if they're still there, and 40 seconds later it says goodbye and leaves.
- It uses the same instructions, app map, the person's own tools (pinned first, at most 30), approvals, hand-over and conversation. What was said is saved in the conversation, so the person can switch between typing and talking.
- Cards (open a page, confirm a change, contact a person) and each finished line of the call arrive as room data messages on the topic in
cardTopic(assistant.card). - Standard talks with Claude Haiku 5.5; Smart and Best talk with Claude Sonnet 5.5, for speed.
- Speech to text is Deepgram, and the voice is Cartesia on the hosted service.
- Voice is billed as AI Agent minutes, needs the AI Agent to be available on the project (so not on the free plan), and its model calls count toward the daily cap.
The React panel does all of this with voice; useAssistantVoice gives you the same for your own UI.
Quality tiers
| Tier | Answers with | Moves up to | Steps per answer |
|---|---|---|---|
| Standard | Claude Haiku 5.5 | Claude Sonnet 5.5 | 8 |
| Smart | Claude Sonnet 5.5 | Claude Opus 5.5 | 20 |
| Best | Claude Opus 5.5 | 30 |
A step is one model call; tools run between steps. When an answer needs a chain of more than 3 rounds of tool calls, Standard and Smart move up to the stronger model for the rest of that answer. When the steps run out, the assistant answers once more without tools, so the person always gets a reply.
The tier comes from the token's tier, else the role in roleTiers, else defaultTier. On the free plan every message is Standard.
Long conversations stay cheap and on topic: the newest exchanges (about 15,000 tokens) go to the model in full, and older ones are summarised by Claude Haiku 5.5 after the answer is sent.
Billing and prices
Each answer is one billed message on the tier that answered it, charged to the project's prepaid credit:
| Tier | Price per message |
|---|---|
| Standard | $0.0033 |
| Smart | $0.04 |
| Best | $0.10 |
- Fair use: a Standard message that needed more than 20,000 prompt tokens or more than 4 model calls in total counts as 2.
- Free: every account gets 100 Standard messages a month, shared by its projects. Smart and Best need credit.
- Voice is billed as AI Agent minutes ($0.027 a minute), not per message.
- Cancelling a change card isn't a message. Confirming one is, because the assistant writes a reply.
These prices are for the pilot and will be reviewed after it. Prices in other currencies are on the console's Billing page.
Limits and caps
| Limit | What happens |
|---|---|
| Daily spending cap | Once the assistant has cost the project its cap in a UTC day, it answers 429 ("reached its daily limit") until midnight UTC. The cap is your dailyBudgetUsd, never above Appsocom's own cap per project (US$5 a day by default). |
| A person's month | With monthlyMessages in the token, that person gets 429 ("used this month's assistant messages") when they reach it. |
| Plan | On a blocked or paused project, or past the free messages without credit, token minting and chat answer 403. |
| One answer at a time | 409 while an answer is being written in the same conversation. |
Usage and the audit log
GET /assistant/usage?days=7(API key, 1 to 90 days): messages, cost, models, tiers, thumbs up and down, each tool's calls, failures and time, approvals and hand-overs, plus today's spending and the daily cap. The console shows the same under the project's AI assistant section.GET /assistant/audit?day=YYYY-MM-DD&conversationId=…(API key): every proposed change, confirm, cancel, result and hand-over that day, with who, when, the tool, its arguments and its result (shortened to 2,000 characters). Up to 500 events per request.
Your data
- Conversations (messages, tool calls and their results, the answers, thumbs and comments, and what was said in voice calls) are kept in the conversation's own store and deleted automatically
retentionDaysafter the last message (90 by default; a token can ask for fewer). - Delete one now with
DELETE /assistant/conversations/:userId/:conversationId(API key), for example when a person asks you to. - The audit log is kept in the project's storage so you can show who approved what. It is not deleted when a conversation is.
- Voice calls are not recorded; only the words, as text, are saved in the conversation.
- The model is Claude, from Anthropic. Messages, your instructions, the person's
context, tool results and knowledge passages are sent to Anthropic's API to write each answer. Voice uses Deepgram for speech to text and a voice provider such as Cartesia. See the Data processing agreement. - Tool results, documents and records are treated as data, never as instructions: the assistant is told so, and a change still needs the person's confirm.