API reference (/v1)
Who it's for: developers of the system that connects to TalkAI
What it's for
With the API your system launches campaigns, queries items and changes their status. Everything is JSON and every request carries an API key created in Settings > Integrations. The concepts are in Integrations: API and webhooks.
Base URL and authentication
| Environment | Base URL |
|---|---|
| Production | https://talkai.com.ar/v1 |
| Testing (sandbox) | https://dev.talkai.com.ar/v1 |
Keys from one environment do not work in the other: the testing environment is used with keys created there, arranged with the TalkAI team.
Every request carries the key in the Authorization header:
Authorization: Bearer tk_live_...
Content-Type: application/json
To test the key: GET /v1/ping answers { "ok": true, "tenant_id": "...", "scopes": [...] }.
Endpoints
| Method and path | Permission | Response |
|---|---|---|
POST /v1/campaigns | campaigns:write | 201 { campaign }, or 200 { campaign, idempotent_replay: true } if it already existed |
GET /v1/campaigns/{id} | items:read | 200 { campaign } |
GET /v1/items/{type}/{external_id} | items:read | 200 { item } |
GET /v1/items | items:read | 200 { items, next_cursor } |
POST /v1/items/{type}/{external_id}/status | items:write | 200 { item, notified } |
GET /v1/ping | any | 200 { ok, tenant_id, scopes } |
Launch a campaign
POST /v1/campaigns
{
"flow": "confirmar_pedidos",
"external_id": "camp-2026-11-20",
"contacts": [
{
"external_id": "cliente-77",
"phone": "+5491122334455",
"name": "Ana",
"items": [
{ "external_id": "P-1001", "data": { "producto": "Silla", "fecha_entrega": "2026-11-20" } }
]
}
]
}
flow: slug of an active flow of your organization.external_id: your campaign id (up to 191 characters). It is the idempotency key: if you repeat the request with the sameexternal_id, nothing new is created or sent and the response is 200 with the existing campaign andidempotent_replay: true. Retrying a request that was cut off is safe.contacts[].phone: required. If there are invalid phones, the whole request is rejected with every error by position (for examplecontacts[3].phone). If a phone repeats, its items are merged into a single contact.contacts[].external_idandcontacts[].name: optional. The name can be used in the template.contacts[].items[]: at least one per contact. Each item carries itsexternal_id(unique within the request) and an optionaldataof up to 8 KB. The item type comes from the flow.- Limits: up to 2000 contacts and 10000 items per campaign, and 5 MB per request.
- Do not send
callback_url: the webhook is configured in the panel and the request is rejected if it includes one.
If an item with the same type and external_id already exists in another campaign (or is already finished), the response is ITEM_ALREADY_EXISTS. Use one item external_id per thing to resolve.
The response carries the campaign:
{
"campaign": {
"id": "6f1c...",
"external_id": "camp-2026-11-20",
"flow": "confirmar_pedidos",
"status": "active",
"created_at": "2026-11-19T12:00:00.000Z",
"counts": { "contacts": 1, "items": 1, "deferred": 0, "by_item_status": { "open": 1 } },
"contacts": [
{
"external_id": "cliente-77",
"phone": "+5491122334455",
"status": "pending",
"deferred_reason": null,
"items": [{ "type": "pedido", "external_id": "P-1001", "status": "open" }]
}
]
}
}
If the campaign was created but could not start, the response adds activation_error with a code; let us know if it happens.
deferred_reason only has a value while the contact is deferred because they were already in a conversation (see Integrations: API and webhooks).
Query a campaign
GET /v1/campaigns/{id} accepts our id or your id with the ext: prefix, for example GET /v1/campaigns/ext:camp-2026-11-20.
Query an item
GET /v1/items/pedido/P-1001 returns the item:
{
"item": {
"type": "pedido",
"external_id": "P-1001",
"status": "resolved",
"data": { "producto": "Silla", "fecha_entrega": "2026-11-20" },
"result": { "respuesta": "confirma" },
"flow": "confirmar_pedidos",
"campaign_id": "6f1c...",
"campaign_external_id": "camp-2026-11-20",
"contact_external_id": "cliente-77",
"origin": "campaign",
"attachments_count": 0,
"last_motivo": null,
"conversations": [{ "id": "9a2e...", "linked_at": "2026-11-19T12:05:10.000Z" }],
"attachments": [],
"created_at": "2026-11-19T12:00:00.000Z",
"updated_at": "2026-11-19T12:06:42.120Z"
}
}
List items and catch up
GET /v1/items accepts these filters, all optional:
| Parameter | What it filters |
|---|---|
type | Item type |
status | open, in_progress, resolved, cancelled or expired |
contact | The contact's external_id |
campaign | The campaign id (ours; ext: is not accepted here) |
updated_since | ISO-8601 date: items changed since that moment, inclusive |
limit | From 1 to 500 (default 100) |
cursor | The next_cursor of the previous page |
Items come sorted by modification date. If next_cursor has a value, ask for the next page with the same filters plus cursor; when it is null, you are done.
To reconcile, store the highest updated_at you processed and, from time to time or after an outage, call GET /v1/items?updated_since=<that value>. The webhook is a doorbell: if one gets lost, this query rebuilds the state.
Change an item's status
POST /v1/items/{type}/{external_id}/status
{ "status": "cancelled", "motivo": "The customer cancelled the order" }
status | When it is accepted |
|---|---|
resolved | From any non-terminal status. If it was already resolved, it answers 200 with no changes |
cancelled | From any non-terminal status. If it was already cancelled, it answers 200 with no changes |
open | From any status, with a required motivo (reason): it reopens the item |
motivo: text of up to 500 characters; it is kept inlast_motivo.in_progressandexpiredare not accepted through the API.notify: true(message the contact) is not available yet and answersNOTIFY_NOT_AVAILABLE. Todaynotifiedis alwaysfalse.
The terminal statuses are resolved, cancelled and expired. Moving from one terminal status to another answers INVALID_TRANSITION; to work on a finished item again, reopen it with open.
Errors
All errors have the same shape:
{ "error": { "code": "VALIDATION_ERROR", "message": "Pedido inválido", "details": [{ "path": "contacts[3].phone", "message": "Teléfono inválido" }] } }
details only shows up when there are per-field errors. Rely on code: the message text (in Spanish) may change.
| Code | HTTP | When |
|---|---|---|
INVALID_API_KEY | 401 | The key is missing, malformed, does not exist or was revoked |
INSUFFICIENT_SCOPE | 403 | The key lacks the permission for that path |
INTEGRATION_NOT_ENABLED | 403 | The organization does not have integrations enabled |
RATE_LIMITED | 429 | More than 120 requests per minute with the same key |
VALIDATION_ERROR | 422 | Invalid body or parameters, or malformed JSON |
CALLBACK_URL_NOT_ALLOWED | 400 | The request includes callback_url |
PAYLOAD_TOO_LARGE | 413 | The body exceeds 5 MB |
TOO_MANY_CONTACTS | 422 | More than 2000 contacts or 10000 items in a campaign |
FLOW_NOT_FOUND | 422 | The flow does not exist or is inactive |
FLOW_TEMPLATE_NOT_APPROVED | 422 | The flow's template is not approved |
ITEM_ALREADY_EXISTS | 409 | An item with that type and external_id already exists in another campaign or is finished |
CAMPAIGN_NOT_FOUND | 404 | The campaign does not exist |
ITEM_NOT_FOUND | 404 | The item does not exist |
INVALID_TRANSITION | 409 | That status change is not allowed |
MOTIVO_REQUIRED | 422 | open was requested without motivo |
NOTIFY_NOT_AVAILABLE | 422 | notify: true was sent |
INVALID_CURSOR | 400 | The cursor is not valid |
NOT_FOUND | 404 | The path does not exist |
INTERNAL_ERROR | 500 | Internal error; retry later |
Limits
- 120 requests per minute per key. Above that it answers 429
RATE_LIMITED; theRateLimit-*headers tell you how much is left and when it resets. - Also, up to 600 requests per minute from the same IP, before the key is checked.
- 5 MB per request, 2000 contacts and 10000 items per campaign, 8 KB of
dataper item.
POST /v1/campaigns, retrying with the same external_id is safe.