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

EnvironmentBase URL
Productionhttps://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 pathPermissionResponse
POST /v1/campaignscampaigns:write201 { campaign }, or 200 { campaign, idempotent_replay: true } if it already existed
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/pingany200 { 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" } }
      ]
    }
  ]
}

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:

ParameterWhat it filters
typeItem type
statusopen, in_progress, resolved, cancelled or expired
contactThe contact's external_id
campaignThe campaign id (ours; ext: is not accepted here)
updated_sinceISO-8601 date: items changed since that moment, inclusive
limitFrom 1 to 500 (default 100)
cursorThe 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" }
statusWhen it is accepted
resolvedFrom any non-terminal status. If it was already resolved, it answers 200 with no changes
cancelledFrom any non-terminal status. If it was already cancelled, it answers 200 with no changes
openFrom any status, with a required motivo (reason): it reopens the item

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.

CodeHTTPWhen
INVALID_API_KEY401The key is missing, malformed, does not exist or was revoked
INSUFFICIENT_SCOPE403The key lacks the permission for that path
INTEGRATION_NOT_ENABLED403The organization does not have integrations enabled
RATE_LIMITED429More than 120 requests per minute with the same key
VALIDATION_ERROR422Invalid body or parameters, or malformed JSON
CALLBACK_URL_NOT_ALLOWED400The request includes callback_url
PAYLOAD_TOO_LARGE413The body exceeds 5 MB
TOO_MANY_CONTACTS422More than 2000 contacts or 10000 items in a campaign
FLOW_NOT_FOUND422The flow does not exist or is inactive
FLOW_TEMPLATE_NOT_APPROVED422The flow's template is not approved
ITEM_ALREADY_EXISTS409An item with that type and external_id already exists in another campaign or is finished
CAMPAIGN_NOT_FOUND404The campaign does not exist
ITEM_NOT_FOUND404The item does not exist
INVALID_TRANSITION409That status change is not allowed
MOTIVO_REQUIRED422open was requested without motivo
NOTIFY_NOT_AVAILABLE422notify: true was sent
INVALID_CURSOR400The cursor is not valid
NOT_FOUND404The path does not exist
INTERNAL_ERROR500Internal error; retry later

Limits

💡
Tip:On a 429 or a 5xx, retry with increasing backoff. On POST /v1/campaigns, retrying with the same external_id is safe.