Skip to content

Developer API and webhooks

Connect your shop, booking system or CRM to your Inbox: send a WhatsApp template when an order ships, read conversations, tag contacts, and hear about new messages as they arrive. The API and webhooks come with Pro, Agency and every lifetime plan.

Your API key

  1. In the dashboard, open Developers in the sidebar and create a key. You can limit it to one site.
  2. Copy it right away: it starts with rk_ and is shown only once. You can revoke it there at any time.

Send it in the Authorization header as Bearer rk_…, to addresses under https://app.talkixa.com/api/v1. Each key can make about 60 requests a minute; past that you get 429 with a Retry-After header.

Send a WhatsApp template

For order updates, reminders and anything else outside WhatsApp’s 24-hour window. First find your number’s ID: it’s the id that GET /connections lists for it.

curl https://app.talkixa.com/api/v1/connections -H "Authorization: Bearer rk_..."

{ "connections": [
  { "id": "c7k2m9x4q1aa", "siteId": "k3j9x2m7qa", "type": "whatsapp", "name": "+20 100 123 4567", "status": "active" }
] }

Then send one of your approved templates, with its values in order:

curl -X POST https://app.talkixa.com/api/v1/whatsapp/send \
  -H "Authorization: Bearer rk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "c7k2m9x4q1aa",
    "to": "+201001234567",
    "template": "order_update",
    "language": "en_US",
    "values": ["Omar", "1042"]
  }'

The answer has the conversation and the message, with status 201 when it started a new conversation and 200 when it continued one. The message shows in the customer’s conversation in your Inbox, marked as sent by your key, and the customer’s reply continues it. Marketing templates aren’t sent to people who unsubscribed from your broadcasts (409 unsubscribed); order updates and codes still are. Meta bills your WhatsApp account for template messages, as it does when you send them from the Inbox.

Other requests

RequestWhat it does
GET /connectionsYour connected numbers, bots, Pages and Instagram accounts, with their IDs.
POST /conversations/:id/messagesReplies in a conversation, inside its channel’s reply window (24 hours after the customer’s last message on WhatsApp, Messenger and Instagram). Body: {"text": "…"}.
GET /conversations50 at a time, newest first, with before (Unix seconds) for older ones. Or, to follow along, since (Unix seconds): the ones with news after it, oldest first, 100 at a time. Filters: status (open or closed), channel,site, and q, which searches the messages’ text.
GET /conversations/:id/messages100 messages at a time after the message after. Your team’s notes are included.
GET /contactsEveryone who wrote, 50 at a time by latest activity, with before, q, tag, stage, channel and site.
POST /ordersPushes an order from your shop, so the customer can track it on your button. Body: site, items(name, quantity, price), customer (name, phone, email), and optionally your own number, status, note and tracking. A number you already sent answers 409 order_exists.
GET /orders50 at a time, newest first, with before from the last page, site and status.
PATCH /orders/:idChanges its status (new, confirmed, shipped, delivered, cancelled),tracking or teamNote. The customer hears about a new status as from your dashboard; told in the answer says how: conversation, template, or null when nothing could reach them.
GET /bookingsThe coming ones, soonest first, or the past ones with when=past, 50 at a time with cursor, site and status.
PATCH /bookings/:idChanges its status, moves it (start, Unix seconds), gives it to someone of your team (staffId), or setsteamNote. A time that’s taken answers 409 slot_taken, unless "force": true. Answers with told, like orders.
PATCH /contacts/:idKeeps your CRM in step: sets a contact’s tags (new ones are made) and their pipeline stage (new, qualified,won, lost, or null). Body: {"tags": ["VIP"], "stage": "won"}, either or both.

Errors come back as {"error": "…"} with a status: 401 for a missing or revoked key, 402 on the Free plan, 404 for something that isn’t there or isn’t in your key’s sites, 409 for an unsubscribed contact, 422 for a request to fix, 429 over the limit, and 502 when the channel refused a message, with its reason in details.

Webhooks

Under Developers, add a webhook address for a site (https, up to 5 per site) and choose its events:

  • conversation.created: someone started a conversation, on any channel.
  • message.received: a customer wrote.
  • message.sent: your team, the assistant, an automation or the API replied.
  • conversation.assigned and conversation.closed.
  • order.created, order.updated, booking.created and booking.updated, with the whole order or booking.

Each event is posted as JSON, with createdAt in Unix seconds:

{
  "id": "evt_8f2k1m9x4q1aa7c3",
  "event": "message.received",
  "createdAt": 1792656600,
  "site": { "id": "k3j9x2m7qa", "name": "Cedar Dental" },
  "conversation": { "id": "9krza0s6y9y3", "channel": "whatsapp", "status": "open", "...": "..." },
  "message": { "id": 812, "direction": "in", "body": "Can I come at 4?", "...": "..." }
}

Requests carry X-Webhook-Event, X-Webhook-Id and X-Signature-256: sha256= followed by the HMAC-SHA256 of the raw body, keyed with the webhook’s signing secret. Check it before trusting a request:

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body exactly as received, before any JSON parsing.
function isFromReachly(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader ?? '');
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Answer within 5 seconds with any 2xx status. Each event is sent once, without retries, so use GET /conversations?since= to catch up after downtime. Test sends a ping event, and the page shows how the last delivery went. Broadcast messages and conversations closed for being quiet don’t send events.