Conversations API

Before you start

• An Onlo organization on a plan that includes API access
• A full-access API key from Dashboard → Integrations → API
• A stable identifier for each of your users, and one for each source conversation you will create

What this API does

The Conversations API gives your backend one path to start or record a customer conversation in Onlo and find it again later. Onlo returns a durable UUID for you to store against your own record. A supplied first message is always stored in Inbox.

API AI replies are off by default. While off, an operator takes over and replies manually; AI does not generate a title or reply, and no AI credits are used. An owner or admin can enable AI replies in Dashboard → Integrations → API for future messages. Replaying the same `external_id`, or enabling the setting later, never generates a reply for an old message.

If you are coming from Intercom

This API deliberately matches Intercom’s wire shape, so most Intercom client code carries over: bearer auth, snake_case fields, a `type` discriminator on every resource, `conversation.list` with `pages.next.starting_after`, the `error.list` error envelope, integer Unix-epoch-second timestamps, `PUT` to update, and the `query`/`operator`/`field`/`value` search grammar.

Three differences will affect your code on day one, and there is a dedicated page for the full list.

• `body` is optional in Onlo. When supplied, Onlo stores it as the first customer message. AI replies are an API channel opt-in and default off; Intercom requires a body.
• Every search must filter on exactly one contact. Intercom lets you search a whole workspace.
• Creating a conversation is idempotent on your `external_id`. Intercom has no idempotency, so a retry there duplicates.

Base URL

All requests go to `https://onlo.ai/api/v1`. There is no API subdomain — if you have seen `api.onlo.ai` or `api.onlo.app` referenced anywhere, those hosts do not exist and will not resolve.

The three identifiers you need

Your identifiers are opaque and case-sensitive. Onlo stores them exactly as sent and rejects leading or trailing whitespace rather than trimming it, so one string in your system can never become two different keys.

Make your first three calls

1. Step 1

   Confirm your key works

   Call `/ping` before anything else. It verifies the key, your plan, any IP allowlist, and reports which scope the key carries.

   Connection testshell

   Copy

   export ONLO_API_BASE_URL="https://onlo.ai/api/v1"
   export ONLO_API_TOKEN="olk_live_replace_with_your_key"
   
   curl --request GET "$ONLO_API_BASE_URL/ping" \
     --header "Authorization: Bearer $ONLO_API_TOKEN" \
     --header "Accept: application/json"

   Expected resultA `200` response containing your `organization_id` and `scope`.

2. Step 2

   Create a conversation and store the id

   Send your source conversation id as `external_id`, a human-readable `subject`, and your user id as `from.external_id`. If that user does not exist in Onlo yet, this creates them.

   Createshell

   Copy

   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",
       "subject": "Order ord_456",
       "from": {
         "type": "contact",
         "external_id": "customer_123",
         "name": "Sarah Chen",
         "email": "sarah@example.com"
       },
       "body": "I need help with my order.",
       "custom_attributes": { "order_id": "ord_456", "plan": "pro" }
     }'

   Expected resultA `201` response whose `id` is the Onlo conversation UUID. Persist the mapping from your `external_id` to that `id` before you treat the record as migrated.

3. Step 3

   Set attributes, then search for them

   Use `PUT` with the returned id to set business fields you want to look up by later, then search for that user filtered on those fields.

   Set attributesshell

   Copy

   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
       }
     }'

   Searchshell

   Copy

   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 }
     }'

   Expected resultThe `PUT` returns the full conversation with the updated `custom_attributes`; the search returns that conversation inside a `conversation.list`.

Complete backend example

The full loop, including the retry-safety and pagination behavior you should copy rather than reimplement. Run it only from a trusted backend.

const baseUrl = process.env.ONLO_API_BASE_URL ?? 'https://onlo.ai/api/v1';
const token = process.env.ONLO_API_TOKEN;
if (!token) throw new Error('ONLO_API_TOKEN is required');

async function callOnlo(path: string, options: RequestInit = {}) {
  const response = await fetch(`${baseUrl}${path}`, {
    ...options,
    signal: AbortSignal.timeout(30_000),
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: 'application/json',
      ...(options.body ? { 'Content-Type': 'application/json' } : {}),
      ...options.headers,
    },
  });

  const body = await response.json().catch(() => ({}));
  if (!response.ok) {
    // Errors arrive as Intercom's error.list: errors is an array.
    const first = body.errors?.[0];
    const requestId = response.headers.get('X-Onlo-Request-Id');
    throw new Error(`${response.status} ${first?.code ?? 'request_failed'} ${first?.message ?? ''} request_id=${requestId ?? 'missing'}`);
  }
  return { body, response };
}

// 1. Create a conversation with its first customer message. API AI replies
// default off, so this is stored for manual handling unless an owner enables them.
const { body: created, response: createResponse } = await callOnlo('/conversations', {
  method: 'POST',
  body: JSON.stringify({
    external_id: 'legacy_conv_987',
    subject: 'Order ord_456',
    from: { type: 'contact', external_id: 'customer_123', name: 'Sarah Chen' },
    custom_attributes: { order_id: 'ord_456' },
    body: 'I need help with my order.',
  }),
});

const conversationId = created.id;
const wasReplay = createResponse.headers.get('X-Onlo-Idempotent-Replay') === 'true';
// Persist legacy_conv_987 -> conversationId now. If THAT write fails, retry this
// exact request: the same id comes back with wasReplay === true.

// 2. Set attributes. A null value removes that key.
await callOnlo(`/conversations/${encodeURIComponent(conversationId)}`, {
  method: 'PUT',
  body: JSON.stringify({ custom_attributes: { order_id: 'ord_789', plan: null } }),
});

// 3. Page through every match for this contact.
const conversations = [];
let startingAfter: string | null = null;
for (;;) {
  const { body: page } = await callOnlo('/conversations/search', {
    method: 'POST',
    body: JSON.stringify({
      query: {
        operator: 'AND',
        value: [{ field: 'contact.external_id', operator: '=', value: 'customer_123' }],
      },
      pagination: { per_page: 50, starting_after: startingAfter },
    }),
  });
  conversations.push(...page.conversations);
  // `next` is ABSENT on the last page, so this loop terminates on its own.
  if (!page.pages?.next) break;
  startingAfter = page.pages.next.starting_after;
}

Where to go next