---
title: "Create or verify a WhatsApp sender, or turn WhatsApp calls on/off, for a workspace (sms:write + admin)."
method: POST
path: "/v1/whatsapp-sender"
---

# Create or verify a WhatsApp sender, or turn WhatsApp calls on/off, for a workspace (sms:write + admin).

`POST /v1/whatsapp-sender`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/whatsapp-sender`
- Auth: HTTP bearer

`action=connect` returns the one signup link the business owner opens to put WhatsApp on one of its own KaiCalls lines (optional `phone_number`); the owner signs in to Facebook as the business and verifies the number, and the link is reused while valid. `action=sync` reads the carrier back; a number is connected only when the carrier lists it verified for WhatsApp. The GET response carries these as `telnyx.connections`. Otherwise uses a customer-owned Twilio account or KaiCalls-managed subaccount. `action=create` registers the Meta Embedded Signup WABA and assigned phone through Twilio v2; `action=verify` submits a six-digit OTP. Both actions require a durable idempotency key. Mutation responses are acknowledgements only; connected requires a following exact GET read-back of the tenant-bound sender as ONLINE. `action=voice` with `enabled` attaches (or detaches) the voice application that lets the agent answer calls placed from WhatsApp; it requires a connected sender and a Meta-verified business at the 2,000-conversation messaging tier, and is unavailable until the deployment enables WhatsApp calls.

## Request body

- object
  - `business_id` string, required
  - `action` 'connect' | 'sync' | 'create' | 'verify' | 'voice', required
  - `enabled` boolean: For action=voice: true to let the agent answer WhatsApp calls
  - `phone_number` string: E.164 number for create
  - `waba_id` string: WABA returned by Embedded Signup
  - `profile_name` string
  - `verification_method` 'sms' | 'voice'
  - `idempotency_key` string: Required for create and verify; reuse only for the same request
  - `sender_sid` string: Twilio XE SID for verify
  - `code` string: Six-digit OTP for verify

## Response `200`

Provider-backed sender lifecycle state

## Other responses

- `403`: Missing sms:write scope, or no access to this business
- `409`: Business Twilio account or idempotency state requires action
- `429`: Verification attempt rate limit reached

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)