{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/conversation/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial","admonition"]},"product":"Conversation","type":"markdown"},"seo":{"title":"WhatsApp Voice Calling Support | Sinch","siteUrl":"https://developers.sinch.com","llmstxt":{"title":"Sinch Developer Documentation","description":"LLMs.txt containing a map of all the documentation files for Sinch.","sections":[{"title":"Numbers API","description":"The Numbers API enables you to search for, view, and activate numbers. It's considered a precursor to other APIs in the Sinch product family. The numbers API can be used in tandem with any of our APIs that perform messaging or calling.","includeFiles":["docs/numbers/**/*.md","docs/numbers/**/*.yaml"],"excludeFiles":["docs/numbers/index.md"]},{"title":"Conversation API","description":"Send and receive messages globally on many popular channels with ease and confidence when using Sinch's Conversation API. Conversation API is the preferred API for sending mobile messages on SMS and other social channels with Sinch. It is a simple API with unified error messages, consistent request payloads, and common webhook payloads that are channel-agnostic.","includeFiles":["docs/conversation/**/*.md","docs/conversation/**/*.yaml"],"excludeFiles":["docs/conversation/index.md"]},{"title":"Voice API","description":"The Voice API works as a big telephony switch. The Voice API handles incoming phone calls (also known as incoming call “legs”), sets up outgoing phone calls (or outgoing call “legs”), and bridges the two. The incoming call leg may come in over a data connection (from a smartphone or web application using the Sinch SDKs) or through a local phone number (from the PSTN network). Similarly, the outgoing call leg can be over data (to another smartphone or web application using the Sinch SDKs) or the PSTN network.","includeFiles":["docs/voice/**/*.md","docs/voice/**/*.yaml"],"excludeFiles":["docs/voice/index.md"]},{"title":"Voice API v2","description":"The Voice API works as a big telephony switch. The Voice API handles incoming phone calls (also known as incoming call “legs”), sets up outgoing phone calls (or outgoing call “legs”), and bridges the two. The incoming call leg may come in over a data connection (from a smartphone or web application using the Sinch SDKs) or through a local phone number (from the PSTN network). Similarly, the outgoing call leg can be over data (to another smartphone or web application using the Sinch SDKs) or the PSTN network.","includeFiles":["docs/voice-2.0/**/*.md","docs/voice-2.0/**/*.yaml"],"excludeFiles":["docs/voice-2.0/index.md"]},{"title":"Verification API","description":"The Verification API is a platform for phone number verification. It consists of the API and different software development kits (the Sinch SDKs) that you integrate with your smartphone or web application and cloud based back-end services. Together they enable SMS, Flashcall, Phone Call and Data verification in your application.","includeFiles":["docs/verification/**/*.md","docs/verification/**/*.yaml"],"excludeFiles":["docs/verification/index.md"]},{"title":"Provisioning API","description":"Provisioning API allows you to programmatically set up your senders, accounts and templates on your favorite messaging platforms on the Conversation API. For now, you can create your first WhatsApp channel through Meta's Embedded sign up, you can configure your first SMS App and configure your webhooks. As development continues, we will be adding the most commonly used channels.","includeFiles":["docs/provisioning-api/**/*.md","docs/provisioning-api/**/*.json"],"excludeFiles":["docs/provisioning-api/index.md"]},{"title":"Elastic SIP Trunking API","description":"With Elastic SIP Trunking you can create and manage your SIP trunks and phone numbers programmatically.","includeFiles":["docs/est/**/*.md","docs/est/**/*.yaml"],"excludeFiles":["docs/est/index.md"]},{"title":"Fax API","description":"Send and receive HIPAA compliant faxes on our modern fax platform using our developer-friendly API.","includeFiles":["docs/fax/**/*.md","docs/fax/**/*.yaml"],"excludeFiles":["docs/fax/index.md"]},{"title":"In-app Voice and Video SDK","description":"The In-app Voice and Video SDK enables you to add voice and video calling capabilities directly into your mobile or web application using the Sinch SDKs.","includeFiles":["docs/in-app-calling/**/*.md"],"excludeFiles":["docs/in-app-calling/index.md"]},{"title":"Number Lookup API","description":"The Number Lookup API is designed to provide in-depth information about phone numbers, helping enterprises enhance their communication strategies and prevent fraud. By identifying the type of phone line (for example, mobile, landline, VoIP) and the associated carrier, the API allows businesses to optimize routing, reduce unnecessary costs, and improve customer engagement.","includeFiles":["docs/number-lookup-api-v2/**/*.md","docs/number-lookup-api-v2/**/*.yaml"],"excludeFiles":["docs/number-lookup-api-v2/index.md"]},{"title":"Functions","description":"Serverless compute for voice and messaging. Deploy your code and Sinch routes live calls and messages to it — no infrastructure to run.","includeFiles":["docs/functions/functions/**/*.md","docs/functions/concepts/**/*.md","docs/functions/reference/**/*.md"],"excludeFiles":["docs/functions/functions/index.md"]},{"title":"CLI","description":"One command line for every Sinch API and the full Functions lifecycle — scaffold, run locally, deploy, and manage.","includeFiles":["docs/functions/cli/**/*.md"],"excludeFiles":["docs/functions/cli/index.md"]}]},"description":"Learn how to send WhatsApp voice calling permission requests and call buttons with the Conversation API."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"whatsapp-voice-calling","__idx":0},"children":["WhatsApp Voice Calling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"ConnectButton","attributes":{"title":"Sinch Agentic Tools","icon":"aiCode","option":[{"title":"Sinch Plugins","description":"Install Sinch Plugins","icon":"connection","link":"https://github.com/sinch/sinch-plugins#installation"},{"title":"Sinch Skills","description":"Install Sinch Skills","icon":"ai","link":"https://github.com/sinch/skills#installation"}]},"children":[]}," ",{"$$mdtype":"Tag","name":"ConnectButton","attributes":{"title":"Sinch SDKs","icon":"code","option":[{"title":"Sinch Node.js SDK","description":"Install Sinch Node.js SDK","icon":"node","link":"/docs/sdks/node#installation"},{"title":"Sinch Java SDK","description":"Install Sinch Java SDK","icon":"java","link":"/docs/sdks/java#installation"},{"title":"Sinch .NET SDK","description":"Install Sinch .NET SDK","icon":"dotnet","link":"/docs/sdks/dotnet#installation"},{"title":"Sinch Python SDK","description":"Install Sinch Python SDK","icon":"python","link":"/docs/sdks/python#installation"}]},"children":[]}," ",{"$$mdtype":"Tag","name":"ConnectButton","attributes":{"title":"Sinch CLI & Functions","icon":"window","option":[{"title":"Sinch CLI","description":"Install Sinch CLI","icon":"cli","link":"/docs/functions/cli/installation"},{"title":"Sinch Functions","description":"Quickstart Sinch Functions","icon":"code","link":"/docs/functions/functions/quickstart"}]},"children":[]}," ",{"$$mdtype":"Tag","name":"ConnectMCP","attributes":{"placement":"bottom","alignment":"start","options":["cursor","vscode","copy"]},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Conversation API supports the following WhatsApp messaging entry points for voice calling:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sending call permission requests"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sending call buttons"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Receiving related event callbacks"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["SIP (Session Initiation Protocol) is a standard way for systems to set up, manage, and end voice calls over IP networks."," ","In practice, SIP connects platforms, including WhatsApp Calling, to your telephony stack (for example, PBX or contact center)"," ","so voice sessions can be routed to your business environment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With this model, you can support both:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business-initiated calls"]},", where your business starts the call (typically after required user permission has been obtained)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["User-initiated calls"]},", where the user starts the call from WhatsApp (for example, by tapping a call button)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the current alpha strategy, the supported architecture is customer-owned SIP. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["This is the only model we can document"," ","and support in this phase"]},". The customer owns the SIP infrastructure, provides the SIP endpoint details during onboarding,"," ","and Meta connects directly to that SIP environment for signaling and media."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sinch handles onboarding/configuration and forwards the relevant WhatsApp call lifecycle and permission-reply events to the customer webhook platform."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more background on WhatsApp Calling and SIP onboarding, see Meta's documentation for ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.facebook.com/documentation/business-messaging/whatsapp/calling"},"children":["Cloud API Calling"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"alpha-architecture-current-scope","__idx":1},"children":["Alpha architecture (current scope)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The details of the current scope of the alpha architecture are below:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer owns and operates the SIP infrastructure and telephony platform."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer provides SIP server details (hostname, port, TLS, credentials, and related configuration) during Sinch-supported onboarding."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Meta connection is configured with the customer SIP endpoint and establishes the SIP session and media path directly with the customer's SIP environment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sinch handles onboarding/configuration support and forwards the relevant call lifecycle and permission-reply events to the customer webhook platform."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sinch does not own or proxy the media path in this phase."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-flow","__idx":2},"children":["Configuration flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The configuration process is illustrated below:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n C[Customer] -->|Share SIP details: host, port, TLS, credentials| S[Sinch onboarding / configuration]\n S -->|Add customer SIP settings to Meta| M[Meta WhatsApp Calling]\n S -->|Provide Meta master password back to customer| C\n","diagramHtml":"

Share SIP details: host, port, TLS, credentials

Add customer SIP settings to Meta

Provide Meta master password back to customer

Customer

Sinch onboarding / configuration

Meta WhatsApp Calling

","diagramHtmlDark":"

Share SIP details: host, port, TLS, credentials

Add customer SIP settings to Meta

Provide Meta master password back to customer

Customer

Sinch onboarding / configuration

Meta WhatsApp Calling

"},"children":["flowchart LR\n C[Customer] -->|Share SIP details: host, port, TLS, credentials| S[Sinch onboarding / configuration]\n S -->|Add customer SIP settings to Meta| M[Meta WhatsApp Calling]\n S -->|Provide Meta master password back to customer| C\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhook-event-flow","__idx":3},"children":["Webhook event flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The webhook event flow is illustrated below:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n U[WhatsApp user] -->|Reply to call permission request / start call / end call| M[Meta WhatsApp Calling]\n M -->|Calling lifecycle + permission reply events| S[Sinch Conversation API]\n S -->|Forward events| W[Customer webhook platform]\n","diagramHtml":"

Reply to call permission request / start call / end call

Calling lifecycle + permission reply events

Forward events

WhatsApp user

Meta WhatsApp Calling

Sinch Conversation API

Customer webhook platform

","diagramHtmlDark":"

Reply to call permission request / start call / end call

Calling lifecycle + permission reply events

Forward events

WhatsApp user

Meta WhatsApp Calling

Sinch Conversation API

Customer webhook platform

"},"children":["flowchart LR\n U[WhatsApp user] -->|Reply to call permission request / start call / end call| M[Meta WhatsApp Calling]\n M -->|Calling lifecycle + permission reply events| S[Sinch Conversation API]\n S -->|Forward events| W[Customer webhook platform]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"call-flow-sip-signaling-and-media","__idx":4},"children":["Call flow (SIP signaling and media)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The call flow is illustrated below:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n CUST[Customer] -->|Call permission request / call button| S[Sinch Conversation API]\n S -->|Send message to Meta| M[Meta WhatsApp Calling]\n U[WhatsApp user] -->|Click call button / accept permission| M\n M -->|Direct SIP signaling + RTP media| SIP[Customer-owned SIP infrastructure]\n SIP -->|Voice app / PBX / contact center| V[Customer telephony platform]\n","diagramHtml":"

Call permission request / call button

Send message to Meta

Click call button / accept permission

Direct SIP signaling + RTP media

Voice app / PBX / contact center

Customer

Sinch Conversation API

Meta WhatsApp Calling

WhatsApp user

Customer-owned SIP infrastructure

Customer telephony platform

","diagramHtmlDark":"

Call permission request / call button

Send message to Meta

Click call button / accept permission

Direct SIP signaling + RTP media

Voice app / PBX / contact center

Customer

Sinch Conversation API

Meta WhatsApp Calling

WhatsApp user

Customer-owned SIP infrastructure

Customer telephony platform

"},"children":["flowchart LR\n CUST[Customer] -->|Call permission request / call button| S[Sinch Conversation API]\n S -->|Send message to Meta| M[Meta WhatsApp Calling]\n U[WhatsApp user] -->|Click call button / accept permission| M\n M -->|Direct SIP signaling + RTP media| SIP[Customer-owned SIP infrastructure]\n SIP -->|Voice app / PBX / contact center| V[Customer telephony platform]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-conversation-api-scenarios","__idx":5},"children":["Supported Conversation API scenarios"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With the WhatsApp channel, you can use Conversation API to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["template"]}," call permission request;"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["free form"]}," call permission request;"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["template"]}," call button message;"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["free form"]}," call button message;"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally receive permission reply, call connect, and call terminate events on your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EVENT"]}," webhook."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note the following:"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A call permission request is used when your business wants to place a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["business-initiated call"]}," to the user."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A call button message is used when you want the user to place a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["user-initiated call"]}," to your"," ","business from WhatsApp."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Outside the WhatsApp ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://community.sinch.com/t5/WhatsApp/What-is-a-customer-service-window/ta-p/6858"},"children":["customer service window"]},", you must use an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://community.sinch.com/t5/WhatsApp/What-is-a-message-template-and-why-are-they-necessary/ta-p/6857"},"children":["approved WhatsApp template"]},"."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sending-a-template-call-permission-request","__idx":6},"children":["Sending a template call permission request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To send a template-based call permission request, use a Conversation API ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/conversation/api-reference/conversation/messages/messages_sendmessage#messages/messages_sendmessage/t=request&path=message&oneof=5/template_message"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["template_message"]}]}," and reference"," ","an approved WhatsApp template whose interaction type in Meta is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call_permission_request"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below is an example payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"app_id\": \"01KX1DEK870THTWCNENESBW5DP\",\n \"recipient\": {\n \"identified_by\": {\n \"channel_identities\": [\n {\n \"channel\": \"WHATSAPP\",\n \"identity\": \"555XXXXXXXXX\"\n }\n ]\n }\n },\n \"message\": {\n \"template_message\": {\n \"channel_template\": {\n \"WHATSAPP\": {\n \"template_id\": \"calls_permission_request_test\",\n \"language_code\": \"en\"\n }\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The actual header, body, footer, and call permission interaction are defined in the approved Meta template. If your"," ","template contains variables, populate them the same way as other WhatsApp templates. See our documentation on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/conversation/channel-support/whatsapp/template-support/"},"children":["template messages"]}," for more information."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sending-a-free-form-call-permission-request","__idx":7},"children":["Sending a free form call permission request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To send a free form call permission request during an open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://community.sinch.com/t5/WhatsApp/What-is-a-customer-service-window/ta-p/6858"},"children":["customer service window"]},", use a"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/conversation/api-reference/conversation/messages/messages_sendmessage#messages/messages_sendmessage/t=request&path=message&oneof=0/channel_specific_message"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_specific_message"]}]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message_type"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call_permission_request"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below is an example payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"app_id\": \"01KX1DEK870THTWCNENESBW5DP\",\n \"recipient\": {\n \"identified_by\": {\n \"channel_identities\": [\n {\n \"channel\": \"WHATSAPP\",\n \"identity\": \"555XXXXXXXXX\"\n }\n ]\n }\n },\n \"message\": {\n \"channel_specific_message\": {\n \"WHATSAPP\": {\n \"message_type\": \"call_permission_request\",\n \"message\": {\n \"body\": {\n \"text\": \"test\"\n }\n }\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The body text is optional, but Meta recommends including context so the recipient understands why your business wants"," ","permission to call."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sending-a-template-call-button-message","__idx":8},"children":["Sending a template call button message"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To send a template-based call button, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["template_message"]}," and reference an approved WhatsApp template whose button"," ","type in Meta is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voice_call"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below is an example payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"app_id\": \"01KX1DEK870THTWCNENESBW5DP\",\n \"recipient\": {\n \"identified_by\": {\n \"channel_identities\": [\n {\n \"channel\": \"WHATSAPP\",\n \"identity\": \"555XXXXXXXXX\"\n }\n ]\n }\n },\n \"message\": {\n \"template_message\": {\n \"channel_template\": {\n \"WHATSAPP\": {\n \"template_id\": \"call_button_test\",\n \"language_code\": \"en_US\"\n }\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This message invites the user to start a voice call to your business from WhatsApp. As with other WhatsApp templates,"," ","the button definition itself is managed in Meta when the template is created and approved. See our documentation on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/conversation/channel-support/whatsapp/template-support/"},"children":["template messages"]}," for more information."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sending-a-free-form-call-button-message","__idx":9},"children":["Sending a free form call button message"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To send a free form call button during an open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://community.sinch.com/t5/WhatsApp/What-is-a-customer-service-window/ta-p/6858"},"children":["customer service window"]},", send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_specific_message"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message_type"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voice_call"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below is an example payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"app_id\": \"01KX1DEK870THTWCNENESBW5DP\",\n \"recipient\": {\n \"identified_by\": {\n \"channel_identities\": [\n {\n \"channel\": \"WHATSAPP\",\n \"identity\": \"555XXXXXXXXX\"\n }\n ]\n }\n },\n \"message\": {\n \"channel_specific_message\": {\n \"WHATSAPP\": {\n \"message_type\": \"voice_call\",\n \"message\": {\n \"body\": {\n \"text\": \"test\"\n },\n \"ttl_minutes\": 100,\n \"display_text\": \"Voice Call\",\n \"payload\": \"test\"\n }\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the message fields as follows:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body.text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required text shown together with the call button."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ttl_minutes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time-to-live for the call button CTA. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10080"]}," (7 days)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["display_text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The text shown on the WhatsApp call button. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Call now"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional tracking value returned in calling events as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cta_payload"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"receiving-calling-events","__idx":10},"children":["Receiving calling events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Conversation API can transcode the relevant WhatsApp calling callbacks and deliver them to your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EVENT"]}," webhook as"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contact_event.channel_specific_event"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Alpha scope note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the current customer-owned SIP model, webhooks are optional and informational. They can be used for permission, connection, and"," ","termination tracking. They are not required to establish the SIP call. The actual SIP signaling and RTP media path is"," ","established directly between Meta and the customer's SIP infrastructure, not via a Sinch-managed media bridge."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"call-permission-reply-event","__idx":11},"children":["Call permission reply event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a user accepts or rejects a call permission request, you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp_call_permission_reply_event"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The user's decision. Expected values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accept"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reject"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_permanent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," if the user granted permanent permission, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," for temporary permission."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiration_timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Expiration timestamp for temporary permission. Omitted for permanent permission."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below is an example with temporary permission:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"app_id\": \"01KX1DEK870THTWCNENESBW5DP\",\n \"event_time\": \"2026-08-28T14:05:28Z\",\n \"project_id\": \"2cb92b1b-2faf-40be-9380-accec4f24f46\",\n \"event\": {\n \"direction\": \"TO_APP\",\n \"contact_event\": {\n \"channel_specific_event\": {\n \"whatsapp_call_permission_reply_event\": {\n \"response\": \"accept\",\n \"is_permanent\": false,\n \"expiration_timestamp\": \"2026-09-04T14:05:28Z\"\n }\n }\n },\n \"id\": \"01M14B18KSPNDA9VX89J6G5D6R\",\n \"conversation_id\": \"\",\n \"contact_id\": \"\",\n \"channel_identity\": {\n \"channel\": \"WHATSAPP\",\n \"identity\": \"555XXXXXXXXX\",\n \"app_id\": \"\"\n },\n \"accept_time\": \"2026-08-28T14:05:30.729904748Z\",\n \"processing_mode\": \"DISPATCH\"\n },\n \"message_metadata\": \"\",\n \"correlation_id\": \"\",\n \"channel_metadata\": {\n \"whatsapp\": {\n \"message_type\": \"interactive\",\n \"interactive_message_type\": \"call_permission_reply\",\n \"profile_names\": {\n \"555XXXXXXXXX\": \"John\"\n },\n \"sender_phone_number\": \"SENDER_phone_number\",\n \"user_profile\": {\n \"display_name\": \"John\",\n \"username\": \"john_user\",\n \"country_code\": \"BR\",\n \"phone_number\": \"SENDER_phone_number\",\n \"user_id\": \"BR.3234965106801957\"\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below is an example with permanent permission:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"app_id\": \"01KX1DEK870THTWCNENESBW5DP\",\n \"event_time\": \"2026-08-28T13:54:59Z\",\n \"project_id\": \"2cb92b1b-2faf-40be-9380-accec4f24f46\",\n \"event\": {\n \"direction\": \"TO_APP\",\n \"contact_event\": {\n \"channel_specific_event\": {\n \"whatsapp_call_permission_reply_event\": {\n \"response\": \"accept\",\n \"is_permanent\": true\n }\n }\n },\n \"id\": \"01M14AE3DAA8QA0XGC4C7XNXEJ\",\n \"conversation_id\": \"\",\n \"contact_id\": \"\",\n \"channel_identity\": {\n \"channel\": \"WHATSAPP\",\n \"identity\": \"555XXXXXXXXX\",\n \"app_id\": \"\"\n },\n \"accept_time\": \"2026-08-28T13:55:02.791959571Z\",\n \"processing_mode\": \"DISPATCH\"\n },\n \"message_metadata\": \"\",\n \"correlation_id\": \"\",\n \"channel_metadata\": {\n \"whatsapp\": {\n \"message_type\": \"interactive\",\n \"interactive_message_type\": \"call_permission_reply\",\n \"profile_names\": {\n \"555XXXXXXXXX\": \"John\"\n },\n \"sender_phone_number\": \"SENDER_phone_number\",\n \"user_profile\": {\n \"display_name\": \"John\",\n \"username\": \"john_user\",\n \"country_code\": \"BR\",\n \"phone_number\": \"555XXXXXXXXX\",\n \"user_id\": \"BR.3234965106801957\"\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"call-connect-event","__idx":12},"children":["Call connect event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the user starts a WhatsApp voice call to your business (for example, if they used a call button),"," ","you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp_call_connect_event"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["direction"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The call direction. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_INITIATED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deeplink_payload"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payload received from a call deep link, when used."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cta_payload"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payload received from a call button message, when used."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sdp_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional SDP type associated with the call session."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sdp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional SDP content associated with the call session."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"app_id\": \"01KX1DEK870THTWCNENESBW5DP\",\n \"event_time\": \"2026-08-28T14:17:45.812211426Z\",\n \"project_id\": \"2cb92b1b-2faf-40be-9380-accec4f24f46\",\n \"event\": {\n \"direction\": \"TO_APP\",\n \"contact_event\": {\n \"channel_specific_event\": {\n \"whatsapp_call_connect_event\": {\n \"direction\": \"USER_INITIATED\",\n \"deeplink_payload\": \"\",\n \"cta_payload\": \"test\",\n \"sdp_type\": \"\",\n \"sdp\": \"\"\n }\n }\n },\n \"id\": \"01M14BQPMMA37HYBWA2EGARM6A\",\n \"conversation_id\": \"\",\n \"contact_id\": \"\",\n \"channel_identity\": {\n \"channel\": \"WHATSAPP\",\n \"identity\": \"555XXXXXXXXX\",\n \"app_id\": \"\"\n },\n \"accept_time\": \"2026-08-28T14:17:46.218428897Z\",\n \"processing_mode\": \"DISPATCH\"\n },\n \"message_metadata\": \"\",\n \"correlation_id\": \"\",\n \"channel_metadata\": {\n \"whatsapp\": {\n \"profile_names\": {\n \"555XXXXXXXXX\": \"John\"\n },\n \"sender_phone_number\": \"\",\n \"user_profile\": {\n \"display_name\": \"John\",\n \"username\": \"john_user\",\n \"country_code\": \"BR\",\n \"phone_number\": \"555XXXXXXXXX\",\n \"user_id\": \"BR.3234965106801957\"\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"call-terminate-event","__idx":13},"children":["Call terminate event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the call ends, you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp_call_terminate_event"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["direction"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The call direction. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_INITIATED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deeplink_payload"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payload received from a call deep link, when used."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cta_payload"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payload received from a call button message."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call result, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start_time"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call start time."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_time"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call end time."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["duration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call duration."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"app_id\": \"01KX1DEK870THTWCNENESBW5DP\",\n \"event_time\": \"2026-08-28T14:19:04.302983983Z\",\n \"project_id\": \"2cb92b1b-2faf-40be-9380-accec4f24f46\",\n \"event\": {\n \"direction\": \"TO_APP\",\n \"contact_event\": {\n \"channel_specific_event\": {\n \"whatsapp_call_terminate_event\": {\n \"direction\": \"USER_INITIATED\",\n \"deeplink_payload\": \"\",\n \"cta_payload\": \"test\",\n \"status\": \"COMPLETED\",\n \"start_time\": \"1787926665\",\n \"end_time\": \"1787926743\",\n \"duration\": 78\n }\n }\n },\n \"id\": \"01M14BT39CASHZJB0Q74ZW3FFT\",\n \"conversation_id\": \"\",\n \"contact_id\": \"\",\n \"channel_identity\": {\n \"channel\": \"WHATSAPP\",\n \"identity\": \"555XXXXXXXXX\",\n \"app_id\": \"\"\n },\n \"accept_time\": \"2026-08-28T14:19:04.464874671Z\",\n \"processing_mode\": \"DISPATCH\"\n },\n \"message_metadata\": \"\",\n \"correlation_id\": \"\",\n \"channel_metadata\": {\n \"whatsapp\": {\n \"profile_names\": {\n \"555XXXXXXXXX\": \"John\"\n },\n \"sender_phone_number\": \"\",\n \"user_profile\": {\n \"display_name\": \"John\",\n \"username\": \"john_user\",\n \"country_code\": \"BR\",\n \"phone_number\": \"555XXXXXXXXX\",\n \"user_id\": \"BR.3234965106801957\"\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"additional-meta-references","__idx":14},"children":["Additional Meta references"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the call transport and calling lifecycle that happen outside Conversation API message sends,"," ","see Meta's documentation for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.facebook.com/documentation/business-messaging/whatsapp/calling"},"children":["Cloud API Calling"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions"},"children":["Obtaining user call permissions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/call-button-messages-deep-links"},"children":["Sending WhatsApp call button messages and deep links"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-initiated-calls"},"children":["User-initiated calls"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/business-initiated-calls"},"children":["Business-initiated calls"]}]}]}]},"headings":[{"value":"WhatsApp Voice Calling","id":"whatsapp-voice-calling","depth":1},{"value":"Alpha architecture (current scope)","id":"alpha-architecture-current-scope","depth":2},{"value":"Configuration flow","id":"configuration-flow","depth":3},{"value":"Webhook event flow","id":"webhook-event-flow","depth":3},{"value":"Call flow (SIP signaling and media)","id":"call-flow-sip-signaling-and-media","depth":3},{"value":"Supported Conversation API scenarios","id":"supported-conversation-api-scenarios","depth":2},{"value":"Sending a template call permission request","id":"sending-a-template-call-permission-request","depth":2},{"value":"Sending a free form call permission request","id":"sending-a-free-form-call-permission-request","depth":2},{"value":"Sending a template call button message","id":"sending-a-template-call-button-message","depth":2},{"value":"Sending a free form call button message","id":"sending-a-free-form-call-button-message","depth":2},{"value":"Receiving calling events","id":"receiving-calling-events","depth":2},{"value":"Call permission reply event","id":"call-permission-reply-event","depth":3},{"value":"Call connect event","id":"call-connect-event","depth":3},{"value":"Call terminate event","id":"call-terminate-event","depth":3},{"value":"Additional Meta references","id":"additional-meta-references","depth":2}],"frontmatter":{"seo":{"title":"WhatsApp Voice Calling Support | Sinch","description":"Learn how to send WhatsApp voice calling permission requests and call buttons with the Conversation API."}},"lastModified":"2026-09-16T15:28:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/conversation/channel-support/whatsapp/whatsapp-voice-calling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}