{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/functions/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial"]},"type":"markdown"},"seo":{"title":"Developer Documentation","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":"SMS API","description":"The SMS API allows you to send and receive SMS messages with a few easy steps. You can also send bulk SMS messages to multiple customers using the Sinch SMS service.","includeFiles":["docs/sms/**/*.md","docs/sms/**/*.yaml"],"excludeFiles":["docs/sms/index.md"]},{"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":"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"]}],"hide":false,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"voice-callbacks","__idx":0},"children":["Voice callbacks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Voice callbacks are HTTP POST requests that Sinch sends to your function when something happens during a phone call. Your function responds with ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#"},"children":["SVAML"]}," to control what happens next."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are four events. They describe the lifecycle of a call."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"lifecycle","__idx":1},"children":["Lifecycle"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"inbound-call-with-a-menu","__idx":2},"children":["Inbound call with a menu"]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n autonumber\n participant Caller\n participant Sinch as Sinch Voice Platform\n participant Fn as Your Function\n\n Caller->>Sinch: Dial Sinch number\n Sinch->>Fn: ICE callback\n Fn-->>Sinch: SVAML (say + runMenu)\n Sinch->>Caller: Speak prompt\n Caller->>Sinch: Press DTMF digit\n Sinch->>Fn: PIE callback\n Fn-->>Sinch: SVAML (connectPstn)\n Sinch->>Caller: Connect the call\n Note over Caller,Sinch: Call in progress\n Caller->>Sinch: Hang up\n Sinch->>Fn: DICE callback\n Fn-->>Sinch: (informational, no response)\n","diagramHtml":"
Your FunctionSinch Voice PlatformCallerYour FunctionSinch Voice PlatformCallerCall in progressDial Sinch number1ICE callback2SVAML (say + runMenu)3Speak prompt4Press DTMF digit5PIE callback6SVAML (connectPstn)7Connect the call8Hang up9DICE callback10(informational, no response)11
"},"children":["sequenceDiagram\n autonumber\n participant Caller\n participant Sinch as Sinch Voice Platform\n participant Fn as Your Function\n\n Caller->>Sinch: Dial Sinch number\n Sinch->>Fn: ICE callback\n Fn-->>Sinch: SVAML (say + runMenu)\n Sinch->>Caller: Speak prompt\n Caller->>Sinch: Press DTMF digit\n Sinch->>Fn: PIE callback\n Fn-->>Sinch: SVAML (connectPstn)\n Sinch->>Caller: Connect the call\n Note over Caller,Sinch: Call in progress\n Caller->>Sinch: Hang up\n Sinch->>Fn: DICE callback\n Fn-->>Sinch: (informational, no response)\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"outbound-call-with-amd","__idx":3},"children":["Outbound call with AMD"]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n autonumber\n participant You as Your code\n participant Sinch as Sinch Voice Platform\n participant Callee\n participant Fn as Your Function\n\n You->>Sinch: context.voice.callouts.custom(...)\n Sinch->>Callee: Ring\n Callee->>Sinch: Answer\n Sinch->>Fn: ACE callback (with AMD result)\n Fn-->>Sinch: continue (if human) or hangup (if machine)\n Note over Callee,Sinch: Call in progress\n Callee->>Sinch: Hang up\n Sinch->>Fn: DICE callback\n","diagramHtml":"
Your FunctionCalleeSinch Voice PlatformYour codeYour FunctionCalleeSinch Voice PlatformYour codeCall in progresscontext.voice.callouts.custom(...)1Ring2Answer3ACE callback (with AMD result)4continue (if human) or hangup (if machine)5Hang up6DICE callback7
"},"children":["sequenceDiagram\n autonumber\n participant You as Your code\n participant Sinch as Sinch Voice Platform\n participant Callee\n participant Fn as Your Function\n\n You->>Sinch: context.voice.callouts.custom(...)\n Sinch->>Callee: Ring\n Callee->>Sinch: Answer\n Sinch->>Fn: ACE callback (with AMD result)\n Fn-->>Sinch: continue (if human) or hangup (if machine)\n Note over Callee,Sinch: Call in progress\n Callee->>Sinch: Hang up\n Sinch->>Fn: DICE callback\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most functions only implement ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ice"]},". You only need ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pie"]}," if you run menus, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ace"]}," if you bridge or make outbound calls, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dice"]}," if you want to log or clean up when calls end."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ice--incoming-call-event","__idx":4},"children":["ICE — Incoming Call Event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires when a phone call reaches one of your Sinch phone numbers. This is where most of your work happens — greet the caller, run a menu, connect them somewhere, start a recording, etc."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-get","__idx":5},"children":["What you get"]},{"$$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":"What it is"},"children":["What it is"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique call ID. Use this as a cache key for call state."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cli"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Caller's phone number (E.164 format)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to.endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Sinch number they dialed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to.type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'number'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'username'"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'sip'"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["domain"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'pstn'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'mxp'"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'sip'"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originationType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Origin type — usually ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'pstn'"]}," for phone calls."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom data, if the call was initiated with any."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 timestamp."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-return","__idx":6},"children":["What you return"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A SVAML response. Most common patterns:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Node.js\nreturn new IceSvamlBuilder()\n .say('Welcome to Acme Corp.')\n .runMenu(MenuTemplates.business('Acme Corp'))\n .build();\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"// C#\nreturn Ok(new IceSvamletBuilder()\n .Instructions.Say(\"Welcome to Acme Corp.\")\n .Action.RunMenu(MenuTemplates.Business(\"Acme Corp\"))\n .Build());\n","lang":"csharp"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ace--answered-call-event","__idx":7},"children":["ACE — Answered Call Event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires when a call ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["you initiated"]}," is answered by the other side. This is relevant for outbound calling or when your ICE response bridged the call somewhere with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["connectPstn"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableAce: true"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-get-1","__idx":8},"children":["What you get"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The call ID plus an optional AMD (Answering Machine Detection) result if it was enabled."]},{"$$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":"What it is"},"children":["What it is"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same call ID as the ICE that started this call."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amd.status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'human'"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'machine'"]}," if AMD was enabled."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amd.reason"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Why AMD chose that status."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amd.duration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How long AMD took to decide (milliseconds)."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-return-1","__idx":9},"children":["What you return"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Usually ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["continue"]}," (let the call proceed) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hangup"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"async ace(context, data) {\n if (data.amd?.status === 'machine') {\n return new AceSvamlBuilder().hangup().build();\n }\n return new AceSvamlBuilder()\n .say('Hello! You have a message from Acme Corp.')\n .continue()\n .build();\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"public override async Task Ace(AceCallbackModel data)\n{\n if (data.Amd?.Status == \"machine\")\n return Ok(new AceSvamletBuilder().Action.Hangup().Build());\n\n return Ok(new AceSvamletBuilder()\n .Instructions.Say(\"Hello! You have a message from Acme Corp.\")\n .Action.Continue()\n .Build());\n}\n","lang":"csharp"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pie--prompt-input-event","__idx":10},"children":["PIE — Prompt Input Event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires when a menu you started with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runMenu"]}," completes — the caller pressed a key, the menu timed out, or they hung up during it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-get-2","__idx":11},"children":["What you get"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The call ID plus a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["menuResult"]}," describing what happened."]},{"$$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":"What it is"},"children":["What it is"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["menuResult.menuId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ID of the menu that completed (you set this in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["runMenu"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["menuResult.type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'return'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'sequence'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'timeout'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'hangup'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'invalidinput'"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["menuResult.value"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The option's action value, or the entered digit sequence."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["menuResult.inputMethod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'dtmf'"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'voice'"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"result-types","__idx":12},"children":["Result types"]},{"$$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":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["return"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Caller selected an option. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," is the option's action value."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequence"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Caller entered multi-digit input. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," is the digit string."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Caller didn't respond in time."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hangup"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Caller hung up during the menu."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalidinput"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Caller pressed a key not mapped to any option."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-return-2","__idx":13},"children":["What you return"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Another SVAML response. You can run another menu, connect the call, say a message, or hang up."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"async pie(context, data) {\n const result = data.menuResult;\n\n if (result?.type === 'timeout' || result?.type === 'hangup') {\n return new PieSvamlBuilder().say('Goodbye!').hangup().build();\n }\n\n switch (result?.value) {\n case 'sales':\n return new PieSvamlBuilder().say('Connecting you to sales.').connectPstn('+15551111111').build();\n case 'support':\n return new PieSvamlBuilder().say('Connecting you to support.').connectPstn('+15552222222').build();\n default:\n return new PieSvamlBuilder().say('Invalid selection. Please try again.').continue().build();\n }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"dice--disconnected-call-event","__idx":14},"children":["DICE — Disconnected Call Event"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fires when the call ends. Informational only — there is nothing to control at this point, so you just log, clean up cached state, bill, or update analytics."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-get-3","__idx":15},"children":["What you get"]},{"$$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":"What it is"},"children":["What it is"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call ID."]}]},{"$$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 in seconds."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Why the call ended — see below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call result — see below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Originating number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to.endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Destination."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reason-values","__idx":16},"children":["Reason values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'N/A'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'TIMEOUT'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'CALLERHANGUP'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'CALLEEHANGUP'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'BLOCKED'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'NOCREDITPARTNER'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'GENERALERROR'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'CANCEL'"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"result-values","__idx":17},"children":["Result values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'N/A'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'ANSWERED'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'BUSY'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'NOANSWER'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'FAILED'"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-return-3","__idx":18},"children":["What you return"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nothing meaningful. Node functions return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["void"]},", C# returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Ok()"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"async dice(context, data) {\n const cli = await context.cache.get(`call:${data.callid}:cli`);\n context.log?.info(`Call from ${cli} ended after ${data.duration}s (${data.result})`);\n await context.cache.delete(`call:${data.callid}:cli`);\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"a-complete-example","__idx":19},"children":["A complete example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A voice IVR that greets the caller, runs a menu, routes them to a department, and logs the call on disconnect."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Node.js\nimport type { VoiceFunction } from '@sinch/functions-runtime';\nimport { IceSvamlBuilder, PieSvamlBuilder, AceSvamlBuilder, MenuTemplates } from '@sinch/functions-runtime';\n\nexport default {\n async ice(context, data) {\n await context.cache.set(`call:${data.callid}:cli`, data.cli ?? 'unknown', 3600);\n return new IceSvamlBuilder()\n .say('Thank you for calling Acme Corp.')\n .runMenu(MenuTemplates.business('Acme Corp'))\n .build();\n },\n\n async pie(context, data) {\n const { type, value } = data.menuResult ?? {};\n if (type === 'timeout' || type === 'hangup') {\n return new PieSvamlBuilder().say('Goodbye!').hangup().build();\n }\n const dest = { sales: '+15551111111', support: '+15552222222' }[value ?? ''];\n return dest\n ? new PieSvamlBuilder().say(`Connecting you to ${value}.`).connectPstn(dest).build()\n : new PieSvamlBuilder().say('Invalid selection.').continue().build();\n },\n\n async ace(context, data) {\n return data.amd?.status === 'machine'\n ? new AceSvamlBuilder().hangup().build()\n : new AceSvamlBuilder().continue().build();\n },\n\n async dice(context, data) {\n const cli = await context.cache.get(`call:${data.callid}:cli`);\n console.log(`Call from ${cli} ended (${data.result}, ${data.duration}s)`);\n await context.cache.delete(`call:${data.callid}:cli`);\n },\n} satisfies VoiceFunction;\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notify-events","__idx":20},"children":["Notify events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Besides the four callbacks above, Sinch also sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notify"]}," events for administrative things (recording notifications, etc.). You handle them the same way — export a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notify"]}," function (Node) or override ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Notify"]}," (C#)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-protection","__idx":21},"children":["Webhook protection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Voice callbacks can be signed by Sinch and validated by your function. Controlled by the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WEBHOOK_PROTECTION"]}," environment variable:"]},{"$$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":"Mode"},"children":["Mode"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Behavior"},"children":["Behavior"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'never'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No validation. Development only."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'deploy'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validate in production, skip in development. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Default."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'always'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always validate."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In C# it is also exposed as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Security:WebhookProtection"]}," in configuration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Legacy alias."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROTECT_VOICE_CALLBACKS"]}," (and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Security:ProtectVoiceCallbacks"]}," in C#) still work as fallback names for compatibility with older functions. Prefer the canonical names above for new code."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related","__idx":22},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#"},"children":["SVAML"]}," — the JSON format voice handlers return"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/functions/reference/svaml-cheatsheet"},"children":["SVAML cheat sheet"]}," — the most-used actions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/voice/api-reference/voice-callbacks/"},"children":["Sinch Voice Callbacks spec"]}," — full field reference on developers.sinch.com"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#"},"children":["Handlers"]}," — how Sinch maps URLs to your handlers"]}]}]},"headings":[{"value":"Voice callbacks","id":"voice-callbacks","depth":1},{"value":"Lifecycle","id":"lifecycle","depth":2},{"value":"Inbound call with a menu","id":"inbound-call-with-a-menu","depth":3},{"value":"Outbound call with AMD","id":"outbound-call-with-amd","depth":3},{"value":"ICE — Incoming Call Event","id":"ice--incoming-call-event","depth":2},{"value":"What you get","id":"what-you-get","depth":3},{"value":"What you return","id":"what-you-return","depth":3},{"value":"ACE — Answered Call Event","id":"ace--answered-call-event","depth":2},{"value":"What you get","id":"what-you-get-1","depth":3},{"value":"What you return","id":"what-you-return-1","depth":3},{"value":"PIE — Prompt Input Event","id":"pie--prompt-input-event","depth":2},{"value":"What you get","id":"what-you-get-2","depth":3},{"value":"Result types","id":"result-types","depth":3},{"value":"What you return","id":"what-you-return-2","depth":3},{"value":"DICE — Disconnected Call Event","id":"dice--disconnected-call-event","depth":2},{"value":"What you get","id":"what-you-get-3","depth":3},{"value":"Reason values","id":"reason-values","depth":3},{"value":"Result values","id":"result-values","depth":3},{"value":"What you return","id":"what-you-return-3","depth":3},{"value":"A complete example","id":"a-complete-example","depth":2},{"value":"Notify events","id":"notify-events","depth":2},{"value":"Webhook protection","id":"webhook-protection","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"seo":{"title":""}},"lastModified":"2026-04-15T14:23:23.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/functions/concepts/voice-callbacks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}