{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/in-app-calling/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"product":"In-app Calling","type":"markdown"},"seo":{"title":"Dialing via Voice API v2 | In-app Calling | 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 SMS, RCS, WhatsApp, and other channels with Sinch's Conversation API. Conversation API is the API to use for all new SMS integrations with Sinch; its SMS channel replaces the standalone SMS REST API, which reached end of sale on 15 April 2026. Conversation API has unified error messages, consistent request payloads, and channel-agnostic webhook payloads.","includeFiles":["docs/conversation/**/*.md","docs/conversation/**/*.yaml"],"excludeFiles":["docs/conversation/index.md"]},{"title":"Standalone SMS REST API (end of sale, existing integrations only)","description":"The standalone SMS REST API reached end of sale on 15 April 2026 and is no longer available to new customers. All new SMS integrations must use the SMS channel of Conversation API (https://developers.sinch.com/docs/conversation/channel-support/sms/). Use these pages only to maintain an existing standalone SMS REST API integration, or to migrate it to Conversation API.","includeFiles":["docs/sms/**/*.md","docs/sms/**/*.yaml"],"excludeFiles":["docs/sms/index.md","docs/sms/**/md_snippets/**"]},{"title":"Voice API (legacy/GA)","description":"Which Voice API? If you are building something using voice AI agents, use the Voice API v2. To learn more, you can read [Why migrate to v2?](/docs/voice-2.0/migration.md) or [What's new?](/docs/voice-2.0/whatsnew.md).\n\nThe 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"],"excludeFiles":["docs/voice/index.md"]},{"title":"Voice API v2 (recommended for new builds/preview)","description":"Which Voice API? If you are building something using voice AI agents, use the Voice API v2. To learn more, you can read [Why migrate to v2?](/docs/voice-2.0/migration.md) or [What's new?](/docs/voice-2.0/whatsnew.md).\n\nThe Voice API v2 enables embedding voice calling into applications for virtually limitless use cases. From voice-enabling AI agents to allow real-time conversational AI workflows over the phone, to number masking for privacy, automated appointment reminders, and outreach campaigns with answering machine detection, to bridging calls between PSTN and SIP endpoints, the API offers the flexibility and control needed for modern communications. The Sinch Programmable Voice is a cloud-native global voice platform, composed by multiple Inbound and Outbound voice channels. All these channels can be combined using our powerful markup language called SVAML v2, creating a toolbox capable of building almost limitless use cases. Our SVAML uses the concept of commands, and customers can use a combination of our commands to interact with calls in all channels, in order to model from the most basic to highly complex scenarios, required to fulfill their voice calling needs.","includeFiles":["docs/voice-2.0/**/*.md"],"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/ai-support.md","docs/functions/reference/**/*.md"],"excludeFiles":["docs/functions/functions/index.md"]},{"title":"CLI","description":"One command line for Sinch numbers, messaging, voice, fax, SIP trunking and porting, and the full Functions lifecycle — scaffold, run locally, deploy, and manage.","includeFiles":["docs/functions/cli/**/*.md"],"excludeFiles":["docs/functions/cli/index.md"]}]},"description":"Place calls from your web app that are routed through the Sinch Voice API v2 platform, to phone numbers, SIP endpoints, audio streams and Voice Relay."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"dialing-via-voice-api-v2","__idx":0},"children":["Dialing via Voice API v2"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Beta"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dialing via Voice API v2 is currently in beta. It is fully functional, but interfaces and behavior may change before general availability. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0"},"children":["Voice API v2"]}," itself is available as a public preview."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The JavaScript SDK can place calls that are routed through the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/overview"},"children":["Sinch Voice API v2"]}," platform. We call these calls ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["dials"]},". A dial starts in your app, just like any other outgoing call, but how it's handled is decided by your Voice API v2 configuration. You can use dials to reach phone numbers, SIP endpoints, audio streams and Voice Relay."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-use-dial","__idx":1},"children":["Why use dial?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Calls made from your app with dials are handled by the Voice API v2 platform. This lets you:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Control the call from your Voice API v2 service."]}," The call follows your service configuration. That can be predefined ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/api-reference/svaml"},"children":["SVAML commands"]}," or webhooks to your backend that decide what happens next in real time. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/overview#how-it-works"},"children":["how Voice API v2 works"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reach more destinations from the app."]}," Besides phone numbers and SIP endpoints, a dial can connect the user to an audio stream or to Voice Relay. This makes it easy to, for example, connect your users to an AI voice agent."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use Voice API v2 features."]}," Dials use the same call model, events and features as the rest of Voice API v2. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/whatsnew"},"children":["What is new in Voice v2?"]}," for an overview."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-destinations","__idx":2},"children":["Supported destinations"]},{"$$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":"Destination"},"children":["Destination"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Learn more"},"children":["Learn more"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Phone number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A phone on the regular telephone network (PSTN). Specify the number in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://community.sinch.com/t5/Glossary/E-164/ta-p/7537"},"children":["E.164 format"]},", prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/tutorials/outbound-tts"},"children":["Outbound calls"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SIP endpoint"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A SIP destination, such as your PBX or contact center."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/api-reference/sip/outbound"},"children":["SIP outbound"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Audio stream"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A two-way audio stream to your WebSocket server."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/api-reference/x-voice-stream"},"children":["Voice Streams"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/tutorials/stream-audio"},"children":["Audio streaming"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Voice Relay"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A WebSocket connection with speech-to-text and text-to-speech, for example for chatbots and AI agents."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/api-reference/x-voice-relay"},"children":["Voice Relay"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/tutorials/voice-relay"},"children":["Call chatbots with Voice Relay"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Service configuration takes precedence"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK provides a dial method for each destination type, but your Voice API v2 service has the final say on where the call goes. Your service configuration in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dashboard.sinch.com/"},"children":["dashboard"]}," can set the destination statically, using ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/api-reference/voice/services/updateservice#services/updateservice/t=request&path=callbehavior"},"children":["service call behaviors"]},", or dynamically, using ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/api-reference/voice/webhooks"},"children":["webhooks"]}," to your backend. If such a configuration is present, it always takes precedence over the destination passed to the SDK dial method."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["App-to-app"]}," calls, including video calls, aren't available via Voice API v2 yet. They continue to use the existing in-app calling on Voice API v1. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-app-calling/js/calling"},"children":["Audio calling"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-app-calling/js/video-calling"},"children":["Video calling"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":3},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set up a Voice API v2 service in your project. It defines how your dials are handled. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0/getting-started"},"children":["Getting started with Voice API v2"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When dialing a phone number, the same rules apply as for ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["app-to-phone"]}," calls: you need a valid CLI (Calling Line Identifier), trial accounts can only call verified numbers, and your account needs sufficient credits. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-app-calling/js/calling#presenting-a-number-to-the-destination-you-are-calling"},"children":["Presenting a number to the destination you are calling"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can choose which Voice API v2 service handles a dial. If you don't specify a service, your project's default service is used."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"placing-a-dial","__idx":4},"children":["Placing a dial"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dials are placed using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CallClient"]},", just like other calls. There is one dial method for each destination type: phone number, SIP endpoint, audio stream and Voice Relay. Each method takes the destination and optional, destination-specific options, such as the Voice API v2 service to use, the caller identifier or custom call headers. For the full list of methods and options, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://download.sinch.com/js/latest/reference/index.html"},"children":["Reference Documentation"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const callClient = sinchClient.callClient;\nconst call = await callClient.dialPhoneNumber('+14155550101');\ncall.addListener(...);\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete examples of each destination type, see the dialing samples in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/rtc-reference-applications/tree/master/javascript"},"children":["Sinch reference applications (JavaScript)"]}," on GitHub."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-the-call","__idx":5},"children":["Handling the call"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A dial returns a regular ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Call"]}," object. Follow its progress with the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CallListener"]}," you use for other outgoing calls: you're notified when the call is progressing, answered, established and ended. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-app-calling/js/calling"},"children":["Audio calling"]}," for details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dials are audio-only."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"more-resources","__idx":6},"children":["More resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://download.sinch.com/js/latest/reference/index.html"},"children":["Reference Documentation"]}," for the dial methods and their options."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/sinch/rtc-reference-applications"},"children":["Sinch reference applications"]}," with dialing samples."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-app-calling/js/release-notes"},"children":["Release notes"]}," to see which SDK version introduced dialing and any later changes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/voice-2.0"},"children":["Voice API v2 documentation"]}," for services, SVAML commands, webhooks and events."]}]}]},"headings":[{"value":"Dialing via Voice API v2","id":"dialing-via-voice-api-v2","depth":1},{"value":"Why use dial?","id":"why-use-dial","depth":2},{"value":"Supported destinations","id":"supported-destinations","depth":2},{"value":"Before you begin","id":"before-you-begin","depth":2},{"value":"Placing a dial","id":"placing-a-dial","depth":2},{"value":"Handling the call","id":"handling-the-call","depth":2},{"value":"More resources","id":"more-resources","depth":2}],"frontmatter":{"seo":{"title":"Dialing via Voice API v2 | In-app Calling | Sinch","description":"Place calls from your web app that are routed through the Sinch Voice API v2 platform, to phone numbers, SIP endpoints, audio streams and Voice Relay."}},"lastModified":"2026-10-26T12:25:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/in-app-calling/js/dial","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}