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

EntornoURL base
Producciónhttps://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 rutaPermisoRespuesta
POST /v1/campaignscampaigns:write201 { campaign }, o 200 { campaign, idempotent_replay: true } si ya existía
GET /v1/campaigns/{id}items:read200 { campaign }
GET /v1/items/{type}/{external_id}items:read200 { item }
GET /v1/itemsitems:read200 { items, next_cursor }
POST /v1/items/{type}/{external_id}/statusitems:write200 { item, notified }
GET /v1/pingcualquiera200 { 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" } }
      ]
    }
  ]
}

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ámetroQué filtra
typeTipo de ítem
statusopen, in_progress, resolved, cancelled o expired
contactexternal_id del contacto
campaignid de la campaña (el nuestro; acá no se acepta ext:)
updated_sinceFecha ISO-8601: ítems modificados desde ese momento, inclusive
limitDe 1 a 500 (por defecto 100)
cursorEl 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" }
statusCuándo se acepta
resolvedDesde cualquier estado no terminal. Si ya estaba resuelto, responde 200 sin cambios
cancelledDesde cualquier estado no terminal. Si ya estaba cancelado, responde 200 sin cambios
openDesde cualquier estado, con motivo obligatorio: reabre el ítem

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ódigoHTTPCuándo
INVALID_API_KEY401Falta la key, tiene mal formato, no existe o está revocada
INSUFFICIENT_SCOPE403La key no tiene el permiso de esa ruta
INTEGRATION_NOT_ENABLED403La organización no tiene integraciones habilitadas
RATE_LIMITED429Más de 120 pedidos por minuto con la misma key
VALIDATION_ERROR422Cuerpo o parámetros inválidos, o JSON mal formado
CALLBACK_URL_NOT_ALLOWED400El pedido trae callback_url
PAYLOAD_TOO_LARGE413El cuerpo supera los 5 MB
TOO_MANY_CONTACTS422Más de 2000 contactos o 10000 ítems en una campaña
FLOW_NOT_FOUND422El flujo no existe o está inactivo
FLOW_TEMPLATE_NOT_APPROVED422La plantilla del flujo no está aprobada
ITEM_ALREADY_EXISTS409Un ítem con ese tipo y external_id ya existe en otra campaña o ya terminó
CAMPAIGN_NOT_FOUND404La campaña no existe
ITEM_NOT_FOUND404El ítem no existe
INVALID_TRANSITION409Ese cambio de estado no está permitido
MOTIVO_REQUIRED422Se pidió open sin motivo
NOTIFY_NOT_AVAILABLE422Se mandó notify: true
INVALID_CURSOR400El cursor no es válido
NOT_FOUND404La ruta no existe
INTERNAL_ERROR500Error interno; reintentá más tarde

Límites

💡
Tip:Ante un 429 o un 5xx, reintentá con espera creciente. En POST /v1/campaigns reintentar con el mismo external_id es seguro.