WhatsApp onboarding walkthrough

This page walks one conversation from first touch to last turn. The getting-started guide explains the platform rules; this walkthrough shows the actual requests, responses, and webhook events as a conversation flows, so you know exactly what your integration receives at each turn. The conversation: a customer named Ada opts in at checkout, receives an order-confirmation template, replies with a question, and gets a free-form answer inside the 24-hour window.

Before you begin

A live Orbit API key (Settings → API Keys, prefix dv_live_sk_). Keep it server-side.
A connected WhatsApp Business Account (WABA). The full connect path — Meta Business Manager, number verification, messaging tiers — is the WABA setup guide.
A webhook endpoint subscribed to the message events below. See webhook security for signature verification.

Step 1 — Connect the WABA

In the dashboard: Settings → Channels → WhatsApp → Connect. Meta’s embedded sign-up picks your Business Manager, creates or selects the WABA, and verifies your number. The channel shows Connected as soon as the number verifies — Meta’s business verification can still be running in the background. Until business verification completes, the WABA is capped at 250 unique recipients per 24 hours. One onboarding-scale conversation costs nothing against that budget.

Step 2 — Create and submit the template

Business-initiated messages must use an approved template. Channels → WhatsApp → Templates → New Template:

Field	Value used in this walkthrough
Category	`utility`
Language	`en` (English)
Name	`order_confirmation`
Body	`Hi {{1}}, your order {{2}} confirmed — we're packing it now. Track it here: {{3}}`

Approval is usually minutes; allow up to 24 hours. You can watch it from your own systems instead of polling — subscribe to the template events:

// webhook: whatsapp.template.approved
{
  "id": "evt_tpl_9f2c1",
  "type": "whatsapp.template.approved",
  "created_at": "2026-10-08T14:02:11Z",
  "data": {
    "template_name": "order_confirmation",
    "language": "en",
    "category": "utility"
  }
}

A rejection arrives as whatsapp.template.rejected with a rejection_reason field — the most common cause is a category mismatch (promotional copy filed as utility). See the content policy.

Step 3 — Send the first template message

Once approved, send:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/whatsapp \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "en" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Ada" },
            { "type": "text", "text": "ORD-12345" },
            { "type": "text", "text": "https://shop.example.com/track/ORD-12345" }
          ]
        }
      ]
    }
  }'

{
  "data": {
    "id": "msg_8d41f2",
    "channel": "whatsapp",
    "to": "+14155552671",
    "status": "queued"
  }
}

Persist the id — it is the key in every webhook event that follows this message.

Step 4 — Watch the delivery progression kill your polling loop

Each message posts its lifecycle to your endpoint as it moves:

{ "type": "message.sent",      "data": { "message_id": "msg_8d41f2", "to": "+14155552671", "status": "sent" } }
{ "type": "message.delivered", "data": { "message_id": "msg_8d41f2", "to": "+14155552671", "status": "delivered" } }
{ "type": "message.read",      "data": { "message_id": "msg_8d41f2", "to": "+14155552671", "status": "read" } }

sent is Meta accepting the message; delivered is the device’s receipt; read is the customer opening the chat. An undeliverable number produces message.failed with an error.code you can route on (for example 131030 recipient-not-allowed — the number is not opted in to your WABA).

Step 5 — Receive the customer’s reply

When Ada replies, you receive the inbound message as message.received:

{
  "id": "evt_in_53kdp",
  "type": "message.received",
  "created_at": "2026-10-08T14:11:47Z",
  "data": {
    "message_id": "msg_2c7a09",
    "from": "+14155552671",
    "channel": "whatsapp",
    "type": "text",
    "text": "Can I change the delivery address before it ships?"
  }
}

Her reply opens the 24-hour service window: from this moment you can send free-form messages without a template until the window closes. See the 24-hour window for the full state model.

Step 6 — Answer inside the window

Free-form sends look like template sends but drop the template object:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/whatsapp \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "type": "text",
    "text": { "body": "Yes — reply with the new address and we will update the shipment before it leaves the warehouse." }
  }'

Zero-cost per-message round trip: this is a service conversation, priced differently from template sends.

Step 7 — Check window status before composing free-form from a job

Batch jobs and campaign senders cannot assume a window is open. Pre-flight the check:

curl "https://api.orbit.devotel.io/api/v1/messages/whatsapp/window-status?to=%2B14155552671&from=%2B18005551234" \
  -H "X-API-Key: dv_live_sk_..."

{ "data": { "window_open": false, "seconds_remaining": 0 } }

If you skip the check and send free-form outside the window, the send is rejected with a 422 — it is not silently dropped. For a closed window, send a re-engagement template instead; when the customer replies to it, a new window opens.

Verify the wiring end to end

Run this checklist on a live WABA before you roll the integration to real customers:

Template send returns 200 with a msg_ id
message.sent then message.delivered arrive on your webhook, same message_id
Replying from a handset produces message.received within a second
A free-form send during the open window returns 200
The window-status endpoint flips to window_open: false after 24 hours of silence
Webhook signature verification passes on every event (how)

Frequently asked questions

Do I need a real Meta Business Manager to test this?

Yes — but your own phone number on a verified WABA works as the test customer. The 250-recipient starter cap is far more than an onboarding test needs. There is no separate Meta sandbox on Orbit; test against the live platform with a small loop of numbers you control.

A free-form send returned 422 — what did I miss?

Two common causes: the 24-hour window has closed (check with window-status), or the number has never messaged the WABA and no template is being used. Both resolve the same way — send an approved template, then continue free-form once the customer replies.

Why did `message.read` never arrive?

Read receipts are the customer’s choice — WhatsApp lets users disable them. Your integration must treat message.delivered as the success terminal state and read as informational.

How do I run a second conversation lane while testing?

Multiple WABAs on one Orbit account are supported. Connect the second through Settings → Channels → WhatsApp → Connect and pick a different WABA in embedded sign-up. Each WABA routes events to the same workspace webhooks, distinguished by the from number in each event.

Next steps

The 24-hour window — full state model, re-engagement rules, and edge cases.
Create and approve templates — variables, buttons, and media headers.
WhatsApp channel reference — every request field, including media and interactive messages.
API migration parity map — moving an existing Meta Cloud API integration onto Orbit’s shape.
Campaign launch playbook — when one walkthrough becomes a production send lane.

WhatsApp

Developer console

Guides

Messaging Controls

Audience & Support Tools

WhatsApp onboarding walkthrough

WhatsApp onboarding walkthrough

Before you begin

Step 1 — Connect the WABA

Step 2 — Create and submit the template

Step 3 — Send the first template message

Step 4 — Watch the delivery progression kill your polling loop

Step 5 — Receive the customer’s reply

Step 6 — Answer inside the window

Step 7 — Check window status before composing free-form from a job

Verify the wiring end to end

Frequently asked questions

Do I need a real Meta Business Manager to test this?

A free-form send returned 422 — what did I miss?

Why did `message.read` never arrive?

How do I run a second conversation lane while testing?

Next steps

​WhatsApp onboarding walkthrough

​Before you begin

​Step 1 — Connect the WABA

​Step 2 — Create and submit the template

​Step 3 — Send the first template message

​Step 4 — Watch the delivery progression kill your polling loop

​Step 5 — Receive the customer’s reply

​Step 6 — Answer inside the window

​Step 7 — Check window status before composing free-form from a job

​Verify the wiring end to end

​Frequently asked questions

​Do I need a real Meta Business Manager to test this?

​A free-form send returned 422 — what did I miss?

​Why did message.read never arrive?

​How do I run a second conversation lane while testing?

​Next steps

WhatsApp onboarding walkthrough

Before you begin

Step 1 — Connect the WABA

Step 2 — Create and submit the template

Step 3 — Send the first template message

Step 4 — Watch the delivery progression kill your polling loop

Step 5 — Receive the customer’s reply

Step 6 — Answer inside the window

Step 7 — Check window status before composing free-form from a job

Verify the wiring end to end

Frequently asked questions

Do I need a real Meta Business Manager to test this?

A free-form send returned 422 — what did I miss?

Why did `message.read` never arrive?

How do I run a second conversation lane while testing?

Next steps