api

WhatsApp API.

API to communicate with WhatsApp Cloud API.

class pipecat.transports.whatsapp.api.WhatsAppSession(*, sdp: str, sdp_type: str)

Bases: BaseModel

WebRTC session information for WhatsApp calls.

Parameters:

• sdp – Session Description Protocol (SDP) data for WebRTC connection

• sdp_type – Type of SDP (e.g., “offer”, “answer”)

sdp: str

sdp_type: str

class pipecat.transports.whatsapp.api.WhatsAppError(*, code: int, message: str, href: str, error_data: dict[str, Any])

Bases: BaseModel

Error information from WhatsApp API responses.

Parameters:

• code – Error code number

• message – Human-readable error message

• href – URL for more information about the error

• error_data – Additional error-specific data

code: int

message: str

href: str

error_data: dict[str, Any]

class pipecat.transports.whatsapp.api.WhatsAppConnectCall(*, id: str, from_: str, to: str, event: str, timestamp: str, direction: str | None, session: WhatsAppSession)

Bases: BaseModel

Incoming call connection event data.

Represents a user-initiated call that requires handling. This is sent when a WhatsApp user initiates a call to your business number.

Parameters:

• id – Unique call identifier

• from – Phone number of the caller (WhatsApp ID format)

• to – Your business phone number that received the call

• event – Always “connect” for incoming calls

• timestamp – ISO 8601 timestamp when the call was initiated

• direction – Optional call direction (“inbound” for user-initiated calls)

• session – WebRTC session data containing SDP offer from the caller

id: str

from_: str

to: str

event: str

timestamp: str

direction: str | None

session: WhatsAppSession

class pipecat.transports.whatsapp.api.WhatsAppTerminateCall(*, id: str, from_: str, to: str, event: str, timestamp: str, direction: str | None, biz_opaque_callback_data: str | None = None, status: str | None = None, start_time: str | None = None, end_time: str | None = None, duration: int | None = None)

Bases: BaseModel

Call termination event data.

Represents the end of a call session, whether completed successfully, failed, or was rejected by either party.

Parameters:

• id – Unique call identifier (matches the connect event)

• from – Phone number of the caller

• to – Your business phone number

• event – Always “terminate” for call end events

• timestamp – ISO 8601 timestamp when the call ended

• direction – Optional call direction

• biz_opaque_callback_data – Optional business-specific callback data

• status – Call completion status (“FAILED”, “COMPLETED”, “REJECTED”)

• start_time – ISO 8601 timestamp when call actually started (after acceptance)

• end_time – ISO 8601 timestamp when call ended

• duration – Call duration in seconds (only for completed calls)

id: str

from_: str

to: str

event: str

timestamp: str

direction: str | None

biz_opaque_callback_data: str | None

status: str | None

start_time: str | None

end_time: str | None

duration: int | None

class pipecat.transports.whatsapp.api.WhatsAppProfile(*, name: str)

Bases: BaseModel

User profile information.

Parameters:

name – Display name of the WhatsApp user

name: str

class pipecat.transports.whatsapp.api.WhatsAppContact(*, profile: WhatsAppProfile, wa_id: str)

Bases: BaseModel

Contact information for a WhatsApp user.

Parameters:

• profile – User’s profile information

• wa_id – WhatsApp ID (phone number in international format without +)

profile: WhatsAppProfile

wa_id: str

class pipecat.transports.whatsapp.api.WhatsAppMetadata(*, display_phone_number: str, phone_number_id: str)

Bases: BaseModel

Business phone number metadata.

Parameters:

• display_phone_number – Formatted phone number for display

• phone_number_id – WhatsApp Business API phone number ID

display_phone_number: str

phone_number_id: str

class pipecat.transports.whatsapp.api.WhatsAppConnectCallValue(*, messaging_product: str, metadata: WhatsAppMetadata, contacts: list[WhatsAppContact], calls: list[WhatsAppConnectCall])

Bases: BaseModel

Webhook payload for incoming call events.

Parameters:

• messaging_product – Always “whatsapp”

• metadata – Business phone number information

• contacts – List of contact information for involved parties

• calls – List of call connection events

messaging_product: str

metadata: WhatsAppMetadata

contacts: list[WhatsAppContact]

calls: list[WhatsAppConnectCall]

class pipecat.transports.whatsapp.api.WhatsAppTerminateCallValue(*, messaging_product: str, metadata: WhatsAppMetadata, calls: list[WhatsAppTerminateCall], errors: list[WhatsAppError] | None = None)

Bases: BaseModel

Webhook payload for call termination events.

Parameters:

• messaging_product – Always “whatsapp”

• metadata – Business phone number information

• calls – List of call termination events

• errors – Optional list of errors that occurred during the call

messaging_product: str

metadata: WhatsAppMetadata

calls: list[WhatsAppTerminateCall]

errors: list[WhatsAppError] | None

class pipecat.transports.whatsapp.api.WhatsAppChange(*, value: WhatsAppConnectCallValue | WhatsAppTerminateCallValue, field: str)

Bases: BaseModel

Webhook change event wrapper.

Parameters:

• value – The actual event data (connect or terminate)

• field – Always “calls” for calling webhooks

value: WhatsAppConnectCallValue | WhatsAppTerminateCallValue

field: str

class pipecat.transports.whatsapp.api.WhatsAppEntry(*, id: str, changes: list[WhatsAppChange])

Bases: BaseModel

Webhook entry containing one or more changes.

Parameters:

• id – WhatsApp Business Account ID

• changes – List of change events in this webhook delivery

id: str

changes: list[WhatsAppChange]

class pipecat.transports.whatsapp.api.WhatsAppWebhookRequest(*, object: str, entry: list[WhatsAppEntry])

Bases: BaseModel

Complete webhook request from WhatsApp.

This is the top-level structure for all webhook deliveries from the WhatsApp Cloud API for calling events.

Parameters:

• object – Always “whatsapp_business_account”

• entry – List of webhook entries (usually contains one entry)

object: str

entry: list[WhatsAppEntry]

class pipecat.transports.whatsapp.api.WhatsAppApi(whatsapp_token: str, phone_number_id: str, session: ClientSession)

Bases: object

WhatsApp Cloud API client for handling calls.

This class provides methods to interact with the WhatsApp Cloud API for managing voice calls, including answering, rejecting, and terminating calls.

Parameters:

• BASE_URL – Base URL for WhatsApp Graph API v23.0

• phone_number_id – Your WhatsApp Business phone number ID

• session – aiohttp client session for making HTTP requests

• whatsapp_url – Complete URL for the calls endpoint

• whatsapp_token – Bearer token for API authentication

BASE_URL = 'https://graph.facebook.com/v23.0/'

__init__(whatsapp_token: str, phone_number_id: str, session: ClientSession) → None

Initialize the WhatsApp API client.

Parameters:

• whatsapp_token – WhatsApp access token for authentication

• phone_number_id – Your business phone number ID from WhatsApp Business API

• session – aiohttp ClientSession for making HTTP requests

update_whatsapp_token(whatsapp_token: str)

Update the WhatsApp access token for authentication.

update_whatsapp_phone_number_id(phone_number_id: str)

Update the WhatsApp phone number ID for authentication.

async answer_call_to_whatsapp(call_id: str, action: str, sdp: str, from_: str)

Answer an incoming WhatsApp call.

This method handles the call answering process, supporting both “pre_accept” and “accept” actions as required by the WhatsApp calling workflow.

Parameters:

• call_id – Unique identifier for the call (from connect webhook)

• action – Action to perform (“pre_accept” or “accept”)

• sdp – Session Description Protocol answer for WebRTC connection

• from – Caller’s phone number (WhatsApp ID format)

Returns:

Dict containing the API response with success status and any error details

Note

Calls must be pre-accepted before being accepted. The typical flow is: 1. Receive connect webhook 2. Call with action=”pre_accept” 3. Call with action=”accept”

async reject_call_to_whatsapp(call_id: str)

Reject an incoming WhatsApp call.

This method rejects a call that was received via connect webhook. The caller will receive a rejection notification and a terminate webhook will be sent with status “REJECTED”.

Parameters:

call_id – Unique identifier for the call (from connect webhook)

Returns:

Dict containing the API response with success status and any error details

Note

This should be called instead of answer_call_to_whatsapp when you want to decline the incoming call. The caller will see the call as rejected.

async terminate_call_to_whatsapp(call_id: str)

Terminate an active WhatsApp call.

This method ends an ongoing call that has been previously accepted. Both parties will be disconnected and a terminate webhook will be sent with status “COMPLETED”.

Parameters:

call_id – Unique identifier for the active call

Returns:

Dict containing the API response with success status and any error details

Note

This should only be called for calls that have been accepted and are currently active. For incoming calls that haven’t been accepted yet, use reject_call_to_whatsapp instead.