Build with OnloAPI v1View as Markdown

Conversations API v1 Quick Start

Send your first customer conversation to Onlo and find it in Inbox.

For: Teams that want to send customer conversations from their app to Onlo Inbox
Needs: You need a full-access Onlo API key.
Time: 10 minutes

Before you start

Plan: Onlo Starter or above
Access: Sign in as an Owner or Admin
API tool: Use Postman, curl, or another API client

How to send your first conversation

Use the Conversations API to send customer conversations from your app to Onlo, so your team can handle them in Inbox.

Create your API token
If you do not have an API key, click here.
1. Click Create key.
2. Set Name to Testing and Scope to Full — read + write.
3. Click Create key, then copy the token immediately.
Create a key named Testing with Full — read + write access.
ImportantCopy the token now. Onlo shows it only once.

2
Test connection
This proves your API key can connect to Onlo with Full access.
Method
GET
URL
https://onlo.ai/api/v1/ping
Authorization
TypeBearer TokenTokenPaste your API keyOpen the Authorization tab in Postman.
Headers
Content-Typeapplication/jsonOpen the Headers tab in Postman.
Expected200 OK
type
ping — this is the connection-test response
scope
full — this key can read and write
server_time
The current Onlo server time in Unix seconds, recorded when it answered this ping. It is not a conversation creation time.
Show full responseHide full response
Your organization_id will be different. server_time changes on every request.
```
{
  "type": "ping",
  "organization_id": "...",
  "scope": "full",
  "server_time": 1788323400
}
```
For API key and security details, click here.
NextKeep the same API key. You will use it to create the conversation.
3
Create a conversation
This creates one test conversation for Maya, asks Onlo to answer the first customer message, and stores four conversation attributes.
Fields used here
external_idRequired
Your unique ID for this conversation in your system. Reuse it if you retry.
bodyOptional
The first customer message. Onlo answers it using the workspace’s normal settings. Omit it when you only need an empty conversation record.
fromRequired
The customer attached to this conversation.
from.external_id or from.idRequired
Your unique ID for this customer, or an existing Onlo contact ID. Use only one.
from.typeOptional
Use contact. The API also accepts user, lead, and customer.
from.name / from.email / from.phoneOptional
Customer details your team can recognize in Inbox.
custom_attributesOptional
Flat string, number, or true-or-false values stored on this conversation, not on the contact.
Method
POST
URL
https://onlo.ai/api/v1/conversations
Authorization
TypeBearer TokenTokenPaste your API keyOpen the Authorization tab in Postman.
Headers
Content-Typeapplication/jsonOpen the Headers tab in Postman.
You send external_id. Onlo returns id. Use the returned id in the Get and Update URLs.
BodyBody → raw → JSON
{ "external_id": "support_case_1048", "from": { "type": "contact", "external_id": "customer_4821", "name": "Maya Patel", "email": "maya.patel@example.com" }, "custom_attributes": { "order": "ORD-1001", "reason": "It's something else", "attempts": 2, "paid": false }, "body": "I need help with my order." }
Expected201 Created
type
conversation — this endpoint returned a conversation resource
id
Copy this conversation ID. Onlo generated it for Steps 4 and 5.
message_count
2 in this example — the customer message and Onlo’s reply
reply
Onlo’s immediate response to the first customer message
custom_attributes
order, reason, attempts, paid
Show full responseHide full response
Onlo returns your own conversation and contact IDs. This example hides them as "...".
```
{
  "type": "conversation",
  "id": "...",
  "external_id": "support_case_1048",
  "created_at": 1788323400,
  "updated_at": 1788323400,
  "channel": "api",
  "source": { "type": "api" },
  "state": "open",
  "open": true,
  "status": "active",
  "custom_attributes": {
    "order": "ORD-1001",
    "reason": "It's something else",
    "attempts": 2,
    "paid": false
  },
  "message_count": 2,
  "last_message_at": 1788323400,
  "contact": {
    "type": "contact",
    "id": "...",
    "external_id": "customer_4821",
    "name": "Maya Patel",
    "email": "maya.patel@example.com",
    "phone": null
  },
  "contacts": {
    "type": "contact.list",
    "contacts": [
      {
        "type": "contact",
        "id": "...",
        "external_id": "customer_4821"
      }
    ]
  },
  "reply": {
    "type": "message",
    "id": "...",
    "body": "I can help with that order. What seems to be wrong?",
    "created_at": 1788323401
  }
}
```
For every supported create field, click here.
NextCopy the returned id. You will paste that conversation ID into Steps 4 and 5.

Get the conversation

This proves Onlo saved the conversation and its attributes unchanged.

Fields used here

conversation_idRequired: The id returned by Onlo in Step 3.

Method: GET
URL: https://onlo.ai/api/v1/conversations/<conversation_id>Replace <conversation_id> with the id you copied in Step 3.
Authorization: TypeBearer TokenTokenPaste your API keyOpen the Authorization tab in Postman.
Headers: Content-Typeapplication/jsonOpen the Headers tab in Postman.

Expected200 OK

id: The same id returned in Step 3
order: ORD-1001
reason: It's something else
attempts / paid: 2 / false

Show full responseHide full response

The custom attributes should match the create response exactly.

{
  "type": "conversation",
  "id": "...",
  "external_id": "support_case_1048",
  "created_at": 1788323400,
  "updated_at": 1788323400,
  "channel": "api",
  "source": { "type": "api" },
  "state": "open",
  "open": true,
  "status": "active",
  "custom_attributes": {
    "order": "ORD-1001",
    "reason": "It's something else",
    "attempts": 2,
    "paid": false
  },
  "message_count": 2,
  "last_message_at": 1788323400,
  "contact": {
    "type": "contact",
    "id": "...",
    "external_id": "customer_4821",
    "name": "Maya Patel",
    "email": "maya.patel@example.com",
    "phone": null
  },
  "contacts": {
    "type": "contact.list",
    "contacts": [
      {
        "type": "contact",
        "id": "...",
        "external_id": "customer_4821"
      }
    ]
  },
  "reply": {
    "type": "message",
    "id": "...",
    "body": "I can help with that order. What seems to be wrong?",
    "created_at": 1788323401
  }
}

For full Get details, click here.

NextKeep the same conversation ID. You will update this conversation next.

Update the conversation

This changes attempts to 3 and removes reason by sending null.

Fields used here

conversation_idRequired: The id returned by Onlo in Step 3.
custom_attributesRequired: Only the attributes you want to change or remove.
attemptsOptional: Sending 3 replaces the previous value of 2.
reasonOptional: Sending null removes this attribute.

Method: PUT
URL: https://onlo.ai/api/v1/conversations/<conversation_id>Replace <conversation_id> with the id you copied in Step 3.
Authorization: TypeBearer TokenTokenPaste your API keyOpen the Authorization tab in Postman.
Headers: Content-Typeapplication/jsonOpen the Headers tab in Postman.

BodyBody → raw → JSON

{
  "custom_attributes": {
    "attempts": 3,
    "reason": null
  }
}

Expected200 OK

attempts: 3
reason: Removed
order / paid: ORD-1001 / false (unchanged)

Show full responseHide full response

Omitted attributes stay unchanged. An attribute sent as null is removed.

{
  "type": "conversation",
  "id": "...",
  "external_id": "support_case_1048",
  "created_at": 1788323400,
  "updated_at": 1788323460,
  "channel": "api",
  "source": { "type": "api" },
  "state": "open",
  "open": true,
  "status": "active",
  "custom_attributes": {
    "order": "ORD-1001",
    "attempts": 3,
    "paid": false
  },
  "message_count": 2,
  "last_message_at": 1788323400,
  "contact": {
    "type": "contact",
    "id": "...",
    "external_id": "customer_4821",
    "name": "Maya Patel",
    "email": "maya.patel@example.com",
    "phone": null
  },
  "contacts": {
    "type": "contact.list",
    "contacts": [
      {
        "type": "contact",
        "id": "...",
        "external_id": "customer_4821"
      }
    ]
  }
}

For full Update details, click here.

NextKeep customer_4821 and ORD-1001. You will use both to find this conversation.

Find the conversation

This searches for Maya’s test conversation using the same customer and order values.

Fields used here

queryRequired: The filters Onlo should match.
contact.external_idRequired: Limits the search to customer_4821.
custom_attributes.orderOptional: Narrows the result to order ORD-1001.
paginationOptional: Controls how many matching conversations Onlo returns.

Method: POST
URL: https://onlo.ai/api/v1/conversations/search
Authorization: TypeBearer TokenTokenPaste your API keyOpen the Authorization tab in Postman.
Headers: Content-Typeapplication/jsonOpen the Headers tab in Postman.

BodyBody → raw → JSON

{
  "query": {
    "operator": "AND",
    "value": [
      {
        "field": "contact.external_id",
        "operator": "=",
        "value": "customer_4821"
      },
      {
        "field": "custom_attributes.order",
        "operator": "=",
        "value": "ORD-1001"
      }
    ]
  },
  "pagination": {
    "per_page": 50,
    "starting_after": null
  }
}

Expected200 OK

total_count: 1
conversations[0].id: The same conversation id returned in Step 3

Show full responseHide full response

The returned record contains the updated attributes from Step 5.

{
  "type": "conversation.list",
  "conversations": [
    {
      "type": "conversation",
      "id": "...",
      "external_id": "support_case_1048",
      "created_at": 1788323400,
      "updated_at": 1788323460,
      "channel": "api",
      "source": { "type": "api" },
      "state": "open",
      "open": true,
      "status": "active",
      "custom_attributes": {
        "order": "ORD-1001",
        "attempts": 3,
        "paid": false
      },
      "message_count": 2,
      "last_message_at": 1788323400,
      "contact": {
        "type": "contact",
        "id": "...",
        "external_id": "customer_4821",
        "name": "Maya Patel",
        "email": "maya.patel@example.com",
        "phone": null
      },
      "contacts": {
        "type": "contact.list",
        "contacts": [
          {
            "type": "contact",
            "id": "...",
            "external_id": "customer_4821"
          }
        ]
      }
    }
  ],
  "total_count": 1,
  "pages": {
    "type": "pages",
    "page": 1,
    "per_page": 50
  }
}

For all search fields and operators, click here.

NextOpen Onlo Inbox and confirm the same conversation is visible to your team.

Verify in Onlo
Open Dashboard → Inbox, select Maya’s test conversation, then open This conversation → Custom attributes.
Select the test conversation.
Open This conversation and check Custom attributes.
The screenshots are cropped and marked so you can find the two controls quickly.
Expected
order
ORD-1001
attempts
3
paid
false
reason
Not shown because Step 5 removed it
For the complete API Reference, click here.

Your Conversations API setup is working.

Before you start

How to send your first conversation

Create your API token

Fields used here

Fields used here

Fields used here

Fields used here