Developer API Included on every plan

🔑 Authentication & base URL

Create API keys from your dashboard: Messaging API page (each key is an independent instance with its own allowed channels and webhook). Keys are shown once — store them securely.

Base URL:  https://thikaa.com/<your-store>/api/messaging/

Authorization: Bearer <api_key>      (or X-API-Key: <api_key>)

POST Send a message

POST /api/messaging/?action=send

cURL

curl -X POST "https://thikaa.com/<your-store>/api/messaging/?action=send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "wd",
    "to": "9647701234567",
    "message": "تحديث الوظائف الأسبوعي 👇 ..."
  }'

Response

{ "ok": true, "message_id": "...", "channel": "wd", "to": "9647701234567" }

💬 WhatsApp message templates

A pre-approved template is the only lawful way to message a WhatsApp Cloud API (wa) contact who has never written to you, or to reopen a chat after the 24-hour window has closed. Without one, action=send returns 409 no_existing_conversation.

1. List your approved templates

GET /api/messaging/?action=templates

curl "https://thikaa.com/<your-store>/api/messaging/?action=templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "ok": true, "count": 1, "templates": [
    { "name": "order_update", "language": "en", "status": "APPROVED",
      "category": "UTILITY", "body": "Hi {{1}}, your order {{2}} is ready.", "variables": 2 }
] }

2. Send one

POST /api/messaging/?action=send — channel wa only

curl -X POST "https://thikaa.com/<your-store>/api/messaging/?action=send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "wa",
    "to": "+994105156977",
    "template": {
      "name": "order_update",
      "language": "en",
      "variables": ["Nurlan", "#1042"]
    }
  }'

{ "ok": true, "message_id": "wamid...", "conversation_id": 87,
  "template": "order_update", "language": "en", "delivery": "sent" }

GET Account status

GET /api/messaging/?action=status — returns the key’s instance status, allowed channels and current balance.

curl "https://thikaa.com/<your-store>/api/messaging/?action=status" \
  -H "Authorization: Bearer YOUR_API_KEY"

📥 Incoming-message webhooks

Set a webhook URL per API key (Messaging API page). Every inbound customer message on the key’s channels is POSTed to your endpoint as JSON, signed with your key’s secret:

POST <your-webhook-url>
Content-Type: application/json
X-Thikaa-Event: message.received
X-Thikaa-Signature: sha256=<hmac_sha256(body, webhook_secret)>

{ "event": "message.received", "instance_id": "...", "data": {
    "channel": "wa",
    "conversation_id": 1290,
    "message_id": 84990,
    "from": "+9665XXXXXXXX",
    "account": { "id": "1297236690138576", "number": "+994 10 515 69 77", "label": "nurlan_dev" },
    "text": "Where is my order?",
    "attachments": []
} }

Verify the signature (PHP)

$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_THIKAA_SIGNATURE'] ?? '';
$ok   = hash_equals('sha256=' . hash_hmac('sha256', $body, $secret), $sig);

Verify the signature (Node.js)

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-thikaa-signature'] || ''));

🧾 Messaging API event types

Tick the events you want on each API key. The X-Thikaa-Event header and the event field always say which one you are handling.

🔌 Connect your clients’ channels from your own panel

Built for platforms that resell us: your customer never sees a Thikaa login. You mint a connect link, they authorize on Facebook or TikTok, and the page lands in your workspace.

See what is connected

curl "https://thikaa.com/<your-store>/api/messaging/?action=channels" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "ok": true, "channels": [
    { "channel": "wd", "id": "1000017", "name": "Lavida Travel", "identifier": "96555060830", "status": "connected" },
    { "channel": "fb", "id": "100877191952677", "name": "Pawlo Butchery", "status": "connected" },
    { "channel": "ig", "id": "17841478342647968", "name": "Pawlo Butchery", "status": "connected" },
    { "channel": "tt", "id": "-000HFd...", "name": "pawlo_butcher", "status": "connected" } ],
  "counts": { "wd": 1, "fb": 1, "ig": 1, "tt": 1 } }

Facebook, Instagram, TikTok — one link

GET /api/messaging/?action=connect-link&channel=fb        # fb | ig | tt
      &redirect_url=https://your-app.com/done?client=42

{ "ok": true, "channel": "fb",
  "connect_url": "https://www.facebook.com/v21.0/dialog/oauth?...",
  "redirect_url": "https://your-app.com/done?client=42" }

Send your client to connect_url. When they finish, we return them to your redirect_url with the outcome appended — ?thikaa_status=success&channel=fb&connected=2&ids=... — and POST you a signed channel.connected event per connected surface.

One Meta authorization covers both surfaces: connecting a Facebook page also connects its Instagram DMs, and you get two channel.connected events for it.

Telegram — no OAuth, just the token

POST /api/messaging/?action=connect-telegram
{ "bot_token": "8765196861:AAG..." }      # from @BotFather
{ "ok": true, "channel": "tg", "status": "connected", "bot_username": "YourBot" }

WhatsApp QR — pair your client’s number

Pairing code is the primary flow: your client is usually holding the very phone being linked, where a QR on that same screen cannot be scanned.

POST /api/messaging/?action=create-session   { "label": "Clinic Riyadh" }
   -> { "session_token": "wds_...", "account_id": 1000021 }
POST /api/messaging/?action=pair-code        { "session_token": "wds_...", "phone": "+9665XXXXXXXX" }
   -> { "pairing_code": "ABCD-EFGH" }        # client types this into WhatsApp
GET  /api/messaging/?action=session-status&session_token=wds_...
GET  /api/messaging/?action=session-qr&session_token=wds_...      # desktop fallback
POST /api/messaging/?action=delete-session

Disconnect

POST /api/messaging/?action=disconnect-channel
{ "channel": "fb", "id": "100877191952677" }       # fb | ig | tg | tt

{ "ok": true, "channel": "fb", "status": "disconnected",
  "also_disconnected": [ { "channel": "ig", "id": "17841478342647968" } ] }

For Facebook this is a full teardown: we unsubscribe our app from the page at Meta so delivery actually stops, then remove its routing and bot links. channel=ig detaches only the Instagram account and leaves Messenger working. WhatsApp QR uses delete-session.

💭 Comments — Facebook, Instagram & TikTok

Comments are a separate surface from DMs, with their own ids and their own reply mechanism. One event to receive them, two endpoints to read and answer.

{ "event": "comment.received", "data": {
    "platform": "fb",                      # fb | ig | tt
    "comment_id": "1221...._1795...",
    "post_id": "113700101731161_1220987...",
    "parent_id": null,
    "text": "How much is this?",
    "from": { "id": "7051...", "name": "Adham Ammar" },
    "conversation_id": 1841
} }

POST /api/messaging/?action=comment-reply
{ "comment_id": "1221...._1795...",
  "message": "It is 200 SAR",
  "private_message": "Here is the full list..." }   # Meta private reply, opens a real DM

GET /api/messaging/?action=comments&platform=tt&limit=50

🔔 Platform event webhooks

Separately from the Messaging API, the platform can POST admin-level events to a single URL (Settings → Webhooks). Useful events include:

🧠 Bring your own AI key

You can run your bots on your own AI account instead of platform credit: connect an OpenAI, Google Gemini or Anthropic Claude API key from the AI Providers page in your dashboard, then select that connection in your bot’s model settings. Your key is stored per-tenant and used only for your own bots.

⚠️ Errors & limits

Questions? Message us on WhatsApp from the site — a human (or our own bot 😄) will help.