---
title: "Connect phone number"
method: POST
path: "/customers/{customer_id}/whatsapp/phone_numbers"
tags: ["Phone Numbers"]
---

# Connect phone number

`POST /customers/{customer_id}/whatsapp/phone_numbers`

## Request

- Base URL: `https://api.kapso.ai/platform/v1`
- URL: `https://api.kapso.ai/platform/v1/customers/{customer_id}/whatsapp/phone_numbers`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/kapso/apis/kapso-platform-api/docs/customers/:customer_id/whatsapp/phone_numbers/post.ts> (a function with typed inputs; its response is checked against the schema)

Connect a WhatsApp number to this customer using Meta credentials.

Get credentials from Meta's App Dashboard after completing embedded signup or manual setup.

## Request body

- WhatsappPhoneNumberCreateRequest
  - `whatsapp_phone_number` object, required
    - `name` string, required
    - `kind` 'production' | 'sandbox': Production uses Meta credentials, sandbox uses test data
    - `phone_number_id` string, required: From Meta
    - `business_account_id` string, required: From Meta
    - `access_token` string, required: Permanent token from Meta
    - `webhook_verify_token` string, nullable
    - `webhook_destination_url` string, uri, nullable: Your HTTPS endpoint for webhooks
    - `inbound_processing_enabled` boolean
    - `calls_enabled` boolean

## Response `201`

Phone number connected

- WhatsappPhoneNumberResponse
  - `data` WhatsappPhoneNumber, required
    - `id` string, required: Meta phone number ID
    - `internal_id` string, uuid, required: Kapso configuration ID
    - `phone_number_id` string, required: Meta phone number ID
    - `name` string, required: Label for this number
    - `business_account_id` string, nullable: WhatsApp Business Account ID
    - `is_coexistence` boolean, nullable: Using with WhatsApp Business App
    - `inbound_processing_enabled` boolean: Process incoming messages
    - `calls_enabled` boolean: Handle voice calls
    - `webhook_verified_at` string, date-time, nullable: When Meta confirmed webhook
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `customer_id` string, uuid, nullable
    - `display_name` string, nullable: Customer-facing display name
    - `display_phone_number` string, nullable: Formatted number from Meta
    - `display_phone_number_normalized` string, nullable: Digits only
    - `verified_name` string, nullable: Meta-verified business name
    - `quality_rating` string, nullable: GREEN, YELLOW, or RED
    - `code_verification_status` string, nullable
    - `name_status` string, nullable: Display name review status
    - `status` string, nullable: Connection status (e.g., CONNECTED)
    - `throughput_tier` string, nullable: Message rate limit tier
    - `whatsapp_business_manager_messaging_limit` union
      - integer
      - string
    - `is_official_business_account` boolean, nullable: Green checkmark verified
    - `is_pin_enabled` boolean, nullable: Two-factor PIN enabled

## Other responses

- `401`: Missing or invalid API key
- `404`: Resource not found
- `409`: Phone limit reached or duplicate
- `422`: Request validation failed

---

[API](https://skmtc.dev/kapso/apis/kapso-platform-api.md) - [All operations](https://skmtc.dev/kapso/apis/kapso-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kapso/apis/kapso-platform-api/revisions/18ff5548a33f?raw)