Everything you can click is an endpoint
Takallam is a REST API with a support product built on top of it. Create and configure agents, push knowledge, start and read conversations, subscribe to signed webhooks, and ship the chat embed in one line. The base URL is https://api.takallam.ai/v1
What you can drive from code
The console is a client of the same API you get. If it exists in the product, there is an endpoint behind it.
REST over HTTPS
Predictable resources, JSON in and out, standard verbs, and cursor pagination on every list. The key travels in an Authorization header.
Agents
POST /agents to create one, PATCH it to change persona, languages, permissions or channels. The agent id is the handle for everything after that.
How agents are builtKnowledge
Push a URL, a document or a set of records to /agents/{id}/knowledge. Replace a source or delete it and the agent stops using it.
Conversations
Start one from your own frontend, or read the ones that arrived over QR, chat, email and phone. Channel, language and outcome sit on the same record.
Inside the support consoleWebhooks
Signed events for conversations, escalations, tickets and workflow runs, delivered to your endpoint and retried when it is not answering.
Embed and SDKs
A script tag for the web, native SDKs for iOS and Android. Same agent, same knowledge, same conversation record as the phone line.
Create an agent, expose it, done
One POST creates the agent and puts it on the channels you name. The response gives you the id you use for knowledge, conversations, webhooks and the embed.
- PATCH the same resource to change persona, languages or escalation rules — no redeploy, no new id.
- Agents are created as drafts. Nothing reaches a customer until you publish.
- Channels are fields on the agent, not four separate integrations.
# Create an agent and expose it on all four channels
curl https://api.takallam.ai/v1/agents \
-H "Authorization: Bearer $TAKALLAM_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Layla",
"role": "reservations",
"languages": ["ar-AE", "en"],
"knowledge_base": "kb_live",
"channels": {
"qr": { "mode": "voice_first" },
"chat": { "embed": true },
"email": { "address": "[email protected]" },
"phone": { "number": "+971 4 555 0180" }
},
"escalate_when": ["low_confidence", "refund_requested"]
}'
# => { "id": "agt_8fk21", "status": "draft" }Feed it, then read back what happened
Knowledge goes in on the agent. Conversations come out on their own resource, whichever channel they arrived on.
Push knowledge
POST a URL, a file or a set of records to /agents/{id}/knowledge. The agent uses it on the next turn — there is nothing to rebuild and nothing to redeploy.
Keep it current
Re-crawl a section of your site on your own schedule, replace a document when a rate changes, or delete a source that should no longer be answered from.
Start a conversation
Building your own frontend, or posting email in from a mail pipeline you already run? POST /conversations with the agent id and take the reply back as JSON. It still lands in the same inbox and escalates to the same team.
The email channelRead what happened
GET /conversations, filter by agent, channel, language or outcome, and page through with a cursor. Escalations and tickets hang off the same record.
Subscribe once, then react
Tell Takallam where to send events and which ones you want. Every delivery is signed, so you can verify it came from us before you act on it.
- Conversation, escalation, ticket and workflow-run events.
- Verify the signature over the raw body before you parse it.
- Failed deliveries are retried, so handlers should be idempotent.
# Subscribe an endpoint to the events you care about
curl https://api.takallam.ai/v1/webhooks \
-H "Authorization: Bearer $TAKALLAM_KEY" \
-d '{
"url": "https://example.com/hooks/takallam",
"events": ["conversation.completed", "conversation.escalated",
"ticket.created", "workflow_run.failed"]
}'
# Every delivery is signed. This is the body you receive:
{
"id": "evt_3c19a",
"type": "conversation.escalated",
"created_at": "2026-05-12T09:41:07Z",
"data": {
"conversation_id": "cnv_71b40",
"agent_id": "agt_8fk21",
"channel": "phone",
"reason": "low_confidence"
}
}The same runs you can open in the console
Every event you receive corresponds to something visible in the product. A workflow_run.failed webhook is the same run you can open in the run history, step by step, with what went in and what came back.
- conversation.completed and conversation.escalated, with agent, channel and language on the payload.
- ticket.created and ticket.updated for anything that needs tracking.
- workflow_run.finished and workflow_run.failed, so a retry on your side can be matched to a run on ours.
- Signed with a shared secret you can rotate from the console.
One line on the page
Paste the script tag and the widget is live with your agent, your knowledge and your escalation rules. It writes to the same conversation record as the QR code, your support inbox and the phone line, so a customer who called this morning is not a stranger this afternoon.
- No build step, no framework, no package to keep up to date.
- Follows the page language, or pin it with data-lang.
- Hands over to a person inside the same widget, without a reload.
<!-- Web chat. One line, before </body>. -->
<script src="https://cdn.takallam.ai/embed.js" data-agent="agt_8fk21" defer></script>
<!-- Pin the language instead of following the page. -->
<script src="https://cdn.takallam.ai/embed.js"
data-agent="agt_8fk21"
data-lang="ar-AE" defer></script>Native SDKs for iOS and Android
The in-app channel ships as a native SDK, not a web view dropped into your app. Your users get chat and voice from the same agent, in the language they are already using your app in.
- Use the drop-in view, or call the API and render your own interface.
- Voice and text in one session — a user can start typing and switch to speaking.
- Arabic and English, including customers who switch mid-sentence.
- The conversation continues in the console if a person needs to take it.
Sandbox first, live when you mean it
Every workspace has two kinds of key. A sandbox key runs against a test workspace with the same request and response shapes and no live channels attached, so a bad loop in a script cannot call a real customer. A live key is the real thing.
- Keys are created and revoked in the console, per environment.
- Sandbox has no live phone number, no live QR code and no real customers on the other end.
- The same code path serves both — you change the key, not the URLs.
- Revoking a key takes effect immediately, not at the end of a session.
The unglamorous parts
The behaviour you only notice when something goes wrong at 2am is the behaviour worth writing down.
Idempotent writes
Send an idempotency key with a POST and a retry after a timeout returns the original result instead of creating a second agent, conversation or ticket.
Rate limits
Limits are applied per key. A throttled request comes back as a 429 and nothing was created, so retrying with backoff is safe rather than duplicating work.
Cursor pagination
Lists return a cursor rather than a page number, so a backfill does not skip or repeat rows while new conversations keep arriving behind it.
One region
Your workspace lives in the UAE region, me-central-1. Conversations, transcripts and knowledge bases stay in-region by default, and you decide what is retained.
What engineers ask first
Is there an API?
Yes. Takallam is a REST API at https://api.takallam.ai/v1 with the console built on top of it. Agents, knowledge, conversations, tickets, workflows and webhooks are all resources you can call directly, with JSON in and out and cursor pagination on every list.
How do I get an API key?
Takallam is pre-launch, so keys go out with the first cohort. Join the waitlist and tell us what you want to build — the integrations people ask for first are the ones that get built and documented first.
Is there a sandbox?
Yes. Sandbox keys run against a test workspace with the same request and response shapes as live, but with no live channels attached, so nothing you send reaches a real customer. Moving to production means changing the key, not the code.
Are webhooks signed?
Yes. Every delivery carries a signature computed over the raw body using a secret you can rotate. Verify it before parsing, and make your handler idempotent — failed deliveries are retried, so the same event can arrive more than once.
Can I build my own interface and still use the console?
Yes. Conversations you start through the API land in the same inbox as QR, chat, email and phone. Your team takes over in the same thread, escalations become the same tickets, and the same workflows run behind them.
Do you have SDKs?
Native SDKs for iOS and Android cover the in-app channel, and the web is a script tag. Everything else is plain HTTP and JSON, so any language with an HTTP client works without waiting for a wrapper.
What are the rate limits?
Limits are applied per key. A throttled request returns a 429 and creates nothing, so retrying with backoff is safe, and an idempotency key on writes means a retry after a timeout returns the original result rather than a duplicate. Exact limits are set with the first cohort against real volume.
Where does the API run?
In the UAE region, me-central-1. Conversations, transcripts and knowledge bases stay in-region by default, and you control what is retained and for how long.
Tell us what you want to build
API access goes out with the first cohort. Join the waitlist and say which channels and which endpoints matter to you — that is what decides the order we ship in.
Pay per interaction · priced per channel · no seats, no minimums