> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Business Calling

> Enable voice calling over WhatsApp on your Telnyx numbers — inbound and outbound calls route through your existing Voice API, SIP, or TeXML connection.

WhatsApp Business Calling lets you receive and place voice calls over WhatsApp using your existing Telnyx phone numbers. Calls route through your configured Voice API, SIP, or TeXML connection — the same infrastructure you already use for programmable voice.

With over 2 billion WhatsApp users worldwide, business calling gives your customers a familiar way to reach you by voice without leaving the app.

## How it works

* **Inbound calls** — When a WhatsApp user calls your business number, the call routes through your existing voice connection (Voice API, SIP, TeXML, or AI agent).
* **Outbound calls** — Place calls to WhatsApp users using a SIP URI with the format `<destination>@whatsapp-<your_telnyx_number_without_plus>.sip.telnyx.com`.
* **On-net routing** — All WhatsApp voice calls route through Meta's network. These are not PSTN calls.
* **Concurrent call limit** — Meta allows a maximum of 1,000 concurrent calls per business number.

<Warning>
  Outbound WhatsApp calling is not available for numbers in the United States, Canada, Egypt, Vietnam, and Nigeria. This is a Meta platform restriction.
</Warning>

## Prerequisites

Before enabling WhatsApp calling, you need:

* A **Telnyx account** with an [API key](https://portal.telnyx.com).
* A **WhatsApp Business Account** connected via [Embedded Signup](/docs/messaging/whatsapp/embedded-signup).
* A **verified phone number** added to your WABA.
* A **voice connection** (Voice API, SIP, or TeXML) configured in the [Telnyx Portal](https://portal.telnyx.com).
* A **WABA daily messaging limit** of at least **2,000 unique recipients** — Meta requires this minimum before calling APIs can be enabled.

### Connect your WhatsApp Business Account

In the Telnyx Portal, navigate to **Messaging Suite → WhatsApp Messaging** to start the Embedded Signup flow. The page walks you through connecting your WhatsApp Business Account to Telnyx.

<Frame>
  <img src="https://mintcdn.com/telnyx/GB6TeQPOlQbqprK8/img/whatsapp-business-calling-embedded-signup-start.png?fit=max&auto=format&n=GB6TeQPOlQbqprK8&q=85&s=d2ed72f319f689687a6e4beb2b729078" alt="WhatsApp Numbers page in the Telnyx Portal showing the Embedded Signup flow with Prerequisites, Connect with Facebook, and Requirements sections" width="1512" height="801" data-path="img/whatsapp-business-calling-embedded-signup-start.png" />
</Frame>

Click **Connect WhatsApp Business** to sign in with your Facebook account and authorize Telnyx to manage your WhatsApp Business Account.

<Frame>
  <img src="https://mintcdn.com/telnyx/GB6TeQPOlQbqprK8/img/whatsapp-business-calling-embedded-signup-connect.png?fit=max&auto=format&n=GB6TeQPOlQbqprK8&q=85&s=8a9843ca2ffe5cfcd4066f1774ef4d70" alt="Connect with Facebook section showing the Connect WhatsApp Business button and requirements list" width="1512" height="801" data-path="img/whatsapp-business-calling-embedded-signup-connect.png" />
</Frame>

## Enable WhatsApp calling

<Steps>
  <Step title="Check current calling status">
    Verify whether calling is already enabled on your WhatsApp phone number.

    ```
    GET https://api.telnyx.com/v2/whatsapp/phone_numbers/{phone_number}/calling_settings
    ```

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET "https://api.telnyx.com/v2/whatsapp/phone_numbers/+15551234567/calling_settings" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```

      ```python Python theme={null}
      from telnyx import Telnyx

      client = Telnyx(api_key="YOUR_API_KEY")

      calling_setting = client.whatsapp.phone_numbers.calling_settings.retrieve(
          "+15551234567",
      )
      print(calling_setting.data)
      ```

      ```javascript Node.js theme={null}
      import Telnyx from 'telnyx';

      const client = new Telnyx({ apiKey: 'YOUR_API_KEY' });

      const callingSetting = await client.whatsapp.phoneNumbers.callingSettings.retrieve('+15551234567');

      console.log(callingSetting.data);
      ```

      ```go Go theme={null}
      package main

      import (
      	"context"
      	"fmt"

      	"github.com/team-telnyx/telnyx-go"
      	"github.com/team-telnyx/telnyx-go/option"
      )

      func main() {
      	client := telnyx.NewClient(
      		option.WithAPIKey("My API Key"),
      	)
      	callingSetting, err := client.Whatsapp.PhoneNumbers.CallingSettings.Get(context.TODO(), "+15551234567")
      	if err != nil {
      		panic(err.Error())
      	}
      	fmt.Printf("%+v\n", callingSetting.Data)
      }
      ```

      ```java Java theme={null}
      package com.telnyx.sdk.example;

      import com.telnyx.sdk.client.TelnyxClient;
      import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
      import com.telnyx.sdk.models.whatsapp.phonenumbers.callingsettings.CallingSettingRetrieveParams;
      import com.telnyx.sdk.models.whatsapp.phonenumbers.callingsettings.CallingSettingRetrieveResponse;

      public final class Main {
          private Main() {}

          public static void main(String[] args) {
              TelnyxClient client = TelnyxOkHttpClient.fromEnv();

              CallingSettingRetrieveParams params = CallingSettingRetrieveParams.builder()
                  .phoneNumber("+15551234567")
                  .build();
              CallingSettingRetrieveResponse callingSetting = client.whatsapp().phoneNumbers().callingSettings().retrieve(params);
          }
      }
      ```

      ```ruby Ruby theme={null}
      require "telnyx"

      telnyx = Telnyx::Client.new(api_key: "My API Key")

      calling_setting = telnyx.whatsapp.phone_numbers.calling_settings.retrieve("+15551234567")

      puts(calling_setting)
      ```
    </CodeGroup>

    The response includes an `enabled` field — `false` means calling is not yet active.

    ```json theme={null}
    {
      "data": {
        "record_type": "whatsapp_calling_settings",
        "phone_number": "+15551234567",
        "enabled": false,
        "updated_at": "2026-04-28T12:00:00Z"
      }
    }
    ```
  </Step>

  <Step title="Enable calling">
    Enable WhatsApp calling by setting `enabled` to `true`.

    ```
    PATCH https://api.telnyx.com/v2/whatsapp/phone_numbers/{phone_number}/calling_settings
    ```

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X PATCH "https://api.telnyx.com/v2/whatsapp/phone_numbers/+15551234567/calling_settings" \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{ "enabled": true }'
      ```

      ```python Python theme={null}
      from telnyx import Telnyx

      client = Telnyx(api_key="YOUR_API_KEY")

      calling_setting = client.whatsapp.phone_numbers.calling_settings.update(
          phone_number="+15551234567",
          enabled=True,
      )
      print(calling_setting.data)
      ```

      ```javascript Node.js theme={null}
      import Telnyx from 'telnyx';

      const client = new Telnyx({ apiKey: 'YOUR_API_KEY' });

      const callingSetting = await client.whatsapp.phoneNumbers.callingSettings.update('+15551234567', {
        enabled: true,
      });

      console.log(callingSetting.data);
      ```

      ```go Go theme={null}
      package main

      import (
      	"context"
      	"fmt"

      	"github.com/team-telnyx/telnyx-go"
      	"github.com/team-telnyx/telnyx-go/option"
      )

      func main() {
      	client := telnyx.NewClient(
      		option.WithAPIKey("My API Key"),
      	)
      	callingSetting, err := client.Whatsapp.PhoneNumbers.CallingSettings.Update(
      		context.TODO(),
      		"+15551234567",
      		telnyx.WhatsappPhoneNumberCallingSettingUpdateParams{
      			Enabled: true,
      		},
      	)
      	if err != nil {
      		panic(err.Error())
      	}
      	fmt.Printf("%+v\n", callingSetting.Data)
      }
      ```

      ```java Java theme={null}
      package com.telnyx.sdk.example;

      import com.telnyx.sdk.client.TelnyxClient;
      import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
      import com.telnyx.sdk.models.whatsapp.phonenumbers.callingsettings.CallingSettingUpdateParams;
      import com.telnyx.sdk.models.whatsapp.phonenumbers.callingsettings.CallingSettingUpdateResponse;

      public final class Main {
          private Main() {}

          public static void main(String[] args) {
              TelnyxClient client = TelnyxOkHttpClient.fromEnv();

              CallingSettingUpdateParams params = CallingSettingUpdateParams.builder()
                  .phoneNumber("+15551234567")
                  .enabled(true)
                  .build();
              CallingSettingUpdateResponse callingSetting = client.whatsapp().phoneNumbers().callingSettings().update(params);
          }
      }
      ```

      ```ruby Ruby theme={null}
      require "telnyx"

      telnyx = Telnyx::Client.new(api_key: "My API Key")

      calling_setting = telnyx.whatsapp.phone_numbers.calling_settings.update("+15551234567", enabled: true)

      puts(calling_setting)
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure inbound routing">
    Inbound WhatsApp calls route through your voice connection. If you haven't set one up yet, configure one of the following:

    * [Voice API](/docs/voice/programmable-voice) — Handle calls programmatically with webhooks.
    * [SIP Trunking](/docs/sip-trunking) — Route calls to your SIP infrastructure.
    * [TeXML](/docs/voice/texml) — Control calls with XML-based instructions.
  </Step>
</Steps>

## Make outbound calls

<Info>
  The WhatsApp user must grant calling permission before you can place an outbound call to them. Permission can be obtained in three ways:

  * **Permission request message** — Send a calling permission request via WhatsApp message (rate-limited to 1 request per 24 hours and 2 requests per 7 days per user).
  * **Callback permission** — The user calls your business first, which grants temporary permission for 7 days. This requires "Allow Callbacks" to be enabled in Meta Business Suite.
  * **User grants via profile** — The user enables calling from your WhatsApp Business Profile settings, granting permanent permission.

  Temporary permission (from callback or accepted request) lasts 7 days. Permission granted via profile settings is permanent until the user revokes it. After 2 consecutive unanswered outbound calls, WhatsApp sends the user a nudge notification. After 4 consecutive unanswered calls, permission is automatically revoked.
</Info>

To place an outbound WhatsApp call, use the SIP URI format:

```
<destination>@whatsapp-<your_telnyx_number_without_plus>.sip.telnyx.com
```

For example, to call `+442071234567` from your Telnyx number `+15551234567`:

```
+442071234567@whatsapp-15551234567.sip.telnyx.com
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.telnyx.com/v2/calls \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "connection_id": "YOUR_CONNECTION_ID",
      "to": "sip:+442071234567@whatsapp-15551234567.sip.telnyx.com",
      "from": "+15551234567"
    }'
  ```
</CodeGroup>

<Warning>
  Outbound calling is restricted for numbers in the US, Canada, Egypt, Vietnam, and Nigeria. Attempts from these countries return an error.
</Warning>

## Disable calling

To turn off WhatsApp calling, set `enabled` to `false`:

```bash theme={null}
curl -X PATCH "https://api.telnyx.com/v2/whatsapp/phone_numbers/+15551234567/calling_settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Calling is enabled but inbound calls are not arriving">
    Verify that your phone number has an active voice connection configured. Inbound WhatsApp calls route through the same connection used for regular voice calls. Check your connection settings in the [Telnyx Portal](https://portal.telnyx.com).
  </Accordion>

  <Accordion title="Outbound calls fail with a geo-restriction error">
    Outbound WhatsApp calling is not available for numbers registered in the US, Canada, Egypt, Vietnam, or Nigeria. This is a Meta platform restriction and cannot be overridden.
  </Accordion>

  <Accordion title="The enabled field returns false after a PATCH request">
    Ensure the phone number is verified and actively registered with your WhatsApp Business Account. Numbers that have not completed Meta's verification process cannot enable calling.
  </Accordion>

  <Accordion title="Call quality issues">
    WhatsApp calls route through Meta's network, not the PSTN. Call quality depends on the end user's internet connection. This is consistent with standard WhatsApp voice call behavior.
  </Accordion>

  <Accordion title="Calling APIs cannot be enabled for this phone number">
    Your WhatsApp Business Account must have a daily messaging limit of at least 2,000 unique recipients before Meta allows calling APIs to be enabled. Increase your messaging volume and quality rating to raise your limit.
  </Accordion>

  <Accordion title="Outbound call fails despite having permission">
    Verify that the phone number is associated with the voice connection you are using in the API call. Also check the SIP URI format — the Telnyx number in the host portion must not include the leading `+` (e.g., `whatsapp-15551234567.sip.telnyx.com`, not `whatsapp-+15551234567.sip.telnyx.com`).
  </Accordion>

  <Accordion title="Outbound calls go unanswered and permission is revoked">
    After 2 consecutive unanswered outbound calls, WhatsApp sends the user a nudge notification asking if they want to continue receiving calls. After 4 consecutive unanswered calls, calling permission is automatically revoked and you will need to obtain permission again.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={3}>
  <Card title="Send WhatsApp Messages" icon="message" href="/docs/messaging/whatsapp/send-messages">
    Send text, media, and template messages over WhatsApp.
  </Card>

  <Card title="Embedded Signup" icon="link" href="/docs/messaging/whatsapp/embedded-signup">
    Connect your WhatsApp Business Account to Telnyx.
  </Card>

  <Card title="Programmable Voice" icon="phone" href="/docs/voice/programmable-voice">
    Build voice applications with the Telnyx Voice API.
  </Card>
</CardGroup>