WhatsApp Business Calling

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.

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

Prerequisites

Before enabling WhatsApp calling, you need:

A Telnyx account with an API key.
A WhatsApp Business Account connected via Embedded Signup.
A verified phone number added to your WABA.
A voice connection (Voice API, SIP, or TeXML) configured in the Telnyx Portal.
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.

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

Enable WhatsApp calling

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

curl -X GET "https://api.telnyx.com/v2/whatsapp/phone_numbers/+15551234567/calling_settings" \
  -H "Authorization: Bearer YOUR_API_KEY"

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)

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);

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)
}

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);
    }
}

require "telnyx"

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

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

puts(calling_setting)

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

{
  "data": {
    "record_type": "whatsapp_calling_settings",
    "phone_number": "+15551234567",
    "enabled": false,
    "updated_at": "2026-04-28T12:00:00Z"
  }
}

Enable calling

Enable WhatsApp calling by setting enabled to true.

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

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 }'

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)

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);

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)
}

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);
    }
}

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)

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 — Handle calls programmatically with webhooks.
SIP Trunking — Route calls to your SIP infrastructure.
TeXML — Control calls with XML-based instructions.

Make outbound calls

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.

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

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"
  }'

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

Disable calling

To turn off WhatsApp calling, set enabled to false:

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

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.

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.

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.

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.

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.

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).

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.

Next steps

Send WhatsApp Messages

Send text, media, and template messages over WhatsApp.

Embedded Signup

Connect your WhatsApp Business Account to Telnyx.

Programmable Voice

Build voice applications with the Telnyx Voice API.

Getting Started

Sending Messages

Calling

Management API

Sending API

For AI Agents

WhatsApp Business Calling

How it works

Prerequisites

Connect your WhatsApp Business Account

Enable WhatsApp calling

Make outbound calls

Disable calling

Troubleshooting

Next steps

Send WhatsApp Messages

Embedded Signup

Programmable Voice

​How it works

​Prerequisites

​Connect your WhatsApp Business Account

​Enable WhatsApp calling

​Make outbound calls

​Disable calling

​Troubleshooting

​Next steps

Send WhatsApp Messages

Embedded Signup

Programmable Voice

How it works

Prerequisites

Connect your WhatsApp Business Account

Enable WhatsApp calling

Make outbound calls

Disable calling

Troubleshooting

Next steps