Voice callbacks are HTTP POST requests that the Sinch Voice Platform sends to your function when something happens during a phone call. Your function responds with SVAML commands — say this, connect there, hang up — built with a CommandBuilder (commands() in Node, new CommandBuilder()/the one your handler is primed with in C#).
A voice function has one entry point for all of this: every call.* event for the service named in VOICE_SERVICE_ID is delivered to a single voiceWebhook export (Node) or dispatched through OnCall on SinchVoiceController (C#). onCall (Node) / a set of On*/On*Async virtuals (C#) route each event to the right handler by call lifecycle stage.
Most functions only implement incoming. Add manage if you run menus without a match/onFail on every option, answered if you dial out and need to act once the far end picks up, and completed if you want to log or clean up when a leg ends.
| Handler key | Fires on | The v1 callback it replaces |
|---|---|---|
incoming | call.incoming — an inbound call arrived | ICE |
answered | call.answered — an outbound leg was answered | ACE |
manage | call.menu, and call.webhook.* names not claimed by webhooks | PIE |
completed | call.hangup, call.failed | DICE |
webhooks | call.webhook.<name> for a name registered here | — new in v2 |
fallback | Any event none of the above claims | — new in v2 |
onCall (Node) keys handlers by these lifecycle stages; in C#, SinchVoiceController dispatches by event name to the matching On*/On*Async virtual. Return a command list (or, in C#, a CallFlow — CallFlow.None for "nothing") and the runtime emits the wire body; return nothing (Node) and it answers 204.
Every handler receives the call, flattened, with the event beside it — call.from, call.callId, call.event (and call.menu on a menu) in Node; a typed Call plus the event name and an optional MenuInput as separate parameters in C#:
| Field | What it is |
|---|---|
event | The call.* event name, e.g. call.incoming, call.hangup. |
callId | ULID of this call leg. Use it as a cache key for call state. |
from | Caller endpoint — an object, e.g. { type: 'PHONE', phone: { number: '+1...' } }. |
to | Destination endpoint, same shape as from. |
callResult | Current outcome, e.g. IN_PROGRESS, COMPLETED, BUSY, FAILED. |
callReason | Cause behind callResult, once there is one. |
direction | INBOUND or OUTBOUND. |
menu.menuName | Present on call.menu — the name you gave the menu. |
menu.input | Present on call.menu — the digit sequence the caller entered. |
In Node, call.call (how the call was read before this flatten) still compiles and still returns call itself, but is deprecated — read fields directly off call instead.
A command list built with the builder onCall/OnIncoming primes your handler with. Most common pattern — answer and run a menu:
// Node.js
import { onCall } from '@sinch/functions-runtime/voice';
export const voiceWebhook = onCall({
incoming: (call, builder) =>
builder.answer().menu('main', (menu) =>
menu
.prompt('Welcome. Press 1 for yes, or press 2 for no.')
.repeatPrompt('Please press 1 for yes, or 2 for no.')
.inputTimeout(5)
.repeatCount(2)
.maxLength(1)
.match('1', (c) => c.say('You pressed yes. Thank you, goodbye.').hangup())
.match('2', (c) => c.say('You pressed no. Thank you, goodbye.').hangup())
.onFail((c) => c.say('No input received. Goodbye.').hangup())
),
});// C#
protected override CallFlow OnIncoming(Call call, CommandBuilder builder) =>
builder
.Answer()
.Menu("main", menu => menu
.Prompt("Welcome. Press 1 for yes, press 2 for no.")
.RepeatPrompt("Press 1 for yes, or press 2 for no.")
.InputTimeout(5)
.RepeatCount(2)
.MaxLength(1)
.Match("1", flow => flow.Say("You pressed yes. Thanks for calling. Goodbye.").Hangup())
.Match("2", flow => flow.Say("You pressed no. Thanks for calling. Goodbye.").Hangup())
.OnFail(flow => flow.Say("Sorry, no valid selection. Goodbye.").Hangup()));Because every branch is declared inside the menu (match / onFail), the platform resolves the caller's choice itself — the function only sees call.incoming and call.hangup, nothing in between. manage is the fall-through: a menu that declares neither match() nor onFail() hands its collected digits back as a call.menu event instead.
Fires on call.menu (a menu without a full set of match/onFail branches) and on any call.webhook.<name> event not claimed by webhooks.
manage: (call, builder) => {
if (call.event === 'call.menu' && call.menu?.input === 'sales') {
return builder.say('Connecting you to sales.').dialPhone('+15551111111');
}
return builder.say('Invalid selection. Please try again.').hangup();
},Fires on call.hangup and call.failed. Informational only — there is nothing left to control, so you log, clean up cached state, or update analytics.
completed: (call) => {
console.log(`Call ended: ${call.event}`, call.callId);
},The Simple Voice IVR template, in full — greets the caller, runs a menu that resolves on the platform, and logs the call on disconnect:
// Node.js
import { onCall, say } from '@sinch/functions-runtime/voice';
const companyName = process.env.COMPANY_NAME || 'Your Company';
export const voiceWebhook = onCall({
incoming: (call, builder) =>
builder.answer().menu('main', {
prompt: `Welcome to ${companyName}. Press 1 for yes, or press 2 for no.`,
repeatPrompt: 'Please press 1 for yes, or 2 for no.',
inputTimeout: 5,
repeatCount: 2,
maxLength: 1,
options: {
'1': say('You pressed yes. Thank you, goodbye.').hangup(),
'2': say('You pressed no. Thank you, goodbye.').hangup(),
},
onFail: say('No input received. Goodbye.').hangup(),
}),
manage: (call, builder) => builder.say('Sorry, I did not get that. Goodbye.').hangup(),
completed: (call) => {
console.log(`Call ended: ${call.event}`, call.callId);
},
});A webhook(name, url) command lets you name your own mid-call event: webhook('escalate', url) is delivered as call.webhook.escalate. Register a handler for that name under webhooks — without it, every webhook command in a function funnels into the single manage handler, which then has to re-parse the event string to tell them apart.
Voice callbacks are signed and can be validated by your function.
Voice v2. A v2 function (one with VOICE_SERVICE_ID) signs webhooks with Authorization: service <serviceId>:<HMAC-SHA256> plus an x-timestamp header. sinch functions deploy sets VOICE_SERVICE_SECRET from the function's voice service, and the runtime verifies every call.* webhook with it. When it is unset (local runs, or a deploy that could not read the service) the runtime lets the webhook through with a one-time warning. To run locally against real calls, set it by hand from serviceSecret on GET /v2/projects/{projectId}/services/{serviceId} (that endpoint only, not the list).
Voice v1 (legacy). v1 functions are controlled by the WEBHOOK_PROTECTION environment variable:
| Mode | Behavior |
|---|---|
'never' | No validation. Development only. |
'deploy' | Validate in production, skip in development. Default. |
'always' | Always validate. |
In C# it is also exposed as Security:WebhookProtection in configuration. PROTECT_VOICE_CALLBACKS (and Security:ProtectVoiceCallbacks in C#) still work as a fallback name for older v1 functions.
- SVAML — the command format voice handlers build and return
- SVAML cheat sheet — the most-used commands
- Voice API v2 reference — full field reference on developers.sinch.com
- Handlers — how Sinch maps requests to your handlers



