Quickstart

WhatsApp quickstart

Send your first WhatsApp message in about five minutes — create a key, find your channel, send a text, and wire up replies, all with copy-paste curl.

1. Create an app key

In the dashboard, install or open your app and create a key (owner/admin only) with the whatsapp scope. The secret looks like vai_app_xxxxxxxxxxxxxxxx and is shown once — copy it now. Send it as a bearer token on every call below, from your server only.

Full detail — key roles, scopes, and the header formats — is 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/app-whatsapp/channels \
  -H "Authorization: Bearer vai_app_…"

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

Grab data.channels[].id — that's your channelId for every send. (Empty list? Connect a number first, per Authentication & channels.)

3. Send a text

Post to /send with the channelId, the recipient's E.164 number in to, and your text in message:

curl -X POST https://api.telenow.ai/api/app-whatsapp/send \
  -H "Authorization: Bearer vai_app_…" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "b1e2c3d4-…",
    "to": "+919876543210",
    "message": "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 a template.

4. Receive replies

Inbound messages are pushed to your endpoint — you never poll. Subscribe with an org API key (vai_live_…) — a different credential from the app key in step 1. Create one in the dashboard under Developers → API keys (the key needs the owner, admin, or developer role), and send it in the X-API-Key header. 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, 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.

Next steps