Connect WhatsApp to a number | Dial — Communication Stack for AI Agents

{
  "number": {
    "id": "string",
    "number": "+14155550123",
    "nickname": "Support line",
    "firstName": "Maya",
    "lastName": "Chen",
    "avatarUrl": "https://getdial.ai/public-media/9f2c47a1b8d3e6f0a1b2c3d4.png",
    "whatsappName": "Maya from ACME",
    "whatsappAvatarUrl": "https://getdial.ai/public-media/7a1b2c3d4e5f60718293a4b5.png",
    "country": "US",
    "capabilities": [
      "sms",
      "call"
    ],
    "callingEnabled": true,
    "forwardTo": null,
    "setupStatus": "ready",
    "setupError": "string",
    "inboundInstruction": "You are Dial's receptionist. Greet the caller and find out what they need.",
    "inboundVoiceGender": "female",
    "inboundLanguage": "es-ES",
    "accountId": "string",
    "createdAt": "2024-01-15T09:30:00Z",
    "replaces": [
      {
        "id": "string",
        "number": "+14155550123",
        "replacedAt": "2024-01-15T09:30:00Z"
      }
    ],
    "replacedBy": {
      "id": "string",
      "number": "+14155550199"
    },
    "replacedAt": "2024-01-15T09:30:00Z",
    "maxCallDurationSeconds": 1,
    "whatsapp": {
      "status": "ready",
      "error": null,
      "retryAvailableAt": null,
      "autoRetryScheduled": false
    },
    "tenDlc": {
      "status": "in_review",
      "kind": "business",
      "submittedAt": "2024-01-15T09:30:00Z",
      "reviewedAt": "2024-01-15T09:30:00Z",
      "reason": "The message flow describes a checkout page rather than the SMS consent step. Say where the consent wording and the checkbox appear, and that the box starts unchecked."
    }
  }
}

Connects WhatsApp to an iMessage number you already hold. Unlike whatsapp: true on Provision a phone number, which hands you a number whose WhatsApp is already set up and warmed, this registers WhatsApp on your own number and then warms it before it can send.

WhatsApp is in beta and enabled per account. Without access this endpoint answers 404, not 403: to such an account the capability does not exist, which is also what the dashboard shows. Contact support to request access.

Asynchronous. The response carries the number as List phone numbers reports it, with whatsapp.status at provisioning. It then moves to warming_up once registered — the number warms up before its first use, which takes about 6 hours — and to ready after that; each move is announced by number.status_changed. Wait for ready before sending on the channel. On an iMessage number, call settles in the same event that moves WhatsApp to warming_up. Progress and failure are independent of the number’s own setupStatus — see WhatsApp lines.

Authentication

AuthorizationBearer

Your Dial API key, sent as Authorization: Bearer sk_live_...

Path parameters

idstringRequired

The phone number's ID.

Response

WhatsApp setup started. The number, with its whatsapp track attached.

numberobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

503

Service Unavailable Error