Conversations API reference

Before you start

• An API key and a successful `/ping` response

Conventions

• Base URL is `https://onlo.ai/api/v1`. There is no API subdomain.
• Field names are `snake_case`. Every resource carries a `type` discriminator.
• All timestamps are INTEGER Unix epoch **seconds**, in responses and in search filters. They are not milliseconds and not ISO-8601 strings.
• Your organization is derived from the API key. `organization_id` and `workspace_id` are never accepted, and sending them is a `400` rather than being silently ignored.
• Unknown fields are rejected at every level of the request body.
• Every response carries `X-Onlo-Request-Id` and `Cache-Control: no-store`. Give the request id to support when you report a problem.

The conversation resource

{
  "type": "conversation",
  "id": "9a4f18f5-93ac-4476-b87f-6af63c700c64",
  "external_id": "legacy_conv_987",
  "created_at": 1787740200,
  "updated_at": 1787740200,
  "channel": "api",
  "source": { "type": "api" },
  "state": "open",
  "open": true,
  "status": "active",
  "custom_attributes": { "order_id": "ord_456", "plan": "pro" },
  "message_count": 0,
  "last_message_at": null,
  "contact": {
    "type": "contact",
    "id": "29894c6a-7187-45cc-af77-8c58a9dd1511",
    "external_id": "customer_123",
    "name": "Sarah Chen",
    "email": "sarah@example.com",
    "phone": null
  },
  "contacts": {
    "type": "contact.list",
    "contacts": [
      { "type": "contact", "id": "29894c6a-7187-45cc-af77-8c58a9dd1511", "external_id": "customer_123" }
    ]
  }
}

POST /conversations

Creates one EMPTY conversation and returns its durable id. It writes no message, sends nothing, and invokes no AI. Requires a full-access key.

`external_id` is the idempotency key. Repeating a create with the same `external_id` and the same contact returns the existing conversation with `200` and the header `X-Onlo-Idempotent-Replay: true`, instead of creating a second one.

curl --request POST "$ONLO_API_BASE_URL/conversations" \
  --header "Authorization: Bearer $ONLO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "external_id": "legacy_conv_987",
    "from": {
      "type": "contact",
      "external_id": "customer_123",
      "name": "Sarah Chen",
      "email": "sarah@example.com"
    },
    "custom_attributes": { "order_id": "ord_456", "plan": "pro" }
  }'

{
  "type": "conversation",
  "id": "9a4f18f5-93ac-4476-b87f-6af63c700c64",
  "external_id": "legacy_conv_987",
  "created_at": 1787740200,
  "updated_at": 1787740200,
  "channel": "api",
  "source": { "type": "api" },
  "state": "open",
  "open": true,
  "status": "active",
  "custom_attributes": { "order_id": "ord_456", "plan": "pro" },
  "message_count": 0,
  "last_message_at": null,
  "contact": {
    "type": "contact",
    "id": "29894c6a-7187-45cc-af77-8c58a9dd1511",
    "external_id": "customer_123",
    "name": "Sarah Chen",
    "email": "sarah@example.com",
    "phone": null
  },
  "contacts": {
    "type": "contact.list",
    "contacts": [
      { "type": "contact", "id": "29894c6a-7187-45cc-af77-8c58a9dd1511", "external_id": "customer_123" }
    ]
  }
}

Create: what each retry does

GET /conversations/{conversation_id}

Returns one conversation. Accepts a read-only key.

A conversation that does not exist, has been deleted, or belongs to another organization all return the same `404 not_found`. This is deliberate — a distinguishable response would confirm whether an id exists in someone else’s organization.

PUT /conversations/{conversation_id}

Sets and removes custom attributes. Requires a full-access key. Only `custom_attributes` is writable — any other field is rejected by name, and status, assignment, channel, and internal metadata cannot be changed through this API.

A `null` VALUE removes that key. There is no separate unset list. This also means a stored JSON `null` is not representable: a key either has a value or does not exist.

Attributes are merged inside the database in a single statement, so a concurrent update to a different key is never lost.

curl --request PUT "$ONLO_API_BASE_URL/conversations/9a4f18f5-93ac-4476-b87f-6af63c700c64" \
  --header "Authorization: Bearer $ONLO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "custom_attributes": {
      "order_id": "ord_789",
      "is_vip": true,
      "plan": null
    }
  }'

Custom attribute limits

POST /conversations/search

Finds one contact’s conversations. This uses `POST` because the filter grammar is typed JSON, but it is read-only and accepts a read-only key. It returns conversation records and their attributes — never transcript messages.

Every search must include exactly one `contact.external_id` or `contact.id` filter with operator `=`. A single filter can also be passed directly as `query`, as in Intercom.

curl --request POST "$ONLO_API_BASE_URL/conversations/search" \
  --header "Authorization: Bearer $ONLO_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "query": {
      "operator": "AND",
      "value": [
        { "field": "contact.external_id",        "operator": "=", "value": "customer_123" },
        { "field": "custom_attributes.order_id", "operator": "=", "value": "ord_789" }
      ]
    },
    "pagination": { "per_page": 50, "starting_after": null }
  }'

{
  "type": "conversation.list",
  "conversations": [ { "type": "conversation", "id": "9a4f18f5-…" } ],
  "total_count": 1,
  "pages": { "type": "pages", "page": 1, "per_page": 50 }
}

• `per_page` defaults to 50, maximum 100. An out-of-range value is REJECTED, not clamped — so a short page always means "no more results", never "your limit was quietly reduced".
• Only one flat `AND` group is supported. Nested groups and a root `OR` are rejected; a root `OR` could return conversations outside your contact filter.
• The `~`, `!~`, `^`, and `$` operators are rejected by name. No index can serve them.
• An unknown, unmapped, or erased contact returns `200` with an empty list — never a `404`, and never organization-wide results.

Pagination

Results are ordered newest first and paginated by cursor. When more results exist, `pages.next.starting_after` holds an opaque cursor; send it back in `pagination.starting_after` with an otherwise IDENTICAL request body.

`pages.next` is ABSENT on the last page rather than `null`, so a `while (page.pages.next)` loop terminates on its own.

Errors

Errors use Intercom’s `error.list` envelope. `errors` is an ARRAY — read `errors[0].code` to branch, and `field` to point a user at the offending input.

{
  "type": "error.list",
  "request_id": "977fba8b-1b57-45c4-a965-bb62e6eebd1d",
  "errors": [
    {
      "code": "parameter_not_found",
      "message": "from.external_id is required",
      "field": "from.external_id"
    }
  ]
}

Retry policy