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. There are three message kinds, and which you can send depends on the 24-hour window:

text and media 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.

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).

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.

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

Receive messages

Templates

Business profile

Phone numbers

Limits & restrictions

​Connect a number

​Send a message

​Receive messages

​Templates

​Business profile

​Phone numbers

​Limits & restrictions

Connect a number

Send a message

Receive messages

Templates

Business profile

Phone numbers

Limits & restrictions