Quickstart

This guide walks you through making your first API calls to oHallo — listing conversations, reading messages, and sending a reply. By the end, you will have a working integration you can build on.

Step 1: Get an API key

Open the oHallo dashboard.
Go to Settings then API Access.
Click + New API key.
Give it a name (e.g. “Dev testing”).
Select the scopes you need. For this quickstart, select conversations:read and conversations:write.
Click Create. Copy the key — it starts with sf_live_v1_ and is only shown once.

Store the key securely. If you lose it, revoke it and create a new one.

Step 2: List your conversations

Use the API key to fetch your recent conversations:

curl -s https://api.ohallo.eu/api/conversations \
  -H "Authorization: Bearer sf_live_v1_your_key_here" | jq .

Response:

{
  "data": [
    {
      "id": "c9f8e7d6-b5a4-3210-fedc-ba9876543210",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "channelId": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
      "contactId": "11223344-5566-7788-99aa-bbccddeeff00",
      "status": "open",
      "lastMessagePreview": "Hi, my order #4521 was placed three days ago and...",
      "lastMessageAt": "2026-03-20T14:32:00Z",
      "contactName": "Jane Smith",
      "contactEmail": "jane@acme.com"
    },
    {
      "id": "aabbccdd-eeff-1122-3344-556677889900",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "channelId": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
      "contactId": "55667788-99aa-bbcc-ddee-ff0011223344",
      "status": "resolved",
      "lastMessagePreview": "Thanks for confirming the bulk pricing.",
      "lastMessageAt": "2026-03-19T11:45:00Z",
      "contactName": "Tom Berger",
      "contactEmail": "tom@globex.com"
    }
  ],
  "nextCursor": "eyJsYXN0SWQiOiJhYWJiY2NkZC0..."
}

Pagination is cursor-based. Pass ?limit=50&cursor=<nextCursor> to fetch the next page. The default limit is 50, the maximum is 100. When nextCursor is omitted from the response, you’ve reached the end.

The status field tells you the conversation’s current state. See the Conversations API reference for the full list of statuses.

Step 3: Read a conversation’s messages

Pick a conversation ID from the list and fetch its messages:

curl -s https://api.ohallo.eu/api/conversations/c9f8e7d6-b5a4-3210-fedc-ba9876543210/messages \
  -H "Authorization: Bearer sf_live_v1_your_key_here" | jq .

Response (a bare JSON array, ordered chronologically):

[
  {
    "id": "11111111-2222-3333-4444-555555555555",
    "direction": "inbound",
    "speaker": null,
    "body": "Hi, could you check the status of order ORD-48291? It was supposed to arrive last week.",
    "sentAt": "2026-03-20T14:30:00Z",
    "channel": "email",
    "fromAddress": "jane@acme.com"
  },
  {
    "id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
    "direction": "outbound",
    "speaker": null,
    "body": "Hello Jane, I have checked your order ORD-48291. It shipped on March 18th via EuroExpress and is currently in transit. The updated estimated delivery is March 22nd. I apologise for the delay.",
    "sentAt": "2026-03-20T14:32:00Z",
    "channel": "email"
  }
]

Each message includes:

direction — inbound (from the customer) or outbound (from your team or the AI)
speaker — "caller" or "ai" on voice channels (where every message is direction inbound); null on text channels
fromAddress — the sender’s email or phone identifier (when the source channel carries it)
body — the message content
sentAt — ISO 8601 timestamp of when the message was sent or received
channel — the channel type the message arrived on (email, chat, whatsapp, voice, …)

Step 4: Reply to a conversation

Send a reply to the conversation. This requires the conversations:write scope on your API key. The reply is delivered to the customer via the original channel (email, WhatsApp, chat, voice) and recorded in the conversation history.

curl -s -X POST https://api.ohallo.eu/api/conversations/c9f8e7d6-b5a4-3210-fedc-ba9876543210/reply \
  -H "Authorization: Bearer sf_live_v1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hi Jane, a quick update -- your order has been delivered. Could you confirm you received it?"
  }' | jq .

Response on success:

{ "ok": true }

Step 5: Check what happened

Fetch the messages again and pick the last one to confirm your reply was recorded:

curl -s https://api.ohallo.eu/api/conversations/c9f8e7d6-b5a4-3210-fedc-ba9876543210/messages \
  -H "Authorization: Bearer sf_live_v1_your_key_here" | jq '.[-1]'

You should see your reply as the latest message:

{
  "id": "77777777-8888-4999-a000-bbbbbbbbbbbb",
  "direction": "outbound",
  "speaker": null,
  "body": "Hi Jane, a quick update -- your order has been delivered. Could you confirm you received it?",
  "sentAt": "2026-03-20T15:10:00Z",
  "channel": "email"
}

Next steps

You now know how to read and write conversation data through the API. From here:

Authentication — learn about API key scopes and security
Managing the Knowledge Base — programmatically manage KB entries
Build an MCP Server — connect oHallo to your business systems
Building a Custom Agent — create a specialist agent with custom tools