Skip to content
uniboxTry it free

API

Connecting another system

A key lets your ERP, site or script read what is in the inbox and reply inside a conversation. A webhook tells it when something happened here.

Getting a key

Settings → API and webhooks → Create key. The key is shown once: we store only a hash of it, so nobody — including us — can read it back to you afterwards. If it is lost, revoke it and make another.

Send it on every request. Ten live keys per workspace, a thousand requests an hour per key.

curl https://unibox.chat/api/v1/conversations \
  -H "Authorization: Bearer ubx_…"

What you can read

Everything is scoped to the workspace the key belongs to. limit defaults to 50 and caps at 200.

GET /api/v1/conversations
GET /api/v1/conversations/{id}
GET /api/v1/conversations/{id}/messages
GET /api/v1/contacts

A conversation carries its assignee, its first-response time in seconds, its satisfaction score if one came back, and the tracked link it came from. A contact carries your own custom fields under custom.

What you can write

One thing: a reply, into a conversation that already exists.

POST /api/v1/conversations/{id}/messages
{"body": "Saiu hoje, chega quinta."}

There is deliberately no endpoint that starts a conversation or sends to a number. Every workspace here shares one WhatsApp gateway and one egress IP, so a public send-to-anyone endpoint would put every customer's number at risk of being blocked for something one script did. Sends also count against the same hourly and daily ceiling the inbox obeys, and come back as 429 when it is reached.

Webhooks

Add an https endpoint in the same panel and pick the events. We POST JSON:

{
  "event": "deal.won",
  "deliveryId": "…",
  "attempt": 1,
  "data": { "cardId": "…", "contactId": "…", "valueCents": 250000, … }
}

Events: message.received, message.sent, conversation.assigned, deal.won, deal.lost.

Each delivery is signed. The header is X-Unibox-Signature: t=<unix>,v1=<hex>, where the hex is an HMAC-SHA256 of "<t>.<raw body>" using your endpoint secret. Verify it before trusting the payload, and reject a timestamp that is not recent — the timestamp is inside the signed string precisely so a captured delivery cannot be replayed later.

Answer with any 2xx. A failure is retried with a growing delay — one minute, four, sixteen, then hourly — and an endpoint that has failed twenty times in a row is switched off and says so in settings.

Errors

Every error is {"error", "message"}. 401 for a missing or wrong key, 404 for something that is not in your workspace, 429 for the hourly key limit or the sending ceiling, 502 when WhatsApp itself refused.

Something missing that you need? Tell us — this is version one and it is short on purpose.

API — Unibox