Conversation Ingestion API

Overview #

The ingestion API is Belter's generic adapter: a single, stable HTTPS contract that accepts conversations from any platform — even ones we don't have a native connector for. Once a conversation lands here, it's normalized into Belter's universal schema and joins the same QA pipeline as data from LiveChat, Zendesk, RingCentral, and the rest.

Base URL

The machine-readable OpenAPI specification is available at GET /api/v1/docs/openapi.json — drop it into Postman, Insomnia, or your codegen of choice.

Quick start #

1. Sign in to Belter and go to Admin → API Tokens.
2. Create a token with the conversations.write scope.
3. POST a conversation envelope to /ingest/conversations.
4. The conversation appears in Belter and is queued for QA evaluation (when auto-evaluation is enabled).

curl -X POST "https://clients.belter.app/api/v1/ingest/conversations" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ticket-123",
    "channel": "chat",
    "messages": [
      { "author": "customer", "body": "Hi" },
      { "author": "agent",    "body": "Hello — how can I help?" }
    ]
  }'

# → 201 Created · evaluation queued

That's the whole API in one call: an external_id (your system's stable ID), and one or more messages. Everything else is optional but worth providing for richer reporting.

Authentication #

All requests use Bearer-token auth. Tokens are organisation-scoped — all data you ingest belongs to the token owner's org.

Authorization: Bearer <your_api_token>
Content-Type: application/json

Auth failure modes

Endpoints #

Three ingestion shapes. Same envelope. Same scope.

Required scope: conversations.write for all ingestion endpoints.

Conversation envelope #

Every ingestion request uses the same JSON schema. Send it as the request body (single endpoint) or as items inside a conversations array (bulk endpoint).

{
  "external_id": "ticket-123",
  "channel": "voice",
  "subject": "Billing question",
  "status": "closed",
  "started_at": "2026-05-29T10:00:00Z",
  "closed_at": "2026-05-29T10:12:00Z",
  "customer": {
    "external_id": "cust-42",
    "email": "[email protected]",
    "name": "Ada Lovelace",
    "phone": "+441234567890"
  },
  "agent": {
    "email": "[email protected]"
  },
  "metadata": {
    "queue": "Billing",
    "priority": "high"
  },
  "messages": [
    {
      "author": "customer",
      "body": "Hi, I was charged twice this month.",
      "sent_at": "2026-05-29T10:00:00Z",
      "external_id": "msg-1"
    },
    {
      "author": "agent",
      "body": "Sorry about that — I'll check your account now.",
      "sent_at": "2026-05-29T10:02:00Z",
      "external_id": "msg-2"
    }
  ]
}

Top-level fields #

customer object #

At least one of external_id or email is needed to link a customer record.

agent object #

messages array #

Author mapping

Deduplication #

external_id is the dedupe key per organisation. The API is safe to retry — re-posting the same conversation only appends genuinely new messages.

When re-posting an existing conversation, only messages with a new external_id are appended. Messages without an external_id may be imported again — always include one when you can.

POST /ingest/conversations #

Ingest a single conversation.

Request

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Body: one conversation envelope (see Conversation envelope above).

Response — imported

{
  "data": {
    "status": "imported",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Response — skipped

{
  "data": {
    "status": "skipped",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "No new messages"
  }
}

POST /ingest/conversations/bulk #

Ingest up to 200 conversations in one request. Each item is evaluated independently — one bad payload doesn't sink the rest.

Request

{
  "conversations": [
    {
      "external_id": "ticket-1",
      "channel": "chat",
      "messages": [
        { "author": "customer", "body": "Hello", "external_id": "m1" }
      ]
    },
    {
      "external_id": "ticket-2",
      "channel": "email",
      "messages": [
        { "author": "agent", "body": "Hi there", "external_id": "m2" }
      ]
    }
  ]
}

Response

{
  "data": {
    "imported": 2,
    "skipped": 0,
    "errors": 0,
    "details": [
      {
        "external_id": "ticket-1",
        "status": "imported",
        "conversation_id": "550e8400-e29b-41d4-a716-446655440001"
      },
      {
        "external_id": "ticket-2",
        "status": "skipped",
        "conversation_id": "550e8400-e29b-41d4-a716-446655440002",
        "reason": "No new messages"
      }
    ]
  }
}

Items that fail validation are counted in errors with an error message in the corresponding details[] entry.

POST /ingest/conversations/csv #

Upload a CSV file where each row becomes a single-message conversation. Use for flat transcript exports from platforms that can't easily POST JSON.

Request

Authorization: Bearer <token>
Content-Type: multipart/form-data

CSV headers

external_id, channel, subject, status, customer_email, customer_name, agent_email, author, body, sent_at

Required per row: external_id and body.

external_id,channel,subject,status,customer_email,customer_name,agent_email,author,body,sent_at
ticket-100,chat,Billing issue,closed,[email protected],Jane Doe,[email protected],customer,I need a refund,2026-05-29T10:00:00Z
ticket-101,chat,Billing issue,closed,[email protected],Jane Doe,[email protected],agent,Happy to help with that,2026-05-29T10:01:00Z

Response

Same shape as the bulk endpoint — imported, skipped, errors, details.

POST /ingest/amazon-connect #

Native receiver for Amazon Connect's Contact Lens / Contact Trace Record (CTR) payloads. Amazon Connect delivers these via Kinesis; a small Lambda forwards each record to this endpoint and Belter normalises it into the generic envelope before evaluation.

Request

Authorization: Bearer <token>
X-Amazon-Connect-Secret: <webhook_secret>
Content-Type: application/json

The payload may be the Contact Lens object directly, or wrapped as { "contact": { ... } } — Belter normalises both shapes.

Setup

1. Enable Contact Lens on the Amazon Connect instance.
2. In Belter, open Integrations → Amazon Connect and provide instance_id, aws_region, and a strong webhook_secret.
3. Deploy a Lambda on the Contact Lens Kinesis stream that POSTs each record to the endpoint above with the shared secret and a valid API token.

Error responses #

Validation error

{
  "errors": {
    "external_id": ["The external id field is required."],
    "messages": ["The messages field is required."]
  }
}

Other errors

Auto-evaluation #

When a conversation is successfully imported, Belter may automatically queue AI evaluation and contact-driver detection if all of the following are true:

• Auto-evaluation is enabled for your organisation
• Onboarding is complete
• An active evaluation version with a system prompt exists
• The conversation meets eligibility rules (channel, message count, etc.)

You can also trigger evaluation manually — useful for back-filling old imports after rolling out a new rubric version:

POST /api/v1/evaluations/trigger
Authorization: Bearer <token>
Content-Type: application/json

{ "conversation_id": "550e8400-e29b-41d4-a716-446655440000" }

cURL examples #

Single conversation

curl -X POST "https://clients.belter.app/api/v1/ingest/conversations" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ticket-123",
    "channel": "chat",
    "subject": "Billing question",
    "status": "closed",
    "customer": {
      "email": "[email protected]",
      "name": "Ada Lovelace"
    },
    "agent": {
      "email": "[email protected]"
    },
    "messages": [
      {
        "author": "customer",
        "body": "Hi, I was charged twice this month.",
        "external_id": "msg-1"
      },
      {
        "author": "agent",
        "body": "Sorry about that — I will check your account now.",
        "external_id": "msg-2"
      }
    ]
  }'

Bulk import

curl -X POST "https://clients.belter.app/api/v1/ingest/conversations/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversations": [
      {
        "external_id": "ticket-1",
        "messages": [{ "author": "customer", "body": "Hello", "external_id": "m1" }]
      },
      {
        "external_id": "ticket-2",
        "messages": [{ "author": "agent", "body": "Hi there", "external_id": "m2" }]
      }
    ]
  }'

CSV upload

curl -X POST "https://clients.belter.app/api/v1/ingest/conversations/csv" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "[email protected]"

Integration patterns #

Three battle-tested shapes. Pick by what your source platform can do.

Related endpoints #

Ingestion isn't the whole API. Once data is in, these endpoints let you read it back out, kick off evaluations, and push CSAT signal alongside.

Full API reference is at /api/v1/docs/openapi.json.

FAQ #