WhatsApp quickstart

Send your first WhatsApp message in about five minutes — one API key does everything: find your channel, send a text, and receive replies, all with copy-paste curl.

1. Create an API key

In the dashboard, go to Developers → API keys and create a key with the developer role (admin or owner work too — a viewer key can only read). The secret looks like vai_live_xxxxxxxxxxxxxxxx and is shown once — copy it now. Send it in the X-API-Key header on every call below, from your server only.

Check the key and get your organization id — every WhatsApp route below has it in the path:

curl https://api.telenow.ai/api/v1/me \
  -H "X-API-Key: vai_live_…"

{
  "org_id": "7f3c9a12-…",
  "org_name": "Acme Corp",
  "key_id": "c41e…",
  "key_name": "WhatsApp server",
  "key_role": "developer"
}

Use org_id as {orgId} below. What the key can reach, and its limits, are in Authentication & channels.

2. Find your channel

A channel is one of your connected WhatsApp numbers. List them and read the id:

curl https://api.telenow.ai/api/orgs/{orgId}/whatsapp-hub/channels \
  -H "X-API-Key: vai_live_…"

{
  "success": true,
  "data": {
    "channels": [
      { "id": "b1e2c3d4-…", "label": "Acme Support", "phone": "+14155550100" }
    ]
  }
}

Each channel carries more fields than shown here; id is the one you need — it goes in the path of every send. (Empty list? Connect a number first — see the WhatsApp guide.)

3. Send a text

Post the recipient's E.164 number in to and your text in body:

curl -X POST https://api.telenow.ai/api/orgs/{orgId}/whatsapp-hub/channels/{channelId}/send \
  -H "X-API-Key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "body": "Hi Asha! Your order #1234 has shipped and will arrive Thursday."
  }'

{ "success": true, "data": { "wamid": "wamid.HBgLMTQxNTU1MDEwMBUCABIYFj…" } }

That's your first WhatsApp message. The returned wamid is the durable handle on it — you'll match it against delivery events. Free-form text like this only works inside the 24-hour window; outside it, send an approved template on the same channel:

curl -X POST https://api.telenow.ai/api/orgs/{orgId}/whatsapp-hub/channels/{channelId}/send-template \
  -H "X-API-Key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "template": "order_update",
    "language": "en_US",
    "variables": ["Asha", "#1234"]
  }'

It answers with the same { "success": true, "data": { "wamid": … } }. Header media and button parameters go in components — see Template messages.

4. Receive replies

Inbound messages are pushed to your endpoint — you never poll. Subscribe with the same API key. (Events fire for Meta Cloud numbers — set up for you or your own Meta app; for partner and WhatsApp Web numbers, read new messages with GET …/threads.) The /api/v1 response is flat:

curl -X POST https://api.telenow.ai/api/v1/hooks \
  -H "X-API-Key: vai_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["whatsapp.message.received"],
    "target_url": "https://example.com/telenow/whatsapp"
  }'

{
  "id": "hook_3a91f0",
  "target_url": "https://example.com/telenow/whatsapp",
  "events": ["whatsapp.message.received"],
  "signing_secret": "wh_secret_9c1f7b2e4a…",
  "secret": "wh_secret_9c1f7b2e4a…"
}

Save signing_secret now — it's shown once and you need it to verify deliveries. When a customer messages your number, Telenow POSTs a whatsapp.message.received payload to your target_url:

{
  "event": "whatsapp.message.received",
  "channelId": "b1e2c3d4-…",
  "from": "+919876543210",
  "wamid": "wamid.HBgLMTIxNTU1NTk4NzYVAgASGBQzQTdBQ0I…",
  "type": "text",
  "body": "Where is my order #1234?"
}
  • from — the customer's number, E.164. Reply by passing it as to on /send (step 3).
  • wamid — Meta's message id; quote it with reply_to on /send (Meta Cloud numbers), or match it in whatsapp.message.status events.
  • type — text, image, interactive, and so on; richer types decode into a content object.
  • body — the text (empty for non-text types).

Verify the X-VoiceAI-Signature header before trusting a delivery — see Webhooks & events.

Building an app that other orgs install?

Use an app key (vai_app_…) on the /api/app-whatsapp routes instead. It's issued per install and carries only the scopes each org approved. See Authentication & channels.

Next steps