WhatsApp Assistant API

How it works

1. Link your number. Scan a QR code from WhatsApp (Settings, Linked devices). No Meta approval and no waiting. Use a number dedicated to the business.
2. A customer messages your number. For example “order”.
3. We route it. A starter keyword can send it to your website, otherwise the AI assistant answers from your business info (or your website handles everything, if you choose that).
4. Your website receives a signed request with the customer's phone, name and message. It answers in the response, or replies later with the send API.
5. The customer sees your reply on WhatsApp: text, a receipt PDF, an image. Your website decides when the guided session is over and the assistant takes back over.

Quick start

1. Open Dashboard, WhatsApp Assistant, add a number and start the free trial (7 days, 100 messages, every feature).
2. Connect tab: scan the QR code.
3. Keywords tab: add a rule, for example the words order, menu, action Hand over to my website.
4. My website tab: enter your https address, copy the signing secret, press Send a test message.
5. Message your number from another phone and send “order”.

Plans & limits

Billed monthly from your wallet (30-day periods, renewed automatically; stop any time). A message is one customer message we handle, whichever way it's answered.

• Reply window: how long after a customer writes you can still reply through the API.
• When messages run out, automatic answers pause and the customer's messages are still saved. We email you at 80% and 100%. Upgrading takes effect at once and charges only the difference for the days left. Downgrades apply at renewal.
• If renewal fails (wallet too low) you have 3 days of grace before answers pause.
• Your month starts the day you pay. We email you 7 days, 3 days and on the day before it renews or ends (with a link to top up or renew), and the dashboard shows the days left.
• Messages nobody answered: if a customer writes something no keyword, website or assistant handled, the chat is flagged “Needs you” and you get an email, so nothing is silently missed.

Authentication

Calls to /v1/wa/* use your secret API key in the X-IdentifyOrg-Key header (or a dashboard login). Requests we send to your website are authenticated by the signature described below, so keep the signing secret private.

Key ideas

• Channel: one linked WhatsApp number, with its business info, keywords and website address.
• Conversation: one customer on one channel. Customers are identified by phone number.
• Phone numbers: you never type your business number anywhere: it is the phone that scans the QR code. When your code sends a customer's number (the to field, or phone), use digits only, with the country code, no +, no spaces and no leading 0, like 2348012345678. We also accept +234 801 234 5678 and Nigerian 0801 234 5678 and convert them, but for other countries always include the country code. The numbers in webhooks always arrive in the digits-only form.
• Who answers a message: (1) a person, if the owner took over the chat; (2) your website, if a guided session is active; (3) the first matching keyword rule; (4) otherwise the assistant, or your website if you set the number to “my website handles everything else”.
• Guided session: a stretch where every message from one customer goes to your website, started by a keyword and ended by your website.

Receiving messages

We send a POST with a JSON body to your website address for each customer message routed to it. Respond with 2xx within 8 seconds.

POST https://yourshop.com/api/whatsapp
Content-Type: application/json
X-IdentifyOrg-Event: message
X-IdentifyOrg-Event-Id: 3EB0C767D0E5A1F2B7
X-IdentifyOrg-Signature: t=1791650000,v1=9f2b…c41a

{
  "id": "3EB0C767D0E5A1F2B7",
  "type": "message",
  "created_at": "2026-10-10T16:40:12.114Z",
  "channel_id": "5b1f3c1e-…",
  "conversation_id": "a77d90c2-…",
  "customer": { "phone": "2348012345678", "name": "Tola" },
  "message": { "type": "text", "text": "order jollof x2" },
  "session": { "active": true, "keyword": "order" }
}

• message.type is text, or image, audio, video, document, sticker, location. Only text is passed through as text; for other types text is the caption, or empty. For location (a pin the customer shares) the message also carries location: { lat, lng, name }.
• id is unique per message: use it to ignore duplicates (we retry failures).
• type: "test" is sent by the dashboard's test button.
• Retries: if your website times out or returns a non-2xx status, we try again after 5 seconds and again after 30 seconds. If it still fails, the customer gets your fallback message (if you set one) and the chat is flagged for you.
• Redirects are not followed, and your address must be a public https URL.

Verifying signatures

The X-IdentifyOrg-Signature header is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw request body>" using your signing secret. Compute it over the raw body exactly as received (not re-serialised JSON), compare in constant time, and reject timestamps older than five minutes.

import crypto from "node:crypto";

// rawBody must be the exact bytes we sent (before JSON parsing).
export function verifyWhatsApp(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 ?? "");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < toleranceSeconds;
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib, time

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

<?php
function verify_whatsapp(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    parse_str(str_replace(',', '&', $header), $p);
    $expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
    return abs(time() - (int)$p['t']) < $tolerance && hash_equals($expected, $p['v1'] ?? '');
}

func verifyWhatsApp(raw []byte, header, secret string) bool {
	parts := map[string]string{}
	for _, kv := range strings.Split(header, ",") {
		if k, v, ok := strings.Cut(kv, "="); ok { parts[k] = v }
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(parts["t"] + "."))
	mac.Write(raw)
	ts, _ := strconv.ParseInt(parts["t"], 10, 64)
	fresh := math.Abs(float64(time.Now().Unix()-ts)) < 300
	return fresh && hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(parts["v1"]))
}

Replying

You have two ways to answer, and can mix them.

1. In the response (simplest)

Return JSON from your webhook. reply is one message; replies is up to 6, sent in order. Each can be a string or an object (text, image, document).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "replies": [
    "Great choice, Tola! Jollof rice x2 is ₦5,000.",
    "Reply 1 to pay by transfer, 2 to pay on delivery."
  ],
  "session": "continue"
}

2. Later, through the API

Return an empty 200, process the order, then reply when ready. Order updates, payment confirmations and receipts work this way. You can only reply to customers who messaged within your plan's reply window.

curl -X POST https://api.identifyorg.com/v1/wa/channels/CHANNEL_ID/send \
  -H "X-IdentifyOrg-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "2348012345678",
    "text": "Order #1042 is out for delivery. Rider: Emeka, 0803 000 0000."
  }'

Images & documents

Available on Business and above (and in the trial). Provide a public url we can fetch, or base64 data.

{
  "replies": [
    { "type": "text", "text": "Payment received. Thank you! Your receipt is attached." },
    {
      "type": "document",
      "url": "https://yourshop.com/receipts/INV-1042.pdf",
      "filename": "receipt-INV-1042.pdf",
      "caption": "Receipt INV-1042"
    }
  ],
  "session": "end"
}

curl -X POST https://api.identifyorg.com/v1/wa/channels/CHANNEL_ID/send \
  -H "X-IdentifyOrg-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "2348012345678",
    "text": "Payment received. Here is your receipt.",
    "media": {
      "kind": "document",
      "url": "https://yourshop.com/receipts/INV-1042.pdf",
      "filename": "receipt-INV-1042.pdf"
    }
  }'

• Images: JPEG, PNG, WebP. Documents: PDF, Word, Excel, plain text, CSV.
• Maximum 5 MB. caption shows under images and documents.
• URLs must be public (no internal addresses) and are fetched once, without following redirects.

Guided sessions

A session is a conversation your website drives step by step: menu, choose, confirm, pay. While it's active, every message from that customer goes to your website, so you don't need to repeat the keyword. Start one with a keyword rule (action “Hand over to my website”), by returning "session": "start", or by sending with "session": "start" in the send API. End it with "session": "end" in a response, or POST /v1/wa/channels/{id}/sessions/end. A session also ends by itself after 30 minutes of silence, and the event always tells you whether one is active (session.active). Keep your own state, keyed by the customer's phone number.

OTP & identity checks

Use your linked number to send one-time codes, or to confirm a person is who they say they are, without waiting for Meta's business approval. Available on Growth and above.

One-time codes

Pass the number and we deliver a fresh code from your number, worded as your brand. Codes are stored only as a one-way hash, expire after the time you set (default 10 minutes), and lock after 5 wrong tries.

# 1. Send the code
curl -X POST https://api.identifyorg.com/v1/wa/channels/CHANNEL_ID/otp \
  -H "X-IdentifyOrg-Key: YOUR_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "to": "2348012345678", "brand": "Acme Pay", "ttl_minutes": 10 }'

# 2. When the person types the code into your app, check it
curl -X POST https://api.identifyorg.com/v1/wa/channels/CHANNEL_ID/otp/verify \
  -H "X-IdentifyOrg-Key: YOUR_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "to": "2348012345678", "code": "483920" }'
# -> { "valid": true }

Identity checks

Send a question and the right answer from your own records. The person replies on WhatsApp; we compare it (ignoring case, spaces and punctuation) and tell you the result. The expected answer is stored only as a one-way hash, and the person gets 3 tries by default. If your website is connected, a signed event of type verification is sent to it when the check ends.

# Ask the person a question only they can answer (the answer comes from your own records)
curl -X POST https://api.identifyorg.com/v1/wa/channels/CHANNEL_ID/verify-identity \
  -H "X-IdentifyOrg-Key: YOUR_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "to": "2348012345678", "question": "What is your date of birth? (DD/MM/YYYY)", "expected": "12/03/1990", "reference": "customer_8841" }'
# -> { "id": "...", "status": "pending" }

# The person replies on WhatsApp. Then check the result (or wait for the signed "verification" event on your website):
curl https://api.identifyorg.com/v1/wa/channels/CHANNEL_ID/verify-identity/VERIFICATION_ID -H "X-IdentifyOrg-Key: YOUR_SECRET_KEY"
# -> { "status": "verified" }   (or "failed" / "expired" / "pending")

Safeguards

• Only codes and verification questions can be sent to people who haven't messaged you first, never free text.
• At most 3 per person per hour and 8 per day, plus a daily cap for your plan (Growth 100, Business 500, Scale 2,000, Enterprise 5,000).
• Each message counts toward your monthly messages.
• Numbers are linked by QR, so WhatsApp can limit a number that people report. Only message people who are expecting it (for example, right after they ask to sign in).

Starter keywords

Rules are checked in order against the customer's message (case and punctuation ignored). Set them in the dashboard, or with PUT /v1/wa/channels/{id}/rules.

{
  "rules": [
    { "words": ["order", "menu", "food"], "match": "starts", "action": "site" },
    { "words": ["hours", "open"],         "match": "contains", "action": "reply",
      "reply": "Hi {name}, we are open 8am to 9pm, Monday to Saturday." },
    { "words": ["search", "find"],        "match": "starts", "action": "guide",
      "reply": "What are you looking for, {name}? Type a product, a place or a budget, like 'jollof under 3000'." },
    { "words": ["human", "agent"],        "match": "exact", "action": "ai" }
  ]
}

• match: exact (the whole message), starts (begins with the word), contains (the word appears).
• action: reply sends your fixed text; guide sends a message telling the customer what they can reply with or search for, then passes whatever they type next to your website (or the assistant if no website is connected); site starts a guided session with your website straight away; ai lets the assistant answer.
• Up to 30 rules; {name} in a reply becomes the customer's first name.

Train the AI

On Business and above, the assistant can learn from your own website and documents, so it answers with your real prices, policies and details instead of only the short business profile. It looks through everything you taught it, takes the passages most relevant to the customer's question, and answers from those in your tone. Anything not covered still goes to you.

• POST /v1/wa/channels/{id}/knowledge/website with { "url": "https://yourshop.com" } reads your public pages (following your links) and learns from each page.
• POST /v1/wa/channels/{id}/knowledge/file (multipart file): PDF, Word (.docx), text, Markdown or CSV up to 8 MB.
• POST /v1/wa/channels/{id}/knowledge/text with { "title", "text" }.
• GET the same path lists what it knows; DELETE /v1/wa/channels/{id}/knowledge/{source_id} makes it forget one.
• Each page, document or pasted text uses one slot. Slots per plan are in the table above.

Example: food ordering

A customer sends “order”, picks items from a numbered menu, confirms, and receives payment details with an invoice PDF, all handled by your server. The keyword rule order, menu starts the session; "session": "end" returns the chat to the assistant afterwards.

import express from "express";
import { verifyWhatsApp } from "./verify.js";

const app = express();
const SECRET = process.env.WA_SECRET;            // whsec_... from the "My website" tab
const carts = new Map();                         // phone -> { step, items }

// Keep the raw body: the signature is calculated over it.
app.post("/api/whatsapp", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyWhatsApp(raw, req.get("X-IdentifyOrg-Signature") ?? "", SECRET)) return res.sendStatus(401);

  const event = JSON.parse(raw);
  if (event.type === "test") return res.json({ reply: "Test received ✅" });

  const phone = event.customer.phone;
  const text = (event.message.text ?? "").trim().toLowerCase();
  const cart = carts.get(phone) ?? { step: "menu", items: [] };

  if (cart.step === "menu") {
    cart.step = "choose";
    carts.set(phone, cart);
    return res.json({
      replies: ["Hi " + (event.customer.name ?? "there") + "! What would you like?\n1. Jollof rice ₦2,500\n2. Fried rice ₦2,800\n3. Chicken ₦1,500"],
      session: "continue",
    });
  }
  if (cart.step === "choose" && ["1", "2", "3"].includes(text)) {
    cart.items.push(text); cart.step = "confirm"; carts.set(phone, cart);
    return res.json({ reply: "Added. Reply YES to place your order, or another number to add more.", session: "continue" });
  }
  if (cart.step === "confirm" && text === "yes") {
    carts.delete(phone);
    const invoice = createOrder(phone, cart.items);   // your own order logic
    return res.json({
      replies: [
        { type: "text", text: "Order placed! Pay ₦" + invoice.total + " to 0123456789 (Mama's Kitchen). We'll confirm when it lands." },
        { type: "document", url: invoice.pdfUrl, filename: "invoice.pdf", caption: "Invoice " + invoice.id },
      ],
      session: "end",                                  // hand the chat back to the assistant
    });
  }
  return res.json({ reply: "Sorry, I didn't get that. Reply with a number from the menu.", session: "continue" });
});

Later, when payment arrives, confirm it with POST /v1/wa/channels/{id}/send using the phone number you stored. No one needs to touch WhatsApp.

Endpoint reference

Base URL https://api.identifyorg.com. Send X-IdentifyOrg-Key with your secret key.

Errors

Errors use the standard shape { "error": { "code", "message", "status" } }.

Fair use

• This is a customer-service channel: reply to people who wrote to you. The API refuses to message anyone outside your reply window, and bulk or unsolicited messaging isn't supported.
• A number sends at most 20 messages a minute, and replies show a short “typing…” pause.
• Use a number dedicated to the business, and keep the phone online now and then so WhatsApp keeps the link active.
• Be honest with customers that they are talking to an automated assistant when asked.
• Do not collect card numbers or passwords over WhatsApp.