WhatsApp

SmartlyQ connects to the WhatsApp Business Cloud API (Meta), so you can send session and template messages, receive inbound messages and delivery receipts via webhooks, and manage templates and the business profile.

Connect a number

There are two ways to connect a WhatsApp number. In the app (recommended). In Settings → WhatsApp, click Connect with WhatsApp and complete Meta’s Embedded Signup popup - sign in, pick your WhatsApp Business Account and phone number, and you’re done. SmartlyQ exchanges the returned code for a system-user token, subscribes to the number’s webhooks, and stores the connection. No tokens to copy. Over the API (headless). For server-to-server onboarding, supply your WhatsApp Business Account id, the phone number id, and a Meta system-user access token:

curl -X POST https://api.smartlyq.com/v1/social/connect/whatsapp \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "waba_id": "1234567890", "phone_number_id": "9876543210", "access_token": "EAAG..." }'

Either way, the token is verified against the number and stored encrypted; the connected number appears in GET /v1/social/accounts (platform whatsapp). Its id is the account_id you pass to every WhatsApp call below.

Send a message

POST /v1/whatsapp/messages. Eight message kinds, and which you can send depends on the 24-hour window:

text, media, interactive_buttons, interactive_list, location, and contacts are session messages - deliverable only within 24 hours of the customer’s last message to you.
template (an approved HSM) is the only kind deliverable outside that window.
reaction reacts to (or removes a reaction from) a message you already sent or received.

Text (session)

{ "account_id": 42, "to": "+14155551234", "type": "text", "text": "Thanks for reaching out!" }

Template (any time)

{
  "account_id": 42, "to": "+14155551234", "type": "template",
  "template": { "name": "order_update", "language": "en_US",
    "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "#A1234" }] }] }
}

Media (session)

{ "account_id": 42, "to": "+14155551234", "type": "media",
  "media": { "kind": "image", "link": "https://cdn.example.com/receipt.png", "caption": "Your receipt" } }

A 502 means WhatsApp rejected it - most commonly sending a session message outside the 24-hour window (send a template instead). For media.kind: "audio", SmartlyQ automatically transcodes the file to WhatsApp’s voice-note format (OGG/Opus) when it isn’t already one of ogg/oga/aac/m4a/mp3/amr - so a browser-recorded clip still renders as a playable voice note, not a generic file attachment. This happens transparently; no extra parameter needed.

Interactive buttons and lists

Buttons and lists let the customer respond by tapping instead of typing - their tap arrives as a normal inbound message on your webhook (message.received), same as any reply.

Interactive buttons (up to 3)

{
  "account_id": 42, "to": "+14155551234", "type": "interactive_buttons",
  "text": "Your order #A1234 is ready. What would you like to do?",
  "buttons": [
    { "id": "confirm", "title": "Confirm" },
    { "id": "reschedule", "title": "Reschedule" },
    { "id": "cancel", "title": "Cancel" }
  ]
}

Interactive list (up to 10 rows)

{
  "account_id": 42, "to": "+14155551234", "type": "interactive_list",
  "text": "Pick a time slot for your appointment.", "button_text": "View slots",
  "sections": [
    { "title": "Tomorrow", "rows": [
      { "id": "slot_10", "title": "10:00 AM", "description": "45 min available" },
      { "id": "slot_14", "title": "2:00 PM", "description": "45 min available" }
    ] }
  ]
}

Button titles are capped at 20 characters, list row titles at 24, and row descriptions at 72 - Meta’s own limits, enforced server-side.

Location and contact cards

Location pin

{
  "account_id": 42, "to": "+14155551234", "type": "location",
  "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "Store pickup counter", "address": "123 Market St, San Francisco, CA" }
}

Contact card

{
  "account_id": 42, "to": "+14155551234", "type": "contacts",
  "contacts": [{ "name": { "formatted_name": "Support Team", "first_name": "Support" }, "phones": [{ "phone": "+14155550188", "type": "WORK" }] }]
}

contacts takes WhatsApp’s raw contact-card object shape directly (name, phones, emails, etc. - see Meta’s WhatsApp Cloud API reference for every optional field).

Reply threading and reactions

Pass context_message_id (a prior WhatsApp message id, wamid...) on any send to thread it as a reply - it renders as a quoted message in the customer’s app. You get wamid values back from every send response’s message_id, and on every inbound message via the message.received webhook.

Threaded reply

{
  "account_id": 42, "to": "+14155551234", "type": "text",
  "text": "Yes, that ships tomorrow.",
  "context_message_id": "wamid.HBgLMTU1NTU1NTU1NTUVAgARGBI5QTM2RUQ4RkQ2QjM4RjQ4QjQA"
}

React to a message

{
  "account_id": 42, "to": "+14155551234", "type": "reaction",
  "context_message_id": "wamid.HBgLMTU1NTU1NTU1NTUVAgARGBI5QTM2RUQ4RkQ2QjM4RjQ4QjQA",
  "emoji": "👍"
}

Send emoji: "" to remove a reaction you previously sent. A customer’s reaction to your message arrives via the reaction.received webhook, not message.received.

Receive messages

Inbound messages and delivery receipts arrive on your webhooks, not by polling (the Cloud API has no message-history endpoint). Subscribe to:

Event	Fires when
`message.received`	A customer sends you a message (lands in your inbox too)
`message.delivered`	Your outbound message reached the recipient
`message.read`	The recipient opened your message
`message.failed`	Your outbound message failed, with the platform error

See the Webhooks guide. Inbound messages also populate the in-app Inbox automatically.

Templates

GET /v1/whatsapp/templates?account_id=42 - list templates and their approval status.
POST /v1/whatsapp/templates - submit a new template (name, category = MARKETING/UTILITY/AUTHENTICATION, language, components) for Meta approval.

Business profile

GET /v1/whatsapp/business-profile?account_id=42 - read about/address/email/websites/vertical.
PATCH /v1/whatsapp/business-profile - update any of those fields.

Phone numbers

GET /v1/whatsapp/phone-numbers?account_id=42 lists the numbers on the connection’s WhatsApp Business Account with their display number, verified name, and quality rating.

Flows

Flows are native in-chat forms - booking, surveys, lead capture - that open inside WhatsApp instead of linking out. A flow goes DRAFT → screens uploaded → PUBLISHED → sendable.

Create a draft flow

POST /v1/whatsapp/flows
{ "account_id": 42, "name": "Book an appointment", "categories": ["APPOINTMENT_BOOKING"] }

Upload its screens

PUT /v1/whatsapp/flows/{flow_id}/json
{ "account_id": 42, "flow_json": { "version": "6.0", "screens": [ /* ... */ ] } }

Check the response’s validation_errors - a successful upload doesn’t guarantee the flow is publishable. Preview a draft with GET /v1/whatsapp/flows/{flow_id}/preview (embeddable iframe URL) before publishing. Once POST /v1/whatsapp/flows/{flow_id}/publish succeeds, send it:

Send the flow

POST /v1/whatsapp/messages
{
  "account_id": 42, "to": "+14155551234", "type": "flow",
  "text": "Book your appointment in a few taps.",
  "flow": {
    "id": "1234567890123456",
    "cta": "Book now",
    "action": "navigate",
    "action_payload": { "screen": "APPOINTMENT", "data": {} }
  }
}

Published flows are immutable - to change one, create a new flow and update your senders to reference the new id. See the full endpoint list on the API reference.

Block users

GET / POST / DELETE /v1/whatsapp/block-users blocks or unblocks WhatsApp users on a connected number and lists who’s currently blocked. Meta only allows blocking someone who has messaged your business within the last 24 hours; other targets come back in the response’s failed array without failing the rest of the batch.

Block a user

POST /v1/whatsapp/block-users
{ "account_id": 42, "users": ["+14155551234"] }

Sandbox (shared test number)

Every developer can test against one SmartlyQ-owned WhatsApp number without connecting their own. Activate a phone, reply to prove you own it, then send the locked sandbox template as many times as you like (up to the daily cap) to see it actually land.

Start an activation

POST /v1/whatsapp/sandbox/sessions
{ "phone": "+14155551234" }

Reply to the WhatsApp message that arrives at that phone (any text works) - the reply itself activates the session. Then:

Fire the template again once active

POST /v1/whatsapp/sandbox/sessions/{session_id}/send

One phone per user at a time; revoke (DELETE /v1/whatsapp/sandbox/sessions/{session_id}) before activating a different one. Limits: 50 sends/24h, pending sessions expire after 24h, active sessions after 7 days. 503 SANDBOX_UNAVAILABLE means the platform hasn’t configured a sandbox number yet - it’s opt-in infrastructure, not guaranteed to exist on every deployment.

Bring your own number (Twilio bridge)

If you’ve bought a phone number through SmartlyQ (POST /v1/phone-numbers/purchase), you can bridge it onto WhatsApp instead of connecting a separate number. This adds the number to your existing WhatsApp Business Account connection - connect one number first via Settings > WhatsApp, then bridge any additional purchased numbers onto that same account.

1. Start the bridge

POST /v1/whatsapp/numbers/{sender_id}/bridge

2. Request a verification code

POST /v1/whatsapp/numbers/{sender_id}/bridge/request-code
{ "method": "sms" }

Meta sends the code to the number itself (SMS or a voice call) - check that number’s inbound message log in SmartlyQ to read it, the same way you’d check any other number you own.

3. Submit the code

POST /v1/whatsapp/numbers/{sender_id}/bridge/verify
{ "code": "123456" }

On success the number is registered with WhatsApp and connected in SmartlyQ - from then on it behaves exactly like any other connected WhatsApp number, including in POST /whatsapp/messages. Requires the number to have SMS or voice capability so Meta can actually deliver the code.

Limits & restrictions

WhatsApp messaging is governed by both Meta’s platform rules and your SmartlyQ plan. Knowing these avoids surprises: Meta (platform) rules — enforced by WhatsApp:

24-hour customer service window — free-form text and media messages are only deliverable within 24 hours of the customer’s last message to you. Outside it, you must use an approved template. A 502 on a session message almost always means the window has closed.
Messaging tiers — a new number can start ~250 unique customers per 24 hours, rising to 1K → 10K → 100K → unlimited as your volume and quality grow. Meta raises the tier automatically.
Quality rating — each number carries a green / yellow / red rating. Too many blocks or reports lowers it and can throttle or restrict the number, so keep messaging relevant and opt-in.
Template categories — templates are MARKETING, UTILITY, or AUTHENTICATION, and each must be approved by Meta before it can be sent. Marketing templates are subject to per-user frequency caps.
Throughput — Meta accepts roughly 80 messages/second per number by default. SmartlyQ paces sends under this automatically so a burst can’t trip the throttle.

SmartlyQ (plan) limits:

Monthly message cap — each plan includes a monthly WhatsApp send allowance. When it’s reached, POST /whatsapp/messages returns 429 LIMIT_REACHED until the next month or a plan upgrade. This is separate from Meta’s tiers.
Connected numbers count toward your plan’s connected-account limit, like any other channel.

SDKs & CLI

Guides

Connect a number

Send a message

Interactive buttons and lists

Location and contact cards

Reply threading and reactions

Receive messages

Templates

Business profile

Phone numbers

Flows

Block users

Sandbox (shared test number)

Bring your own number (Twilio bridge)

Limits & restrictions

​Connect a number

​Send a message

​Interactive buttons and lists

​Location and contact cards

​Reply threading and reactions

​Receive messages

​Templates

​Business profile

​Phone numbers

​Flows

​Block users

​Sandbox (shared test number)

​Bring your own number (Twilio bridge)

​Limits & restrictions

Connect a number

Send a message

Interactive buttons and lists

Location and contact cards

Reply threading and reactions

Receive messages

Templates

Business profile

Phone numbers

Flows

Block users

Sandbox (shared test number)

Bring your own number (Twilio bridge)

Limits & restrictions