A WhatsApp assistant for every client you serve

How it works

1. Create a workspace for each client business. One workspace is one WhatsApp number.
2. Link the number. Send the client to a connect page with your name and logo, or draw the QR code in your own screens.
3. Tell it about the business with a few fields, rules and, if you like, your own system for orders and bills.
4. We answer their customers on WhatsApp, day and night, and hand over to a person when needed.
5. You watch usage and billing in your dashboard and by API, per workspace.

Everything below can also be done by hand from your dashboard under WhatsApp → Platform, so you can see each step before you code it.

Quick start

Use a test key (io_test_sk_…) for this whole section. It costs nothing and touches no real number. Get a key in API Keys. All requests go to https://api.identifyorg.com with the header X-IdentifyOrg-Key.

1. Create a workspace

curl -X POST https://api.identifyorg.com/v1/wa/channels \
  -H "X-IdentifyOrg-Key: io_test_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Ada Stores",
    "external_id": "client_8841",
    "ai_enabled": true,
    "brand": { "name": "YourPlatform", "color": "#0a7f3f", "logo_url": "https://yourplatform.com/logo.png" },
    "profile": {
      "business_name": "Ada Stores",
      "about": "We sell phones and accessories in Yaba, Lagos.",
      "services": "Phones, chargers, repairs, airtime.",
      "hours": "Mon to Sat, 9am to 6pm",
      "tone": "friendly",
      "language": "English"
    }
  }'

HTTP/1.1 201 Created

{
  "id": "5b1f3c1e-7a42-4d0e-9a2c-1f0c7a1d9e33",
  "label": "Ada Stores",
  "business_name": "Ada Stores",
  "status": "new",
  "ai_enabled": true,
  "profile_ready": true,
  "external_id": "client_8841",
  "test": true,
  "brand": { "name": "YourPlatform", "color": "#0a7f3f", "logo_url": "https://yourplatform.com/logo.png" },
  "connect_url": "https://identifyorg.com/connect/Qm4k…",
  "phone": null,
  "msgs_in": 0,
  "created_at": "2026-10-14T09:12:03Z"
}

2. Start linking

POST /v1/wa/channels/{id}/connect

{
  "status": "pairing",
  "qr": "identifyorg-test-qr:Qm4k…",      // null on live workspaces: fetch it with GET (below)
  "connect_url": "https://identifyorg.com/connect/Qm4k…",
  "test": true
}

3. Pretend the QR code was scanned

curl -X POST https://api.identifyorg.com/v1/wa/channels/$ID/test/scan \
  -H "X-IdentifyOrg-Key: io_test_sk_xxxxxxxx"

{ "status": "connected", "phone": "2340000000000", "test": true }

4. Send a pretend customer message

curl -X POST https://api.identifyorg.com/v1/wa/channels/$ID/test/inbound \
  -H "X-IdentifyOrg-Key: io_test_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "text": "How much is a Samsung A15?", "from_phone": "2348012345678", "name": "Tola" }'

{
  "replies": [ { "type": "text", "text": "The Samsung A15 is ₦185,000. Want me to hold one for you?" } ],
  "conversation_id": "a77d90c2-…",
  "needs_human": false,
  "charged": 0,
  "test": true
}

That is the whole loop. Swap the test key for a live key when you are ready (see Go live).

Test mode

• A test key creates test workspaces. They are completely separate from live ones: a test key cannot see, change or message a live workspace, and the other way round.
• Linking is pretend. POST /connect returns a placeholder QR string. POST /test/scan makes the workspace connected, exactly as a real scan would, and sends the whatsapp.connected webhook.
• POST /test/inbound sends a pretend customer message through the real pipeline: your keyword rules, your own system (signed the same way as live, so you can test your endpoint and signature check) and the assistant. You get back the replies that would have been sent. Nothing goes to WhatsApp.
• Test replies are never billed. Usage is recorded separately so you can see it with GET /usage using a test key.
• You can keep 25 test workspaces and send up to 120 test messages an hour.
• From the dashboard, switch the mode bar to Test to do the same by clicking.

Workspaces

A workspace is one client business with one WhatsApp number, its own information, rules, conversations and usage. Nobody can see another account's workspaces.

POST /v1/wa/channels

• GET /v1/wa/channels lists your workspaces. Add ?external_id=client_8841 to find one.
• GET /v1/wa/channels/{id} returns one workspace with live status and the QR code while pairing.
• PATCH /v1/wa/channels/{id} changes label, ai_enabled, mode or brand.
• POST /v1/wa/channels/{id}/disconnect unlinks the number. DELETE /v1/wa/channels/{id} removes the workspace and its conversations.

Linking a number

The client opens WhatsApp on the phone that holds the business number, goes to Linked devices, and scans a QR code. You can show that QR code in two ways.

Option A: the hosted connect page (nothing to build)

Every workspace has a connect_url. Redirect your client to it, or put it in a frame. It shows your name, logo and colour, the QR code (refreshed automatically), the steps, and a success message when linked. Nothing on it says IdentifyOrg unless you leave the brand empty.

<iframe
  src="https://identifyorg.com/connect/Qm4k…"
  style="width:100%;max-width:420px;height:560px;border:0;border-radius:16px"
  allow="clipboard-write"></iframe>

Option B: draw the QR code yourself

Call POST /connect, then poll GET /channels/{id} every 2 seconds. While status is pairing the response has a qr string. Draw it with any QR library. It changes about every 20 seconds, so always draw the latest one. Stop polling when status becomes connected, or listen for the whatsapp.connected webhook.

GET /v1/wa/channels/{id}          // poll every 2 seconds while status is "pairing"

{
  "id": "5b1f3c1e-…",
  "status": "pairing",              // new → pairing → connected   (also: disconnected, logged_out)
  "qr": "2@Vh3…",                   // the text to draw as a QR code. Present only while status is "pairing".
  "phone": null,                    // filled in once connected
  ...
}

A typical integration

import { IdentifyOrgClient } from "@identifyorg/node-sdk"; // or plain fetch, see the cURL examples

const API = "https://api.identifyorg.com";
const headers = { "X-IdentifyOrg-Key": process.env.IDENTIFYORG_KEY, "Content-Type": "application/json" };
const call = (path, method = "GET", body) =>
  fetch(API + path, { method, headers, body: body ? JSON.stringify(body) : undefined }).then(async (r) => {
    const data = await r.json();
    if (!r.ok) throw new Error(data.error?.message ?? r.statusText);
    return data;
  });

// 1. when one of your clients turns on WhatsApp
const ws = await call("/v1/wa/channels", "POST", {
  label: client.businessName,
  external_id: client.id,
  profile: { business_name: client.businessName, about: client.about, services: client.services },
});

// 2. start linking and send the client to the hosted page (or draw the QR yourself)
const { connect_url } = await call(`/v1/wa/channels/${ws.id}/connect`, "POST");
redirect(connect_url);

// 3. wait for the webhook "whatsapp.connected", then mark the client as live in your own database

Branding

The connect page shows your name, logo and colour. Set them once for your whole account, and override any of them for a single workspace. The page picks, in this order: the workspace's own value, then your account default, then your account name with a plain colour.

PUT /v1/wa/brand                      (set once for every workspace you have)

{ "name": "YourPlatform", "color": "#0a7f3f", "logo_url": "https://yourplatform.com/logo.png" }

→ { "name": "YourPlatform", "color": "#0a7f3f", "logo_url": "https://yourplatform.com/logo.png" }

POST /v1/wa/brand/logo               multipart/form-data, field "file"  (PNG, JPEG, WebP or SVG, up to 5 MB)

→ { "name": "YourPlatform", "color": "#0a7f3f", "logo_url": "https://api.identifyorg.com/media/partner-logos/9f2c….png" }

PATCH /v1/wa/channels/{id}           { "brand": { "color": "#aa0000" } }    // this workspace only; empty fields fall back to your default
POST  /v1/wa/channels/{id}/brand/logo  multipart, field "file"              // a logo for this workspace only

• name: up to 60 characters. color: #RRGGBB. logo_url: an https address, or use the upload endpoints and we host it for you.
• GET /v1/wa/brand returns your default, and DELETE /v1/wa/brand clears it.
• A square logo looks best. It is shown at about 56 pixels.
• You can also do all of this by clicking in your dashboard, under WhatsApp → Platform → Your branding, with a live preview.

Behaviour

You and your clients control how each assistant behaves with the business information, keyword rules, trained knowledge and the AI switch. You do not manage prompts or models.

PUT /v1/wa/channels/{id}/profile

{
  "business_name": "Ada Stores",        // required
  "about": "…", "services": "…", "pricing": "…", "hours": "…", "location": "…", "contact": "…",
  "website": "https://…", "extra": "anything else the assistant should know",
  "tone": "friendly",                    // friendly | professional | playful, or your own words
  "language": "English",                 // the default language of replies
  "greeting": "Hi! How can I help?",     // used on a customer's first message
  "handoff_message": "A person from the team will reply here shortly.",
  "faqs": [ { "q": "Do you deliver?", "a": "Yes, within Lagos, same day." } ]
}

PUT /v1/wa/channels/{id}/rules

PUT /v1/wa/channels/{id}/rules

{ "rules": [
  { "words": ["hours", "open"], "match": "contains", "action": "reply", "reply": "We are open Monday to Saturday, 9am to 6pm." },
  { "words": ["order"], "match": "starts", "action": "site" }
] }

action is reply (send the fixed text), guide (send the text, then your system handles the next messages), site (hand the message to your system) or ai (let the assistant answer). match is exact, starts or contains. Up to 30 rules.

Teach the assistant more with POST /channels/{id}/knowledge/text, /knowledge/website and /knowledge/file. Turn the AI on or off with PATCH and ai_enabled. To see how it answers before customers do, use POST /channels/{id}/test with { "message": "…" }.

Your own system: orders, bills, bookings

Your platform knows things the assistant cannot, such as a client's orders or a customer's bill. Give each workspace a web address and we send it customer messages as signed requests. Your system answers in the response, or later through POST /channels/{id}/send. Use a rule with action site to choose which messages go there.

PUT /v1/wa/channels/{id}/website

{ "url": "https://yourplatform.com/api/whatsapp/client_8841",
  "fallback_message": "Sorry, we are having trouble right now. A person will reply soon." }

→ { "endpoint_url": "…", "endpoint_secret": "whsec_…", "mode": "ai", ... }

The exact message format, the signature check and the reply format are in the WhatsApp API guide. You can test the whole thing with test/inbound in test mode.

Billing

Choose pay per reply and there is no monthly fee. Every answered customer message is taken from your wallet:

• You are charged for messages that get an automatic answer. Chats that a person has taken over are not charged.
• Test workspaces are never charged.
• Monthly plans are also available. See Plans. Pay per reply suits platforms with many small clients.
• If your wallet runs out, the next 20 replies are still answered, so no customer is dropped mid-chat. Then answers pause until you top up, and you receive whatsapp.balance_low before and whatsapp.balance_empty and whatsapp.paused after.
• Prices are set by us and can change. GET /v1/wa/plans always returns the current ones.

GET /v1/wa/plans

{ "plans": [ … monthly plans … ],
  "pay_per_reply": { "ai_reply": 10.0, "plain_reply": 5.0, "grace_replies": 20 },
  "trial": { "days": 7, "numbers": 1, "messages": 100 } }

POST /v1/wa/subscription      { "tier": "payg" }

{ "tier": "payg", "name": "Pay per reply", "status": "active", "active": true,
  "pay_per_reply": { "ai_reply": 10.0, "plain_reply": 5.0, "grace_replies": 20 },
  "balance": 12500.0 }

You decide what your own clients pay. We bill you; you bill them however you like, using the per-workspace usage below.

Usage

GET /v1/wa/usage?days=30            (optional: &channel_id=…)

{
  "days": 30, "currency": "NGN",
  "summary": { "replies": 1840, "ai_replies": 1500, "plain_replies": 340, "charged": 16700.0 },
  "by_channel": [
    { "channel_id": "5b1f…", "label": "Ada Stores", "external_id": "client_8841",
      "replies": 920, "ai_replies": 800, "plain_replies": 120, "charged": 8600.0 }
  ],
  "by_day": [ { "date": "2026-10-13", "replies": 61, "charged": 560.0 } ]
}

Add &mode=test or &mode=live when using a dashboard login. API keys see their own mode automatically.

Webhook events

Add an address in Webhooks and choose these events. Every event is signed; see Webhooks for how to check the signature. You can also resend any event from the log and send sample events to your address.

POST https://yourplatform.com/webhooks/identifyorg
X-IdentifyOrg-Signature: t=1791650000,v1=9f2b…c41a

{
  "id": "6c7e…",
  "event": "whatsapp.connected",
  "created_at": "2026-10-14T09:15:40Z",
  "data": {
    "channel_id": "5b1f3c1e-…",
    "external_id": "client_8841",
    "label": "Ada Stores",
    "phone": "2348012345678",
    "test": false
  }
}

Go live

1. Switch your account to live under API Keys and create a live key (io_live_sk_…).
2. Choose pay per reply: POST /v1/wa/subscription with { "tier": "payg" }, or press the button in WhatsApp → Platform.
3. Add money to your wallet.
4. Run the same calls you tested, with the live key. Live workspaces are created with the same POST /v1/wa/channels call.
5. Send each client to their connect_url. They scan with the phone that holds the business number.
6. Wait for the whatsapp.connected webhook. They are live.

Errors

Errors look like { "error": { "code": "duplicate_external_id", "message": "…", "status": 409 } }.

Good practice

• One number per business, used to answer customers who message in. Do not use a number for mass or unsolicited messages: WhatsApp can restrict numbers that do.
• Ask your clients to keep the phone connected to the internet and not to remove the linked device. If it happens, you get whatsapp.disconnected and they can scan again from the same connect_url.
• Tell your clients’ customers they are chatting with an automated assistant if they ask, and give them a way to reach a person.
• Keep the information accurate. The assistant only uses what the business has told it.