API reference

Overview

The base URL for every request:

https://omniochat.com/api/v1

• Plans. The API and webhooks are included on the Growth and Business plans, and during the free trial. On Starter, requests are refused with 402 upgrade_required.
• JSON. Send Content-Type: application/json and Accept: application/json, except for file uploads, which are multipart/form-data.
• Versioning. The version is in the path. Within v1 we only add — new endpoints, new fields, new events, new reason codes — so ignore fields you do not recognise rather than rejecting them.
• Rate limit. 120 requests a minute per user. Over it you get 429 with a Retry-After header.

Quick start

Create a token under Automate → API & webhooks in the app, then:

# Who am I?
curl https://YOUR-DOMAIN/api/v1/me \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# The five most recent open conversations
curl "https://YOUR-DOMAIN/api/v1/conversations?status=open&per_page=5" \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

# Reply to one
curl -X POST https://YOUR-DOMAIN/api/v1/conversations/CONVERSATION_ID/reply \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"content": "Thanks — it shipped this morning."}'

Authentication

Every request carries a token: Authorization: Bearer <token>. Owners and admins create tokens on the API & webhooks settings page. A token is shown once — store it then.

A token acts as the person who created it, and sees exactly what they see: an agent’s token only reaches the conversations that agent can open in the inbox. It is also limited to its scopes, chosen when it is made. Give each integration its own token with only the scopes it needs, and an expiry, so one leak can be revoked without touching the rest.

A request without the scope it needs gets 403 naming the scope it was missing and the scopes the token does have. GET /me needs no scope, so any token can ask what it is allowed to do.

Requests & responses

• Successful responses wrap their result in data.
• Lists are paginated with page and per_page (at most 100) and carry meta: current_page, per_page, total, last_page.
• Times are ISO 8601 in UTC. Conversation and message ids are 24-character hex strings; contacts, webhook endpoints and deliveries use UUIDs; users, teams, labels, tags and templates use integers.
• Something that does not exist and something your token may not see both answer 404, so an id cannot be used to learn what exists.

{
    "data": [
        {
            "id": "…"
        },
        {
            "id": "…"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 112,
        "last_page": 5
    }
}

Errors

Every error has a human-readable message. Validation errors (422) add errors, keyed by field. Refusals you can act on add a stable, machine-readable reason — branch on that, never on the message text.

{
    "message": "This chat is outside WhatsApp's 24-hour window. Send an approved template to re-engage the contact.",
    "reason": "window_closed"
}

Objects

The same shapes are used in responses and in webhook payloads.

conversation

Lists return the short form, up to last_message_preview; a single conversation returns all of it. can_send_freeform is whether a text reply will go now — when it is false, send a template.

{
    "id": "6710c2f1a9e4b2d7c8f30a11",
    "channel_type": "whatsapp",
    "status": "open",
    "contact": {
        "name": "Sarah Ahmed",
        "external_id": "447700900123"
    },
    "assigned_to": 42,
    "assigned_team": 3,
    "unread_count": 2,
    "last_message_at": "2026-10-18T09:14:03+00:00",
    "last_message_preview": "Has my order shipped yet?",
    "participants": [
        42,
        57
    ],
    "label_ids": [
        5
    ],
    "bot_enabled": false,
    "last_inbound_at": "2026-10-18T09:14:03+00:00",
    "whatsapp_window_open": true,
    "can_send_freeform": true
}

message

direction is inbound or outbound. Outbound status moves pending → sent → delivered → read, or to failed. sent_by is the user who sent it, null for the customer.

{
    "id": "6710c2f1a9e4b2d7c8f30b27",
    "conversation_id": "6710c2f1a9e4b2d7c8f30a11",
    "direction": "inbound",
    "type": "text",
    "content": "Has my order shipped yet?",
    "media_url": null,
    "status": "received",
    "sent_by": null,
    "created_at": "2026-10-18T09:14:03+00:00"
}

note

{
    "id": "6710c3a8a9e4b2d7c8f30c02",
    "body": "Asked for a refund last month too.",
    "user_id": 42,
    "user_name": "Dan Okafor",
    "created_at": "2026-10-18T09:20:44+00:00"
}

contact

{
    "id": "9b1f6a52-3c1e-4c55-9a2e-6f0f1d2b7a40",
    "first_name": "Sarah",
    "last_name": "Ahmed",
    "full_name": "Sarah Ahmed",
    "phone_e164": "+447700900123",
    "email": "sarah@example.com",
    "channel_type": "whatsapp",
    "country": "GB",
    "language": "en",
    "opt_in_whatsapp": true,
    "opt_in_sms": false,
    "opt_in_email": true,
    "custom_fields": {
        "plan": "gold",
        "seats": 4
    },
    "tags": [
        {
            "id": 7,
            "name": "VIP",
            "color": "#7c3aed"
        }
    ],
    "source": "inbound",
    "last_seen_at": "2026-10-18T09:14:03+00:00",
    "created_at": "2026-03-02T11:05:19+00:00"
}

Account

Who the token belongs to, and how much of the plan the workspace has used.

Conversations

The shared inbox. A token sees exactly what its owner sees in the web inbox: owners and admins see every conversation; an agent sees those assigned to them, to one of their teams, or that they have joined. A conversation the token cannot see answers 404, the same as one that does not exist.

Sending messages

Sending needs messages:write, separate from everything else, because it speaks for the business. A send is queued, not delivered: the response says status: pending, and the message moves to sent, delivered, read or failed afterwards — subscribe to message.status_updated to follow it. The first reply to an unassigned conversation assigns it to the token’s user, as in the inbox.

Contacts

Contacts are shared across the workspace. They are addressed by id (a UUID).

Webhook endpoints

Manage where events are sent. Owners and admins only, whatever the token’s scopes: an endpoint receives every event in the workspace, so creating one is the same as being able to read the whole inbox.

Tokens

Most people create tokens on the API & webhooks settings page. These endpoints do the same over the API, for owners and admins, and only with a full-access token — a narrow token cannot make a wider one.

Mobile sign-in

For our mobile app. Integrations should use a token from the settings page instead: these sessions last 90 days and are tied to a person’s password.

Webhooks

Subscribe a URL to events and we POST each one to it as JSON, signed so you can tell it came from us. Set them up on the settings page or with the webhook endpoints API.

Events

data holds the resource in its API shape: message for message events, conversation (full form) for conversation events, contact for contact events. message.status_updated and conversation.status_changed add previous_status; conversation.assigned adds previous { assigned_to, assigned_team }; contact.updated adds changed, the fields that changed. campaign.completed carries a campaign: id, name, channel, status, total, sent, failed, launched_at, completed_at. A test sends webhook.ping.

The request

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: OmnioChat-Webhooks/1.0
X-Webhook-Event: message.received
X-Webhook-Id: 0f3c9a7e-5d21-4b8e-9a64-2c1e7b9d4f10
X-Webhook-Signature: t=1792271957,v1=5f2b…

{
    "id": "0f3c9a7e-5d21-4b8e-9a64-2c1e7b9d4f10",
    "event": "message.received",
    "created_at": "2026-10-18T09:14:04+00:00",
    "data": {
        "message": {
            "id": "6710c2f1a9e4b2d7c8f30b27",
            "conversation_id": "6710c2f1a9e4b2d7c8f30a11",
            "direction": "inbound",
            "type": "text",
            "content": "Has my order shipped yet?",
            "media_url": null,
            "status": "received",
            "sent_by": null,
            "created_at": "2026-10-18T09:14:03+00:00"
        }
    }
}

Verifying the signature

Each endpoint has a signing secret (whsec_…), shown when it is created or rotated. v1 is the hex HMAC-SHA256 of <t>.<raw body> under that secret. Compute it over the raw bytes you received — not re-encoded JSON — compare in constant time, and reject a t more than five minutes from your clock so a captured request cannot be replayed.

// Node.js
const crypto = require('crypto')

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return expected.length === v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
}

<?php // PHP
function verify(string $rawBody, string $header, string $secret): bool
{
    parse_str(str_replace(',', '&', $header), $p);
    if (abs(time() - (int) ($p['t'] ?? 0)) > 300) return false;

    return hash_equals(hash_hmac('sha256', ($p['t'] ?? '').'.'.$rawBody, $secret), (string) ($p['v1'] ?? ''));
}

# Python
import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Delivery

• Answer 2xx within 10 seconds. Do the work afterwards, in a queue: a slow answer counts as a failure.
• Retries. A failed delivery is tried six times in all: now, then after 1 minute, 5 minutes, 1 hour, 1 day and 1 day — about two and a half days.
• Duplicates. A retry can arrive after you processed the original. X-Webhook-Id (and the body’s id) is the same on every attempt and every endpoint: store it and ignore repeats.
• Order. Events usually arrive in order, but retries mean they need not. Use created_at and previous_status rather than arrival order, or fetch the resource for its current state.
• A failing endpoint is turned off. After five deliveries in a row have each used up every attempt — the first of them at least a day earlier — we stop sending, set enabled to false with disabled_reason: failing, and tell the workspace’s owners and admins. Turn it back on when it is fixed, and resend what you missed from its history.
• Redirects are not followed. If your endpoint moves, update its URL.
• URLs must be https and resolve to a public address. Private, loopback and link-local addresses are refused, checked again before every delivery.
• History. Each endpoint’s deliveries — payload, response and attempts — are kept for 30 days. Erasing a conversation or message in the inbox erases it from the history too.
• Plans. Webhooks are part of API access. On Starter nothing is sent; endpoints are kept and resume when you upgrade.