WhatsApp

Customers who live in WhatsApp can call you there too. They open your business chat, tap the call button, and your assistant picks up: same assistant, same number, no app switch for them.

Overview#

WhatsApp calling adds a second way to reach the assistant on a phone number you already have with OnCore. Once the number is enabled for WhatsApp, customers can call you from inside the WhatsApp app (no dialling, just a tap in the chat) and the same assistant that answers your phone line takes the call. The number keeps answering ordinary phone calls exactly as before; WhatsApp calling sits alongside, and the call travels over the internet rather than the phone network.

• Meet customers where they already are: for many customers WhatsApp is the phone; the call button in your chat now reaches a live assistant instead of ringing out.
• Serve callers abroad without international dialling: a customer in another country taps to call over the internet instead of dialling a foreign number.
• Keep one assistant across phone and WhatsApp: both routes land on the assistant behind the same number, so its behaviour, greeting, and tasks stay in one place.
• Enable numbers at scale through the API: start an onboarding with a single request, hand the business owner a signup link, and follow progress by webhook until calling is live; the owner never handles codes or verification screens.
• Tell WhatsApp calls apart in your reporting: each call is announced to your systems with a whatsapp source marker, alongside the same call records you get for phone calls.

WhatsApp onboarding lets a reseller enable WhatsApp calling on one of a tenant's phone numbers. You start a session, send the end customer to a single-use signup URL where they authenticate with Meta and share their WhatsApp Business Account (WABA), and everything after that (attaching the number, capturing the registration code, enabling calling) happens on OnCore's side. The customer never sees a phone-number or OTP screen.

Once the number is onboarded, inbound WhatsApp text is a separate channel flag on the assistant. Calling and texting share the same WABA number; they do not share the same on/off switch.

In the dashboard: Sign up to WhatsApp on the assistant, then turn WhatsApp Enabled on under Messaging and save.

Authenticate with your tenant API key, or an organization key plus X-Tenant-Id. See Authentication.

Enable or disable the WhatsApp text channel#

Toggle two-way WhatsApp text per assistant. OnCore only answers customer-initiated text. It does not send templates, start a conversation, or handle media.

A WhatsApp text conversation behaves like an SMS conversation: the same opening line, the same ways for a thread to end, and the same handling of a text sent right after a goodbye.

curl -X PATCH https://core-api.heysadie.ai/assistants/ASSISTANT_ID/whatsapp-enabled \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "whatsappEnabled": true }'

The response returns the assistant id and its updated featureFlags. When WhatsApp is disabled, OnCore ignores inbound WhatsApp text for the assistant's number(s). Other channel flags (SMS, for example) are left alone.

Start a session#

POST /whatsapp/onboarding-sessions requires an Idempotency-Key header:

curl -X POST https://core-api.heysadie.ai/whatsapp/onboarding-sessions \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Idempotency-Key: 8c8f3f1e-YOUR-UNIQUE-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "TENANT_ID",
    "phoneNumber": "+15555550123",
    "displayName": "Acme Support"
  }'

The response contains a sessionId, a single-use, tenant-bound, 15-minute signupUrl (a OnCore-hosted page wrapping Meta's Embedded Signup) with its expiresAt, and a single-use signup token (also embedded in signupUrl) for resellers hosting their own signup page. Send the end customer to signupUrl.

The Meta consent popup shows the platform provider's registered name, not your customer's business name. Meta does not white-label Tech Providers.

The state machine#

Track progress by polling GET /whatsapp/onboarding-sessions/{id} or by subscribing to the WhatsApp webhook events.

pending → authorized → verifying → [tier_pending] → completed → live

with terminal states failed, name_rejected, and abandoned.

On failure states the status response also carries failureReason, blame (customer = the account owner must act, resolve with your customer; system = OnCore/Meta-side, hand to OnCore), and userMessage, human-readable copy safe to show the end customer. When failureReason is otp_request_limit, retryAfterHours gives Meta's lockout window.

A stranded session self-heals to failed past its TTL: failureReason: "stalled" if it crashed in authorized (no verification call placed), or "otp_call_timeout" if it was stuck in verifying. While verifying, if the verification call was placed more than ~5 minutes ago the response carries verificationCallOverdue: true, a soft signal to prompt the customer to resend or cancel.

Resend the verification call#

POST /whatsapp/onboarding-sessions/{id}/resend-code re-triggers Meta's automated voice call that reads the registration code, for a session in verifying. The session stays verifying; otpAttempts in the response reflects the per-session budget consumed so far.

Cancel / reset#

DELETE /whatsapp/onboarding-sessions/{id} is the self-service recovery path:

• pending / authorized / verifying are cancellable: the number's WhatsApp link is cleared and the session becomes abandoned (a subsequent GET reports failureReason: "cancelled"). The number can immediately be re-onboarded.
• failed / abandoned / name_rejected are already terminal: idempotent no-op, returns the current status (200).
• tier_pending / completed / live are not cancellable: a verified/registered or live number returns 409 WHATSAPP_ONBOARDING_NOT_CANCELLABLE.

Cancelling makes no Meta call (a re-onboard idempotently re-attaches the number) and fires no webhook, since you initiated it. Cross-tenant / unknown ids return 404.

Failure reason codes#

On terminal failure, failureReason (and data.reason on the whatsapp.onboarding.failed webhook) is one of:

Webhook events#

Onboarding progress is also pushed to your server as signed webhooks: whatsapp.onboarding.tier_pending, whatsapp.onboarding.completed, whatsapp.onboarding.failed, and whatsapp.calling.live. See WhatsApp events for the payload, signature verification, and retry semantics, and the API reference for the full endpoint specification.

Limits & FAQ#

• The signup link is single-use and valid for 15 minutes; if it expires or the owner abandons it, you simply start again. Nothing is left in a broken state.
• The number must already be answering ordinary voice calls: enablement is confirmed by an automated verification call to the line, so a number with no inbound voice routing can't complete onboarding.
• A brand-new WhatsApp Business Account can sit below Meta's calling tier; the number is parked as tier_pending and calling switches on once the account's limit rises. You're notified by webhook when it completes.
• WhatsApp calls can't be transferred to your team. Keep lines whose flows depend on call transfers on the regular phone channel.
• WhatsApp calling and WhatsApp text are separate. Calling goes live through onboarding. Texting stays off until you set whatsappEnabled on the assistant. Stickers and images are ignored; only customer-initiated text is answered.

Is it the same assistant as our phone line? Yes. WhatsApp calls to the number reach the assistant assigned to that number, and regular phone calls continue to work unchanged.

What does the caller see in WhatsApp? Your business display name. You request it during onboarding and Meta reviews it. Once approved, calling is live end-to-end under that name.

What does the business owner have to do? Only the Meta approval: they open the signup link, sign in, and consent. They never see a phone-number or verification-code screen. Note the Meta consent screen shows the platform provider's registered name. Meta does not white-label technology providers.

How do these calls show up in our reporting? Like phone calls: the start-of-call event carries call_source: "whatsapp" (see the assistant-request webhook), and each call delivers an end-of-call report and appears in your call history with its transcript and summary.

Do inbound WhatsApp texts get a reply? Yes, once the number is onboarded and whatsappEnabled is true on the assistant. Threads show up as conversations with channel: whatsapp. OnCore does not start the chat or send templates.

Next steps#

• WhatsApp events: signed webhooks for the onboarding lifecycle.
• Conversations: WhatsApp threads in your history.
• WhatsApp API: the full endpoint specification.