Skip to content

Voice callbacks

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.

Lifecycle

Inbound call with a menu

Your FunctionSinch Voice PlatformCallerYour FunctionSinch Voice PlatformCallerThe menu resolves the digit on the platform —no round trip when the match is declared in the menu itselfCall in progressDial Sinch number1call.incoming2commands (answer + menu)3Speak prompt4Press DTMF digit5Connect the call6Hang up7call.hangup8(informational, no response needed)9
Your FunctionSinch Voice PlatformCallerYour FunctionSinch Voice PlatformCallerThe menu resolves the digit on the platform —no round trip when the match is declared in the menu itselfCall in progressDial Sinch number1call.incoming2commands (answer + menu)3Speak prompt4Press DTMF digit5Connect the call6Hang up7call.hangup8(informational, no response needed)9

Bridged call with a dialled leg

Your FunctionCalleeSinch Voice PlatformCallerYour FunctionCalleeSinch Voice PlatformCallerBoth legs bridged, call in progressDial Sinch number1call.incoming2answer + bridgeCall + dial(callee)3Ring4Answer5Hang up6call.hangup (for the leg that ended)7
Your FunctionCalleeSinch Voice PlatformCallerYour FunctionCalleeSinch Voice PlatformCallerBoth legs bridged, call in progressDial Sinch number1call.incoming2answer + bridgeCall + dial(callee)3Ring4Answer5Hang up6call.hangup (for the leg that ended)7

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.

Handlers, and the events they receive

Handler keyFires onThe v1 callback it replaces
incomingcall.incoming — an inbound call arrivedICE
answeredcall.answered — an outbound leg was answeredACE
managecall.menu, and call.webhook.* names not claimed by webhooksPIE
completedcall.hangup, call.failedDICE
webhookscall.webhook.<name> for a name registered here— new in v2
fallbackAny 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.

What you get

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#:

FieldWhat it is
eventThe call.* event name, e.g. call.incoming, call.hangup.
callIdULID of this call leg. Use it as a cache key for call state.
fromCaller endpoint — an object, e.g. { type: 'PHONE', phone: { number: '+1...' } }.
toDestination endpoint, same shape as from.
callResultCurrent outcome, e.g. IN_PROGRESS, COMPLETED, BUSY, FAILED.
callReasonCause behind callResult, once there is one.
directionINBOUND or OUTBOUND.
menu.menuNamePresent on call.menu — the name you gave the menu.
menu.inputPresent 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.

What you return

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.

manage — mid-call decisions

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();
},

completed — the call ended

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);
},

A complete example

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);
  },
});

Named webhook commands

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.

Webhook protection

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:

ModeBehavior
'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.