Referencia de la API (/v1)
Para quién es: quien desarrolla el sistema que se conecta con TalkAI
Para qué sirve
Con la API tu sistema lanza campañas, consulta ítems y cambia su estado. Todo va en JSON y cada pedido lleva una API key creada en Configuración > Integraciones. Los conceptos están en Integraciones: API y webhooks.
Base y autenticación
| Entorno | URL base |
|---|---|
| Producción | https://talkai.com.ar/v1 |
| Pruebas (sandbox) | https://dev.talkai.com.ar/v1 |
Las keys de un entorno no sirven en el otro: el entorno de pruebas se usa con keys creadas ahí, coordinándolo con el equipo de TalkAI.
Cada pedido lleva la key en el header Authorization:
Authorization: Bearer tk_live_...
Content-Type: application/json
Para probar la key: GET /v1/ping responde { "ok": true, "tenant_id": "...", "scopes": [...] }.
Endpoints
| Método y ruta | Permiso | Respuesta |
|---|---|---|
POST /v1/campaigns | campaigns:write | 201 { campaign }, o 200 { campaign, idempotent_replay: true } si ya existía |
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 | cualquiera | 200 { ok, tenant_id, scopes } |
Lanzar una campaña
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 de un flujo activo de tu organización.external_id: tu id de la campaña (hasta 191 caracteres). Es la clave de idempotencia: si repetís el pedido con el mismoexternal_id, no se crea ni se envía nada nuevo y la respuesta es 200 con la campaña existente yidempotent_replay: true. Reintentar un pedido que se cortó es seguro.contacts[].phone: obligatorio. Si hay teléfonos inválidos, el pedido entero se rechaza con todos los errores por posición (por ejemplocontacts[3].phone). Si un teléfono se repite, sus ítems se juntan en un solo contacto.contacts[].external_idycontacts[].name: opcionales. El nombre puede usarse en la plantilla.contacts[].items[]: al menos uno por contacto. Cada ítem lleva suexternal_id(único dentro del pedido) y undataopcional de hasta 8 KB. El tipo del ítem lo pone el flujo.- Límites: hasta 2000 contactos y 10000 ítems por campaña, y 5 MB por pedido.
- No mandes
callback_url: el webhook se configura en el panel y el pedido se rechaza si la trae.
Si un ítem con el mismo tipo y external_id ya existe en otra campaña (o ya terminó), la respuesta es ITEM_ALREADY_EXISTS. Usá un external_id de ítem por cada cosa a resolver.
La respuesta trae la campaña:
{
"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" }]
}
]
}
}
Si la campaña se creó pero no pudo arrancar, la respuesta suma activation_error con un código; avisanos si pasa.
deferred_reason solo tiene valor mientras el contacto está diferido porque ya estaba conversando (ver Integraciones: API y webhooks).
Consultar una campaña
GET /v1/campaigns/{id} acepta nuestro id o tu id con el prefijo ext:, por ejemplo GET /v1/campaigns/ext:camp-2026-11-20.
Consultar un ítem
GET /v1/items/pedido/P-1001 devuelve el ítem:
{
"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"
}
}
Listar ítems y ponerse al día
GET /v1/items acepta estos filtros, todos opcionales:
| Parámetro | Qué filtra |
|---|---|
type | Tipo de ítem |
status | open, in_progress, resolved, cancelled o expired |
contact | external_id del contacto |
campaign | id de la campaña (el nuestro; acá no se acepta ext:) |
updated_since | Fecha ISO-8601: ítems modificados desde ese momento, inclusive |
limit | De 1 a 500 (por defecto 100) |
cursor | El next_cursor de la página anterior |
Los ítems salen ordenados por fecha de modificación. Si next_cursor viene con valor, pedí la página siguiente con los mismos filtros más cursor; cuando viene null, terminaste.
Para reconciliar, guardá el updated_at más alto que procesaste y, cada tanto o después de una caída, pedí GET /v1/items?updated_since=<ese valor>. El webhook es un timbre: si alguno se pierde, esta consulta reconstruye el estado.
Cambiar el estado de un ítem
POST /v1/items/{type}/{external_id}/status
{ "status": "cancelled", "motivo": "El cliente canceló el pedido" }
status | Cuándo se acepta |
|---|---|
resolved | Desde cualquier estado no terminal. Si ya estaba resuelto, responde 200 sin cambios |
cancelled | Desde cualquier estado no terminal. Si ya estaba cancelado, responde 200 sin cambios |
open | Desde cualquier estado, con motivo obligatorio: reabre el ítem |
motivo: texto de hasta 500 caracteres; queda enlast_motivo.in_progressyexpiredno se aceptan por la API.notify: true(avisarle al contacto) todavía no está disponible y respondeNOTIFY_NOT_AVAILABLE. Hoynotifiedsiempre esfalse.
Los estados terminales son resolved, cancelled y expired. Pasar de uno terminal a otro responde INVALID_TRANSITION; para volver a trabajar un ítem terminado, reabrilo con open.
Errores
Todos los errores tienen la misma forma:
{ "error": { "code": "VALIDATION_ERROR", "message": "Pedido inválido", "details": [{ "path": "contacts[3].phone", "message": "Teléfono inválido" }] } }
details aparece solo cuando hay errores por campo. Guiate por code: el texto de message puede cambiar.
| Código | HTTP | Cuándo |
|---|---|---|
INVALID_API_KEY | 401 | Falta la key, tiene mal formato, no existe o está revocada |
INSUFFICIENT_SCOPE | 403 | La key no tiene el permiso de esa ruta |
INTEGRATION_NOT_ENABLED | 403 | La organización no tiene integraciones habilitadas |
RATE_LIMITED | 429 | Más de 120 pedidos por minuto con la misma key |
VALIDATION_ERROR | 422 | Cuerpo o parámetros inválidos, o JSON mal formado |
CALLBACK_URL_NOT_ALLOWED | 400 | El pedido trae callback_url |
PAYLOAD_TOO_LARGE | 413 | El cuerpo supera los 5 MB |
TOO_MANY_CONTACTS | 422 | Más de 2000 contactos o 10000 ítems en una campaña |
FLOW_NOT_FOUND | 422 | El flujo no existe o está inactivo |
FLOW_TEMPLATE_NOT_APPROVED | 422 | La plantilla del flujo no está aprobada |
ITEM_ALREADY_EXISTS | 409 | Un ítem con ese tipo y external_id ya existe en otra campaña o ya terminó |
CAMPAIGN_NOT_FOUND | 404 | La campaña no existe |
ITEM_NOT_FOUND | 404 | El ítem no existe |
INVALID_TRANSITION | 409 | Ese cambio de estado no está permitido |
MOTIVO_REQUIRED | 422 | Se pidió open sin motivo |
NOTIFY_NOT_AVAILABLE | 422 | Se mandó notify: true |
INVALID_CURSOR | 400 | El cursor no es válido |
NOT_FOUND | 404 | La ruta no existe |
INTERNAL_ERROR | 500 | Error interno; reintentá más tarde |
Límites
- 120 pedidos por minuto por key. Al pasarte responde 429
RATE_LIMITED; los headersRateLimit-*indican cuánto te queda y cuándo se renueva. - Además, hasta 600 pedidos por minuto desde una misma IP, antes de revisar la key.
- 5 MB por pedido, 2000 contactos y 10000 ítems por campaña, 8 KB de
datapor ítem.
POST /v1/campaigns reintentar con el mismo external_id es seguro.