DEV Community: Gunnar Grosch

Build, Operate, and Automate Sinch APIs with the Sinch CLI

Gunnar Grosch — Wed, 30 Sep 2026 08:20:15 +0000

The Sinch CLI (@sinch/cli) puts the Sinch platform in one terminal command: sinch. You can get a phone number, route calls to a Voice API v2 service, build and deploy a Sinch Function, send a message over the Sinch Conversation API, and then script the same steps in CI with --json output and predictable exit codes.

The same commands work for coding agents. Claude Code, Kiro, Cursor, and GitHub Copilot all work through a terminal, so they can run sinch just like you do. They use --help to find commands, --json to read structured output, and exit codes to decide what to do next, without assembling raw API requests. Ask your agent to rent a number and point it at your function, and it can do that with the commands in this post.

This post walks one path from start to finish. You'll get a number, create a Voice service, scaffold a voice function, test it locally, deploy it, and place a call that speaks to you. After that comes messaging, the rest of the products the CLI covers, automation, and how to give your coding agent Sinch-specific skills.

You'll need

Node.js 24 or newer
A Sinch account and a project in the Sinch Build Dashboard
A project ID, access key ID, and access key secret from the project's Access Keys page
A Conversation App with at least one channel configured, for the messaging section

Use a development project for this walkthrough. The steps below repoint a Voice service's webhook, and you don't want that happening to a service that takes real customer calls.

Install and authenticate

npm install -g @sinch/cli
sinch auth login

auth login asks for your project ID, access key ID, and access key secret, then verifies the key pair. That one login covers Numbers, Voice API v2, Functions, the Sinch Conversation API, fax, SIP trunking, and porting.

Credentials go into your OS keychain: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Short-lived session tokens go in ~/.sinch/. Check what's stored:

sinch auth status

Get a phone number

Search for a number with voice capability, rent it, and confirm it's active:

sinch numbers available search --region US --type LOCAL --capabilities SMS VOICE
sinch numbers available rent +12025550134
sinch numbers active list

active list shows each number with its capabilities:

+1 202-555-0134  [US] LOCAL  SMS, VOICE

Some regions need supporting documents, such as proof of address or business identity, before a number can go live. Search results tag those numbers [docs required]. If a rental needs documents the CLI switches to a guided KYC order and runs that region's questionnaire, which it fetches from the API at run time. You can also start an order directly:

sinch numbers order create --region DE --type LOCAL

Create a Voice service

Voice API v2 routes inbound calls through a service. A service holds one setting that matters here: The webhook URL that receives call events. List what your project already has:

sinch voice services list

The list marks one service as the project default. Calls you place with sinch voice calls create run through the default service, so for this walkthrough use that one. If the project has no services yet, create one:

sinch voice services create --name "Support line"

The CLI prints the new service ID, a sinch voice services update command for setting the webhook, and the VOICE_SERVICE_ID=<id> line that routes a function to the service. You don't need to set a webhook yourself: The function steps below do it for you.

Build a voice function

Sinch Functions run your call-handling code on Sinch. The CLI covers the whole loop: Scaffold, test locally, deploy, and watch the logs.

sinch functions init simple-voice-ivr --name my-function
cd my-function

init uses the Node.js runtime for this template (add --runtime csharp for C#) and asks four questions:

Company name. This goes into the voice prompts.
Voice service. This is where the function receives calls. Pick the default service from the previous step.
Auto-configure voice integration on deploy. Say yes. This is what lets deploy point the service at your function.
Database. Pick No database for this example.

Then it installs dependencies and prints the next steps. Run sinch templates list to see the rest of the catalog: IVRs, call bridging, number masking, SMS and RCS responders, and realtime AI voice agents.

Make it speak on an outbound call

The template's voiceWebhook handles inbound calls with an incoming handler that plays a menu. For outbound calls, add an answered handler to the same onCall in function.ts:

export const voiceWebhook = onCall({
  // incoming, manage, and completed from the template stay as they are
  answered: (_call, builder) =>
    builder.say('Your package is arriving today.').hangup(),
});

When a call you place is answered, Voice API v2 sends a call.answered event to the service webhook. The function replies with the commands to run: Say the message, then hang up. That's why calls create has no --say flag. The function decides what happens on the call.

Test it locally

sinch functions dev

dev builds the function, runs it on localhost:3000, and reloads on every save. Send it the event Voice API v2 would send and look at the commands it returns:

curl -X POST http://localhost:3000/ \
  -H 'Content-Type: application/json' \
  -d '{"event":"call.answered","callId":"01TEST","sessionId":"01TEST"}'

{
  "commands": [
    {
      "command": "messages",
      "messages": [
        { "type": "SAY", "say": { "text": "Your package is arriving today.", "voiceName": "Emma" } }
      ],
      "events": {
        "onFinish": [{ "command": "hangup" }],
        "onFailure": [{ "command": "hangup" }]
      }
    }
  ]
}

dev --tunnel goes one step further. It opens a Sinch tunnel and points your Voice service's webhook at your laptop, so real calls reach the local server before you deploy anything. The service keeps pointing at the tunnel after you stop dev, so run deploy afterwards to move it back to the function.

Deploy it

Stop dev with Ctrl+C and deploy:

sinch functions deploy

deploy packages the source, audits the npm dependencies, and rolls it out. Because auto-configuration is on, it also points the Voice service webhook at the deployed function's URL. Check it with sinch voice services list.

Place the call

To see the request before it costs anything, add --dry-run. It prints the exact request body without placing the call:

sinch voice calls create +15551234567 --from +12025550134 --dry-run

{
  "commands": [
    {
      "command": "dial",
      "callName": "origin",
      "from": { "type": "PHONE", "phone": { "number": "+12025550134" } },
      "to": { "type": "PHONE", "phone": { "number": "+15551234567" } }
    }
  ]
}

bridge, hangup, and patch take --dry-run, too. SIP destinations take the scheme, such as sip:agent@pbx.example.com, and the dry run shows how they're sent. Drop the flag to place the call:

sinch voice calls create +15551234567 --from +12025550134

Use your own phone as the destination. --from is the voice-capable number from earlier. Answer and you'll hear "Your package is arriving today."

create prints a session ID, the service that handled the call, and the command to look the call up:

Session ID: 01M3MWAGB1JPKE7VVBVN36BYG1
Service:    YOUR_SERVICE_ID

Inspect with: sinch voice calls list --service-id YOUR_SERVICE_ID

The session ID is not a call ID. To inspect a single call, list the service's calls and use the ULID call ID from that list:

sinch voice calls list --service-id YOUR_SERVICE_ID
sinch voice calls get YOUR_CALL_ID

Call ID                     Dir  Type   From          To            Result     Duration
---------------------------------------------------------------------------------------
01M3MWAGB6HH85Y9GMT8V79D57  out  PHONE  +12025550134  +15551234567  COMPLETED  4s

calls list filters with --call-result, --call-type, --from, --to, --start-time, and --end-time, all optional and combinable. sinch voice calls also has bridge to connect two parties, hangup to end legs of a live call, and patch to add a party to a call that's already up.

Watch the logs

sinch functions logs --follow

--follow streams each request the function handles, with its response and any console.log output. The call you just placed shows up as two events:

Time        Method   Status  Duration    URL
────────────────────────────────────────────────────────────────────────────────
22:47:02  POST    204  1ms        /webhook/voice [call.hangup]
22:46:59  POST    200  1ms        /webhook/voice [call.answered]

For an interactive view where the arrow keys move between requests and Enter expands one, use sinch functions logs --interactive. Filter with --level, --search, or --since.

The rest of the lifecycle: functions list, functions status, functions download to pull the deployed source back down, functions delete, and functions docs to generate a README from the source.

Secrets

Secrets live in your OS keychain and go up with the deployment, so the value never sits in your project. Run this from the function directory:

sinch secrets add CRM_API_KEY YOUR_SECRET_VALUE

The CLI stores the value in the keychain and adds an empty CRM_API_KEY= line to the function's .env. That empty line tells dev and deploy to fill the value in from the keychain. Your code reads it as process.env.CRM_API_KEY, locally and in production.

For a longer build on this same template, Build a Voice IVR with Sinch Functions walks through the menu logic and a live phone call.

Stream call audio or connect the Voice Relay

calls create can also bridge the call to a WebSocket endpoint instead of a function:

sinch voice calls create +15551234567 --stream wss://example.com/audio
sinch voice calls create +15551234567 --relay wss://example.com/relay --tts-voice Emma

--stream sends the raw call audio to your endpoint. --relay connects the Voice Relay, where Sinch runs the speech-to-text and text-to-speech and your endpoint only exchanges text. Both need a public wss:// endpoint. Add --dry-run to see the full command list either one sends. To build on them, start from the voice-relay-agent, voice-relay-echo, or realtime-* templates in sinch templates list.

Send an SMS with the Sinch Conversation API

sinch conversation send +15551234567 "Hello from Sinch" --channel SMS

send goes through your Conversation App and supports eight message types with --type: text, media, template, card, carousel, choice, location, and list. If the app doesn't have the channel you pass, the CLI lists the channels it does have. The rest of the Sinch Conversation API is in the same group: messages, contacts, conversations, apps, webhooks, and templates.

Automate it

Most commands take --json and print a single JSON document with no table and no spinner, so the output pipes straight into jq:

sinch functions list --json | jq -r '.functions[] | select(.status != "Running") | .name'
sinch functions deploy --non-interactive --json | jq -r '.url'

In a pipeline, authenticate with environment variables instead of the keychain. They take precedence over stored credentials:

export SINCH_PROJECT_ID=YOUR_PROJECT_ID
export SINCH_KEY_ID=YOUR_KEY_ID
export SINCH_KEY_SECRET=YOUR_KEY_SECRET
sinch functions deploy --non-interactive

--non-interactive skips every prompt and uses defaults, and setting CI=true has the same effect on deploy. A non-interactive deploy is public unless you pass --private.

Exit codes follow BSD sysexits conventions, plus a Sinch range starting at 100. Two are worth branching on in a script, because retrying won't help with either:

Exit code	Meaning
`0`	Success
`1`	General failure
`100`	Authentication required: No credentials found
`101`	Authentication failed: Credentials were rejected

Profiles let one install work across several projects. Create a profile, switch to it, and log in:

sinch config profile create staging
sinch config profile use staging
sinch auth login

Or leave the active profile alone and pass --profile staging on a single command.

Updates are opt-in. Turn them on with sinch config set autoUpdate true, or check on demand with sinch upgrade. Install shell completions with sinch completion --install.

Use the Sinch CLI with coding agents

Every command in this post works the same when an agent runs it. These are the parts an agent relies on:

--help on every command and group, to discover what exists
--json, to read results as structured data
Exit codes, to tell an auth problem from a failed call
--non-interactive, to run without prompts
--dry-run on call commands, to check a request before it costs anything

To give your assistant Sinch-specific knowledge, install Sinch's developer skills:

sinch skills install

This installs skills from github.com/sinch/skills into your coding assistants. It includes a sinch-cli skill that teaches the commands in this post, plus skills for Functions, Voice API v2, the Sinch Conversation API, Numbers, and the other Sinch APIs. After that you can describe what you need ("place a test call to my phone and show me the call log") and let the agent run the commands.

Troubleshooting

calls get returns 404 for the ID from create. create returns a session ID. calls get takes the ULID call ID from sinch voice calls list --service-id YOUR_SERVICE_ID.
Inbound calls stopped reaching your function after a dev session. The Voice service webhook still points at the tunnel. Run sinch functions deploy, or set it by hand with sinch voice services update YOUR_SERVICE_ID --webhook-url YOUR_FUNCTION_URL. Check where it points with sinch voice services list.
A secret is empty in production. Check that .env has the empty CRM_API_KEY= line and that the key shows up in sinch secrets list, then deploy again. sinch secrets add only writes the .env line when you run it from the function directory.
A SIP destination is rejected. Voice API v2 wants the scheme: sip:agent@pbx.example.com or sips: for TLS. Run the command with --dry-run to see what's sent.
A sinch voice v1 command asks for credentials. v1 uses the Voice application key and secret, not the project access key. Set SINCH_APPLICATION_KEY and SINCH_APPLICATION_SECRET.
A script exits with 100 or 101. 100 means no credentials were found and 101 means they were rejected. Run sinch auth status, or check the SINCH_KEY_ID and SINCH_KEY_SECRET values in your pipeline.

Command reference

Task	Command
Install	`npm install -g @sinch/cli`
Log in	`sinch auth login`
Find a number	`sinch numbers available search --region US --type LOCAL --capabilities VOICE`
Rent a number	`sinch numbers available rent +12025550134`
List your numbers	`sinch numbers active list`
List Voice services	`sinch voice services list`
Create a Voice service	`sinch voice services create --name "Support line"`
Point a service at a URL	`sinch voice services update YOUR_SERVICE_ID --webhook-url YOUR_URL`
Scaffold a function	`sinch functions init simple-voice-ivr --name my-function`
Run locally	`sinch functions dev`
Route real calls to your laptop	`sinch functions dev --tunnel`
Deploy	`sinch functions deploy`
Stream logs	`sinch functions logs --follow`
Add a secret	`sinch secrets add CRM_API_KEY YOUR_SECRET_VALUE`
Place a call	`sinch voice calls create +15551234567 --from +12025550134`
Preview a call request	`sinch voice calls create +15551234567 --dry-run`
List calls	`sinch voice calls list --service-id YOUR_SERVICE_ID`
Send an SMS	`sinch conversation send +15551234567 "Hello" --channel SMS`
Send a fax	`sinch fax send --to +12025550134 --file ./document.pdf`
Check portability	`sinch porting check +12025550134`
Switch projects	`sinch config profile use staging`
Install agent skills	`sinch skills install`

Where to go next

You now have a number, a Voice service, a function that answers and places calls, and the commands to script all of it. Build a Voice IVR with Sinch Functions goes deeper on the function side. An upcoming post builds an AI voice agent on --stream and --relay.

Use the dashboard for configuration you set once. Use the CLI for everything you repeat, debug, or run in a pipeline.

Additional resources

What's the first thing you'd script with the Sinch CLI? Let us know in the comments.

Build a voice IVR with Sinch Functions

Gunnar Grosch — Tue, 29 Sep 2026 07:54:14 +0000

I have built plenty of voice and messaging integrations where a small HTTP service existed for one reason: receive a callback and turn it into the next action. The service was rarely complicated, but it still needed to be deployed, monitored, and kept available.

Sinch Functions runs that callback code on Sinch infrastructure. You write a function, deploy it with the Sinch CLI, and Sinch routes voice and messaging traffic to it. Keep your customer database, order service, and other backend services where they already run. Functions handles the code triggered by communications events.

I use a small Voice API v2 IVR in this post because it makes the event flow easy to test from a phone. The same development and deployment model applies to messaging webhooks and other communications workflows: create the function, run it locally behind a temporary tunnel, test it with curl and live traffic, then deploy it.

You'll need

A Sinch account and a project in the Sinch Build Dashboard
A project ID, access key ID, and access key secret from the project's Access Keys page
Node.js 24 or newer
A Voice API v2 service with a phone number assigned to it. Create one with sinch voice services create and rent a number with sinch numbers available rent, or let the init picker create the service for you.

Renting a number and voice usage are billable; check your project's Billing Overview in the dashboard for current rates. You don't need a number to write and test the handler. The local curl request below returns the commands without placing a call. The phone call at the end is what needs the Voice service and number.

Why Functions fits this job

A simple phone tree usually has a small control loop:

A caller reaches a Sinch phone number.
Voice API v2 sends a call.incoming event to your function.
Your function returns commands to answer the call and start a menu.
The platform plays the prompt, collects the keypress, and runs the commands in the matching branch. Your function is not called again for that step.
When the call ends, Voice API v2 sends call.hangup, and the completed handler logs it.

When a menu declares what to do for every key, the branch runs on the Sinch platform instead of coming back to your code. That's one fewer network hop and one fewer function invocation per keypress, and it's what keeps a small IVR small.

Sinch Functions provides the runtime, routing, logs, local tunnel, and deployment path for that part of the application. Sinch delivers the events to your code inside its own network, and the CLI wires the callback URL for you during local development and deployment. With the private deployment used in this tutorial, there's no public production webhook endpoint to expose and no separate deployment pipeline to maintain.

The distinction matters. A function can call your existing APIs to look up an order or customer, but it shouldn't become a substitute for the system that owns that data. Keep the business system where it belongs and use Functions at the communications boundary.

Install and authenticate the CLI

Install the Sinch CLI globally:

npm install -g @sinch/cli

Authenticate with the project credentials from the Sinch Build Dashboard:

sinch auth login

The CLI prompts for your project ID, access key ID, and access key secret, and stores the secret in your OS credential store rather than in the project directory.

Check the signed-in project:

sinch auth status

Voice functions use this project key pair. When you create one, the CLI lets you select a Voice service and writes its ID to VOICE_SERVICE_ID in .env.

Create the function

Start from the built-in voice IVR template:

sinch functions init simple-voice-ivr --name getting-started-functions

The template uses the Node.js runtime by default. To use C# instead, add --runtime csharp to the command.

The initializer is interactive. Complete these prompts before running another command:

Enter the company name to use in the voice prompts.
Select the dedicated development Voice service from the picker, or enter its service ID manually.
Accept Yes to auto-configure the selected Voice service when you deploy.
Choose No database. The Basic and Pro options provision SQLite storage, which this IVR does not need.

The initializer extracts the template, configures secure credential access from your OS keychain, and installs dependencies. Wait for Function initialized successfully and Dependencies installed successfully, then move into the generated project:

cd getting-started-functions

The template installs its dependencies unless you pass --skip-install.

The files this tutorial touches are:

getting-started-functions/
├── .env
├── function.ts
├── package.json
├── package-lock.json
├── tsconfig.json
├── sinch.json
├── runtime.json
└── test.http

sinch.json contains the function name, runtime, and non-secret variables. .env contains local configuration. Keep .env out of source control. The template also includes AGENTS.md, a README.md, GitHub configuration, and VS Code debugging configuration, which this tutorial does not change.

Write the first handler

The template generates a working IVR. We replace it with a smaller handler and build it back up so each part of the flow is visible.

Open function.ts and replace the template code with this minimal handler:

import { onCall } from '@sinch/functions-runtime/voice';

export const voiceWebhook = onCall({
  incoming: (call, builder) => {
    const from = call.from?.type === 'PHONE' ? call.from.phone.number : undefined;
    console.log('Call received', { from, callId: call.callId });
    return builder.answer().say('Hello! Thanks for calling.').hangup();
  },
});

voiceWebhook is the named export that receives Voice API v2 events. onCall selects a handler based on the event type and gives it a command builder. The local runtime dispatches a call.* event posted to the function root, POST /, to this handler.

For an incoming call, builder.answer() accepts the call, say() turns the text into speech, and hangup() ends it. The fluent builder returns valid Voice API commands without making you assemble the JSON manually.

Run it locally

Start the development server:

sinch functions dev

The server listens on port 3000 and reloads TypeScript changes automatically. The CLI asks whether to enable the Sinch tunnel for external access. Choose Yes: Enable tunnel this time for this walkthrough.

While the tunnel is up, the CLI points the selected Voice service's callback URL at your machine, so real calls to that service reach your laptop. It lives only as long as sinch functions dev is running. Use a development Voice service, not the one carrying customer calls. The CLI warns that real calls route to your machine until you stop the development server with Ctrl+C.

You can verify the handler without renting a number or placing a call:

curl -s -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{
    "event": "call.incoming",
    "call": {
      "callId": "01LOCALTEST0000000000000001",
      "sessionId": "01LOCALTEST0000000000000002",
      "from": {
        "type": "PHONE",
        "phone": { "number": "+15551234567" }
      },
      "to": {
        "type": "PHONE",
        "phone": { "number": "+15559876543" }
      },
      "direction": "INBOUND"
    }
  }'

The response contains the commands the builder produced:

{
  "commands": [
    { "command": "answer" },
    {
      "command": "messages",
      "messages": [
        {
          "type": "SAY",
          "say": { "text": "Hello! Thanks for calling.", "voiceName": "Emma" }
        }
      ],
      "events": {
        "onFinish": [{ "command": "hangup" }],
        "onFailure": [{ "command": "hangup" }]
      }
    }
  ],
  "callName": "caller"
}

The terminal also prints the log line from the handler, which is much easier to inspect than a production webhook log while you are still building the flow:

Call received { from: '+15551234567', callId: '01LOCALTEST0000000000000001' }

Then call the phone number assigned to the Voice service. You should hear the greeting and the call should end.

If port 3000 is already in use, choose another one:

sinch functions dev --port 8080

For breakpoint debugging, use --debug. The CLI detects VS Code, creates or reuses .vscode/launch.json, and prompts you to press F5 to attach the debugger. Set breakpoints in the compiled function.js file, then test the function to hit them:

sinch functions dev --debug

Add a menu

Answering a call is useful as a health check, but an IVR needs to collect an answer. Replace function.ts with the following example:

import { createUniversalConfig } from '@sinch/functions-runtime';
import { onCall } from '@sinch/functions-runtime/voice';

export const voiceWebhook = onCall({
  incoming: (call, builder, context) => {
    const config = createUniversalConfig(context);
    const companyName = config.getVariable('COMPANY_NAME', 'Acme Corp');
    const callerId = config.getVariable('CALLER_ID', '+15550000000');

    return builder.answer().menu('main', (menu) =>
      menu
        .prompt(
          `Thank you for calling ${companyName}. Press 1 for sales, 2 for support, or 0 for an operator.`
        )
        .repeatPrompt('Press 1 for sales, 2 for support, or 0 for an operator.')
        .inputTimeout(8)
        .repeatCount(2)
        .maxLength(1)
        .match('1', (commands) =>
          commands.say('Connecting you to sales now.').dialPhone('+15551110001', { from: callerId })
        )
        .match('2', (commands) =>
          commands.say('Connecting you to support.').dialPhone('+15551110002', { from: callerId })
        )
        .match('0', (commands) =>
          commands.say('Please hold for an operator.').dialPhone('+15551110000', { from: callerId })
        )
        .onFail((commands) =>
          commands.say('Sorry, we did not receive your selection. Goodbye.').hangup()
        )
    );
  },
  completed: (call) => {
    console.log('Call ended', { event: call.event, callId: call.callId });
  },
});

Set the three destination numbers to the numbers each option should reach, and set CALLER_ID to a Sinch number you own or are allowed to present as the caller ID. menu() builds the prompt and handles DTMF, the tones a keypress sends. Each match() branch returns the commands that run when the caller presses that key, and onFail() covers a timeout or an unsupported key, so no caller is left on a silent call.

The completed handler runs after the call ends. It's a good place to record the call ID and outcome, or to notify another system that a call has completed.

The values after each getVariable() name are fallbacks. They keep the example runnable when no configuration has been set, so you do not need to duplicate them in .env for this walkthrough. Define the non-sensitive variables there only when you want to change the greeting or caller ID without editing and redeploying the handler, or when each environment needs different values. Add them to the .env file the initializer created:

COMPANY_NAME=Acme Corp
CALLER_ID=+15550000000

Because every branch has a match() or onFail(), the platform resolves the keypress without calling your function again. Run the earlier call.incoming curl request again to inspect the generated menu safely. Its response contains startMenu: "main", the prompt, and the 0, 1, and 2 match branches, but it doesn't dial the placeholder numbers. Then test it by calling the number: You hear the prompt, press a key, and the matching branch runs.

When a menu needs your code

This is an optional alternative to the platform-resolved menu above. Do not make this change for the IVR you have just built. Use it only when the next step depends on a lookup, such as an order, calendar, or customer record.

To use this pattern, replace the current incoming handler with the one below and add manage to the same onCall() handler map. The menu has no match() or onFail(), so Voice API v2 sends the collected digits to manage in a call.menu event:

incoming: (call, builder) =>
  builder.answer().menu('main', (menu) =>
    menu
      .prompt('Press 1 for sales, or 2 for support.')
      .repeatPrompt('Press 1 for sales, or 2 for support.')
      .inputTimeout(8)
      .repeatCount(2)
      .maxLength(1)
  ),

manage: (call, builder, context) => {
  const config = createUniversalConfig(context);
  const callerId = config.getVariable('CALLER_ID', '+15550000000');

  switch (call.menu?.input) {
    case '1':
      return builder.say('Connecting you to sales.').dialPhone('+15551110001', { from: callerId });
    case '2':
      return builder.say('Connecting you to support.').dialPhone('+15551110002', { from: callerId });
    default:
      return builder.say('Invalid selection.').hangup();
  }
},

Use manage when the branch has to check an order, a calendar, or a customer record before deciding where the call goes. Do not combine this menu with match() or onFail(): those handlers resolve the input on the platform, so manage never runs.

You can test this path without placing a call while sinch functions dev is running:

curl -s -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{
    "event": "call.menu",
    "call": { "callId": "01LOCALTEST0000000000000001" },
    "menu": { "menuName": "main", "input": "1" }
  }'

That request reaches manage with call.menu.input set to 1. Without a manage handler, the event has nowhere to go.

Store secrets safely

Put public configuration, such as COMPANY_NAME, in sinch.json. Sensitive values, such as the API token the operator route uses to look up the caller in your CRM, go in the secret store instead. Store the value outside the repository:

sinch secrets add CRM_API_KEY YOUR_SECRET_VALUE

The CLI adds CRM_API_KEY= to .env for you. Read the value in the handler that needs it:

manage: (call, builder) => {
  const crmApiKey = process.env.CRM_API_KEY;
  if (!crmApiKey) {
    throw new Error('CRM_API_KEY is not configured');
  }

  // look up the caller with crmApiKey before routing
},

The guard makes a missing credential explicit before the function tries to call the CRM. Secrets are redacted in function logs.

Deploy the function

When the local flow works, deploy it:

sinch functions deploy

The CLI validates the function first, then asks whether it should generate or update README.md. Choose Yes: Generate documentation this time for this walkthrough. It performs a dependency audit, packages the function, and prepares its configuration before prompting for a key.

Choose the managed key. It's the default, and the CLI saves the choice in sinch.json, so later deploys do not ask again. Choose the profile key only if you already manage function credentials yourself. The CLI then lists the configuration variables it will ship, marking secrets separately, and asks for the deployment access level. For an IVR that receives only Sinch voice callbacks, choose Private: Internal access only (Sinch services). You can change that default later with --public or --private.

Before uploading, the CLI type-checks and bundles a Node.js function, then validates the package. It uploads the package over HTTPS and waits for the platform build and rollout. The resulting URL is displayed when the function is running.

The CLI updates the callback URL for the Voice service selected during initialization. Call the assigned number again after deployment. You should hear the same menu without the local server or Cloudflare Tunnel running.

Follow the production logs:

sinch functions logs --follow

The log stream shows each request, response, handler logs, and any runtime warnings.

You can also inspect a function's state:

sinch functions status

For integration with an existing operations stack, the Sinch Functions API exposes historical logs, streaming logs, metrics, and cost data. That's the path to use when the CLI's interactive logs are not enough for your production monitoring workflow.

Test the deployed function

Call the number assigned to the Voice service and work through the menu. That verifies the complete production path: number, Voice service, deployed function, and the menu branch. Keep sinch functions logs --follow running in another terminal while you test so you can confirm the incoming event and response.

If you intentionally deployed a public function, you can also repeat the earlier call.incoming curl request with the function URL printed after deployment in place of http://localhost:3000. It verifies the deployed handler without placing a call. Do not change a private IVR to public only to run this test: use the assigned number for the private deployment path.

Troubleshooting

The tunnel does not start: Run sinch functions dev --no-tunnel and post the local test payloads with curl. That confirms the handler works while you sort out the network or firewall blocking the Cloudflare Tunnel.
The test call does not reach your laptop: Confirm that sinch functions dev is still running and that you chose the Voice service assigned to the number you dialed. The tunnel updates that service's callback URL only while the development server is active.
Deployment stops because .env is missing: Run sinch env init, then add any required secrets again with sinch secrets add. The command restores secret names, not their values.

Cleaning up

Delete the function when you are done:

sinch functions delete <function-id>

The CLI displays the function details and asks you to confirm because deletion cannot be undone. Afterward, it removes the function ID from sinch.json; run sinch functions deploy to deploy the project again. sinch functions list prints function IDs if you do not have one handy. Nothing else to clean up locally beyond deleting the project directory.

Where to go next

The IVR is deliberately small, but the same model applies to inbound SMS and Sinch Conversation API webhooks. A function can send messages through the Sinch SDK clients, use the distributed cache for short-lived state, store durable files, or use the built-in replicated SQLite database when the interaction needs persistence.

For voice, the command builder can also dial phone, SIP, stream, relay, and AI-agent destinations. Put the event-specific communications logic in the function, then call the service that owns your business data or workflow.

Additional resources

Originally published on the Sinch blog.

Yells at Cloud, Episode 3: Super Intelligence, Artificial Slowdown

Gunnar Grosch — Mon, 28 Sep 2026 17:29:34 +0000

Listen: YouTube · Spotify · Apple Podcasts

Summary

The AI labs say they want to pace the frontier. About ten days later, they shipped new models and cut prices. Is "slow down" a safety commitment, marketing, or a way to write the rules before regulators do? Chris explains the EU Cyber Resilience Act and its new 24-hour clock for reporting exploited vulnerabilities. Danielle looks at Pizza Bot, AWS' open-source inbox for background agents. And newcomer Ken Collins joins to talk about building AI-native teams when anyone can vibe code something that looks finished.

Burst Mode: Aurora DSQL finally gets foreign key constraints, Jev and Laya make decisions instead of generating text, an S3 bucket from Obama's inauguration day that nobody wants to delete, and AWS confirming permanent customer data loss in Bahrain and the UAE.

Timestamps

Main topics

0:00: Cold open
3:57: Pacing the frontier: is "slow down" just marketing? (Gunnar)
15:00: The EU Cyber Resilience Act starts the clock (Chris)
22:53: Pizza Bot and the harness explosion (Danielle)
28:31: Building AI-native teams (Ken)

Burst Mode

38:58: Burst Mode
39:06: Aurora DSQL foreign key constraints (Danielle)
45:07: Jev, Laya, and decision models (Ken)
51:13: Can AI clean up forgotten cloud resources? (Chris)
55:58: AWS permanently loses customer data in the Middle East (Gunnar)

Hosts

Gunnar Grosch: https://gunnargrosch.com
Danielle Heberling: https://danielleheberling.xyz
Chris Farris: https://chrisfarris.com
Ken Collins: https://metaskills.net

Follow the show

Website: https://yellsatcloudpod.com
YouTube: https://youtube.com/@yellsatcloudpod
Bluesky: https://bsky.app/profile/yellsatcloudpod.com
Twitter / X: https://twitter.com/yellsatcloudpod

Connect AI Agents to Phone Calls with Sinch Voice API v2

Gunnar Grosch — Sat, 26 Sep 2026 12:37:34 +0000

Connecting an AI agent to a live phone call means bridging the phone network and the agent. That can involve SIP integration or a raw media path over a WebSocket, plus speech-to-text, text-to-speech, and managing conversational turns between the caller and the agent. That is a lot of telephony and media infrastructure to build and operate around an AI agent.

Sinch Voice API v2 takes that work off you. Its Voice Relay destination connects a live call to your WebSocket endpoint, Sinch runs speech-to-text and text-to-speech, and your application exchanges plain text. Voice API v2 also adds Voice Streams, a raw bidirectional audio path for the cases where you do want the media yourself.

It's in public preview, so features, limits, documentation, and behavior can still change and no SLA applies, but it's open for testing, evaluation, and early production traffic. I ran the whole path end to end against the tutorial example: a LangChain agent answering a real phone call, interruptions included.

Why Voice Relay matters

An AI agent usually starts as a text application. It accepts a message, calls a model, and returns a text response. Voice Relay moves the audio boundary into the Sinch platform, so you keep the agent, its tools, prompts, and state, and you work with text rather than raw audio. Interruptions come with it, so callers can barge in while a response is playing.

That makes Voice Relay a practical entry point for an AI receptionist, product demo bot, and internal helpdesk.

The Voice API v2 model

Voice API v2 organizes an interaction around three resources:

A session groups related calls and connections and remains active until its associated calls end.
A call represents one participant's connection, such as a phone, SIP, or streaming leg.
A bridge connects calls within a session when multiple participants need to communicate.

SVAML, the Sinch Voice API Markup Language, describes what happens during the interaction. A dial command can create a call leg. Nested events can define what happens when the call is answered, is busy, times out, or fails. A webhook can take over when the application needs to make a dynamic decision.

This model matters for AI agents because the conversation and the call are related, but they aren't the same thing. The AI agent manages the conversation. SVAML and the Voice API manage the call flow. That separation lets you add a human transfer, another call leg, or a different media path without putting all of that logic inside the model prompt.

You'll need

A Sinch account with Voice API v2 access, at the Sinch Build Dashboard
A Sinch project ID, access key ID, and access key secret
An activated Sinch virtual number
A Voice API v2 service ID, from Voice > Programmable Voice > Services in the dashboard
Python 3.10 or newer
An API key for OpenAI, Anthropic Claude, or Google Gemini
ngrok with a registered authtoken, or another way to expose a local server over wss://

The walkthrough uses the sinch-voice-tutorials repository. Its 4.1-voice-relay tutorial is a Python WebSocket server backed by LangChain, which reads its configuration from environment variables and supports OpenAI, Anthropic Claude, and Google Gemini.

Connect an agent with Voice Relay

Clone the tutorials repository and move into the Voice Relay example:

git clone https://github.com/sinch/sinch-voice-tutorials.git
cd sinch-voice-tutorials/4.1-voice-relay

Create an environment and install the example's dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

The commands here are for macOS and Linux. On Windows, use python in place of python3 and activate with .venv\Scripts\activate.

Copy the example configuration:

cp .env.example .env

Set a provider and its API key in .env:

PROVIDER=openai
API_KEY=YOUR_LLM_API_KEY

The repository's .env.example uses openai as its default provider. The example also supports claude for Anthropic Claude and gemini for Google Gemini, and requirements.txt installs the packages for all three, so switching provider means changing PROVIDER and API_KEY. You can also set MODEL, TEMPERATURE, MAX_TOKENS, and PORT, whose defaults show up in the startup log below, plus GREETING to change the Hello! the agent opens with.

Start the local server:

python server.py

The server reports the system prompt it loaded, then its provider and model settings, then the local address it is listening on:

[*] Loaded system prompt (3424 chars)
[*] Provider: openai  Model: gpt-4o  Temp: 0.7  MaxTokens: 1024
[*] Agent Relay listening on ws://0.0.0.0:8765

Check that output before you make a call. A missing provider key or a broken dependency shows up here rather than halfway through a conversation.

The agent's behavior comes from system_prompt.md. Edit that file to change the persona, domain, or instructions, then restart server.py because the prompt is loaded at startup.

Sinch connects inward to your relay server, so it needs a public address. Leave server.py running in the first terminal and open a second one. If you don't already have ngrok, install it and register an authtoken from the Your Authtoken page in the ngrok dashboard. The free tier covers this walkthrough, and ngrok refuses to start a tunnel until a token is configured:

brew install ngrok
ngrok config add-authtoken YOUR_NGROK_AUTHTOKEN
ngrok http 8765

ngrok takes over the terminal and prints a status table. The line that matters is the forwarding address:

Forwarding    https://YOUR_NGROK_ID.ngrok-free.dev -> http://localhost:8765

Take that address, change only the scheme to wss://, and use it as the Voice Relay endpoint:

ngrok address:  https://YOUR_NGROK_ID.ngrok-free.dev
Sinch endpoint: wss://YOUR_NGROK_ID.ngrok-free.dev

That wss:// value goes in the Sinch service configuration, not in the relay server, which stays on local port 8765. Leave both server.py and ngrok running from here on.

The minimal Voice Relay destination looks like this:

{
  "type": "VOICE_RELAY",
  "voiceRelay": {
    "endpoint": "wss://YOUR_NGROK_ID.ngrok-free.dev",
    "ttsVoice": "Tiffany",
    "sttLanguage": "en-US"
  }
}

Field	Required	Notes
`endpoint`	Yes	The `wss://` address Sinch connects to
`ttsVoice`	Yes	`Tiffany` matches this tutorial. See the supported voices reference before changing it
`sttLanguage`	Yes	A BCP-47 language tag
`enableInterruptions`	No	Defaults to `true`
`callHeaders`	No	Up to 16 key/value pairs, each key and value 255 characters or fewer

Your service needs the number before any of this matters. In the dashboard, open the service, go to Voice channels, and choose Configure on the Phone row, then Add numbers and pick your virtual number. A number belongs to one service at a time, so if it already sits with another service the dashboard asks you to confirm the reassignment, and incoming calls to that number follow the new service from then on.

With the number in place, route the call by giving the service a static call behavior or a webhook that returns SVAML. The static configuration does five things:

Answer the incoming call.
Add the inbound leg to main-bridge.
Create a call leg with a VOICE_RELAY destination.
Add the relay leg to the same main-bridge when it answers.
Hang up the relay leg when the inbound leg ends.

server.py and ngrok are both holding their terminals now, so open a third one for this step. Fill in the five values at the top of the request and run it. If you'd rather use the dashboard, paste the inner SVAML body from static.txt into its predefined call behavior editor instead.

export PROJECT_ID=YOUR_PROJECT_ID
export KEY_ID=YOUR_ACCESS_KEY_ID
export SERVICE_ID=YOUR_SERVICE_ID
export VOICE_RELAY_ENDPOINT=wss://YOUR_NGROK_ID.ngrok-free.dev

# prompts without echoing, so the secret stays out of shell history
printf 'Access key secret: '
read -rs KEY_SECRET
echo
export KEY_SECRET

curl -X PATCH \
  -u "$KEY_ID:$KEY_SECRET" \
  "https://voice.api.sinch.com/v2/projects/$PROJECT_ID/services/$SERVICE_ID" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{
  "callBehavior": {
    "type": "STATIC",
    "static": {
      "callName": "caller",
      "commands": [
        { "command": "answer" },
        { "command": "bridgeCall", "bridgeName": "main-bridge" },
        {
          "command": "dial",
          "callName": "voice_relay_call",
          "to": {
            "type": "VOICE_RELAY",
            "voiceRelay": {
              "endpoint": "$VOICE_RELAY_ENDPOINT",
              "ttsVoice": "Tiffany",
              "sttLanguage": "en-US"
            }
          },
          "events": {
            "onAnswer": [
              { "command": "bridgeCall", "bridgeName": "main-bridge" }
            ]
          }
        }
      ],
      "events": {
        "onHangup": [
          { "command": "hangup", "callName": "voice_relay_call" }
        ]
      }
    }
  }
}
JSON

A successful PATCH returns the updated service, so you can read your endpoint back out of the response and confirm it took:

{
  "serviceId": "YOUR_SERVICE_ID",
  "projectId": "YOUR_PROJECT_ID",
  "name": "voice-relay-test",
  "isDefault": true,
  "callBehavior": {
    "type": "STATIC",
    "static": {
      "callName": "caller",
      "commands": [
        { "command": "answer" },
        { "command": "bridgeCall", "bridgeName": "main-bridge" },
        {
          "command": "dial",
          "to": {
            "type": "VOICE_RELAY",
            "voiceRelay": {
              "endpoint": "wss://YOUR_NGROK_ID.ngrok-free.dev",
              "ttsVoice": "Tiffany",
              "sttLanguage": "en-US"
            }
          },
          "events": {
            "onAnswer": [
              { "command": "bridgeCall", "bridgeName": "main-bridge" }
            ]
          },
          "callName": "voice_relay_call"
        }
      ],
      "events": {
        "onHangup": [
          { "command": "hangup", "callName": "voice_relay_call" }
        ]
      }
    }
  }
}

The inner SVAML body is also available in static.txt.

What success looks like

Call the Sinch number associated with the service. You should hear Hello!, or the greeting you set with GREETING. Then speak a question and listen for the agent's response.

The server terminal logs both directions of the WebSocket, and that log is the most useful thing on screen during a first call. Mine looked like this, trimmed to one exchange:

[+] Connected: ('127.0.0.1', 65438)
  WS << {"callHeaders":{},"callId":"01M25YACD3G61GH4Y0NQNWR4WD","interruptionsEnabled":true,...}
    connect  callId=01M25YACD3G61GH4Y0NQNWR4WD  serviceId=YOUR_SERVICE_ID
  WS >> {"command": "answer"}
  WS >> {"command": "text", "text": "Hello!", "isLast": true, "isInterruptible": true}
  WS << {"batchSequence":0,"command":"textPlaybackStart"}
  WS << {"batchSequence":0,"command":"textPlaybackStop"}
  WS << {"reason":"speech-detected","command":"interrupt"}
  WS << {"sttLanguage":"en-US","text":"Hi.","isCorrection":false,"command":"text"}
    STT → 'Hi.'
    LLM ← 'Hey there! How can I assist you today? If it involves voice tech or a good dad j'…
  WS >> {"command": "text", "text": "Hey there! How can I assist you today?...", "isLast": true}
  WS << {"batchSequence":1,"command":"textPlaybackStart"}
  WS << {"batchSequence":1,"command":"textPlaybackStop"}
[-] Connection closed (1006):
[-] Session ended  callId=01M25YACD3G61GH4Y0NQNWR4WD

Two things in that log are worth knowing before your first call. The connect message carries interruptionsEnabled: true, which is where you can confirm the interruption default rather than taking it from the configuration reference. And the connection closes with code 1006 when the caller hangs up, which reads as an abnormal closure but is what a normal hangup looks like here.

An interrupt with reason=speech-detected appears on every turn, because Sinch sends one whenever it hears the caller. Its position is what tells you something: after textPlaybackStop it just marks the start of the caller's turn, while between textPlaybackStart and textPlaybackStop it is a barge-in. When I talked over a response, playback stopped and the next transcript was what I had said over the top:

  WS << {"batchSequence":5,"command":"textPlaybackStart"}
  WS << {"reason":"speech-detected","command":"interrupt"}
  WS << {"batchSequence":5,"command":"textPlaybackStop"}
  WS << {"sttLanguage":"en-US","text":"I'm going to stop you right there.",...,"command":"text"}

That's a voice interface in front of a text-based AI agent, without handling a single audio frame yourself.

Where your application sits

Sinch and the WebSocket server exchange a small JSON protocol, one command per message, and server.py handles it for you. Transcript corrections are the part worth understanding before you build on the example.

Sinch sends an early transcript, then may send a corrected one for the same utterance with isCorrection: true, and the corrected text includes the earlier text rather than replacing only the changed part. It happened once in three calls: Thank you. was followed by Thank you.\nOh, that's nice., and both went to the model, so the agent answered the same utterance twice. Decide whether you wait for a correction, cancel the in-flight request, or ignore corrections entirely.

The application boundary looks like this:

Caller speech
    |
Sinch speech-to-text
    |
Voice Relay text message
    |
AI agent
    |
Voice Relay text response
    |
Sinch text-to-speech
    |
Caller hears the response

Voice Relay or raw audio streaming?

Choose	When
Voice Relay	Your agent accepts text and returns text, and Sinch handles STT and TTS.
Voice Streams	You need raw audio and own the STT/TTS pipeline.

Voice Streams suits a custom speech pipeline, a specialized audio processor, or a provider whose protocol requires direct audio access. It also means you own more of the latency and failure behavior.

Production considerations

Voice interactions make latency visible. A slow model response creates silence for the caller, so measure the time from the incoming speech event to the first response and to the completed response. Use a model and prompt that fit a phone conversation rather than optimizing only for maximum answer quality.

The repository example waits for the full model response before sending anything back, so the caller hears nothing until the model has finished generating. That is the first place to look if the pauses feel long.

The example also keeps conversation history in memory for each WebSocket connection. That's fine for a first test, but it isn't a durable conversation store. Decide what state belongs to a call, what belongs to a customer, and what has to survive a reconnect.

Interruptions need explicit handling. If the caller speaks while a response is playing, you can receive an interruption event while an LLM request is still running. Cancel the request where you can, or tag each response with a turn ID and discard stale output before sending it back to Sinch. The same turn ID handles corrected transcripts, which arrive as a second text message for an utterance you have already sent to the model.

The local example also needs stronger failure handling before production use:

Send a short fallback response when the model provider fails.
Persist conversation state when the call needs to survive a process restart.
Keep the WebSocket endpoint available for the full call lifetime.
Log call, session, connection, and model timing identifiers without logging sensitive conversation content unnecessarily.
Use OAuth 2.0 client credentials for production API access. Basic authentication is useful for initial testing.

Troubleshooting

Check the provider configuration before you make a call. A bad or missing LLM key shows up as a silent call rather than an error, because the model isn't called until the first turn, so confirm that PROVIDER and API_KEY match each other in .env.

The free ngrok URL changes when the tunnel restarts. Update the endpoint in the Voice API v2 service configuration whenever that happens, or Sinch can't reach the current server. server.py doesn't need restarting for this.

Preview status

The preview terms allow testing, evaluation, early commercial use, and live traffic, and state that the platform is designed to support production-level volumes. The service is provided as is and as available, usage limits may apply, and no SLA applies. Sinch may add functionality, and breaking changes cannot be ruled out before general availability.

What's next

Voice Relay is one path into Voice API v2. The same platform model also supports:

Outbound voice alerts with text-to-speech
Answering machine detection
Batch calling with call pacing
Call recording and transcription
Number masking
SIP connections
Raw audio streaming
Live call control through SVAML and webhooks

The Sinch Voice API v2 tutorials repository has working examples for these paths. Start with the 4.1-voice-relay tutorial for a text-based agent, then move to 4.2-stream-audio when you need direct access to the audio stream.

Voice API v2 gives an existing text agent a route into a live voice interaction without turning that agent into an audio-processing system. Clone 4.1-voice-relay, point system_prompt.md at your own agent's prompt, and call the number.

Additional Resources

What would you connect to a voice agent first: customer support, an internal helpdesk, or a product demo? Share the use case you would test on Voice API v2.

Originally published on the Sinch blog.

Building Bivack: A Cloud Dev Sandbox for Coding Agents on AWS Lambda MicroVMs

Gunnar Grosch — Mon, 21 Sep 2026 10:45:25 +0000

I released a new version of Bivack this morning, and I built it from a car, a bus, an airport and a flight to Amsterdam. Laptop when there was a table, phone when there was not. The agent doing the work never moved: it sat on a MicroVM in us-east-1 the whole time, with my home directory in Amazon S3 where I had left it the night before.

That is the whole premise. Most of what I have written about agentic coding assumes the agent runs on your machine. Claude Code with Amazon Bedrock, hooks, MCP servers, plugins: all of it assumes a terminal on your laptop and a project on your local disk. That setup is excellent until you want to close the laptop, hand a task to an agent and walk away, or pick the work back up from a phone in a departure hall.

Bivack gives each person their own AWS Lambda MicroVM, with their coding agents on it and a persistent home on Amazon S3 Files, reached from a browser: a terminal or a full VS Code workbench. One machine per user, not one per agent, so the agents you selected all sit on the same box and share the same files. The name is a nod to a bivouac, a shelter you set up where you need it. One limit up front: the home is network storage, so it is slower than a local disk. This post covers how it works, the decisions that shaped it, and the parts that are harder than they look.

On the trip, I started work in the browser on my phone, then picked up the exact same session on my laptop when I had a table. The terminal made the phone leg workable; on the laptop, the workbench let me inspect the files and changes the agent had made rather than reconnecting only to a shell. I moved back and forth between the two several times before I shipped the release. There was no handoff to manage or context to recreate: the agent, the terminal and the files stayed put on the MicroVM while I changed devices.

Why the agent needs its own machine

The friction with a laptop-bound agent is mostly the laptop. The session is tied to that one machine, the provider logins live on it, and a long task means keeping the terminal open and the machine awake. You also cannot hand the same environment to a teammate without them repeating your setup.

What I wanted was narrow and specific:

One disposable machine per person, isolated from everyone else.
A home directory that survives restarts, so files and logins are still there next week.
Reachable from a browser, including from a phone or an iPad, without installing anything.
Each person brings their own provider login, rather than a shared key in the image.
A real editor, not just a terminal. I want to read and change what the agent wrote.

That last one is why the workbench exists. Handing a task to an agent and reading a summary of what it did is not how I work. I want to open the diff, disagree with a function name, move a file, run the tests myself and then hand it back. A terminal covers the agent side of that fine, and it is thin for the rest: reviewing a multi-file change through a CLI pager on a phone is not reviewing. So the editor is not a nicety bolted onto the terminal, it is half the point, and both halves had to be the same machine for it to mean anything.

AWS Lambda MicroVMs matched those requirements closely. A Firecracker snapshot boots in a fraction of a second, each MicroVM is isolated, and you are billed while one is running. For an interactive sandbox that should feel instant and cost nothing while idle, that is the right primitive.

What using it is like

Sign in, pick a workspace, and you are in. The terminal and the editor are the same machine, so they share one home, one set of files and one set of logins. Because it is one machine, you can run an agent in a terminal pane and a second one beside it, both working the same repo. Bringing work in is the usual git clone; git and gh are already installed.

The numbers behind the walk-away part: a VM suspends after two hours with no inbound traffic, stays resumable for another thirty minutes, and no single VM lives longer than eight hours. So you have roughly two and a half hours of not touching it before the session is gone, and the running agent process goes with it. The home survives either way, which is the part that matters: files, shell history and every login are still there on the next sign-in. All three timers are deploy.env settings (IDLE_MAX_SECONDS, IDLE_SUSPEND_SECONDS, MAX_LIFETIME_SECONDS), so a longer leash costs awake time and nothing else. A travel day fits inside the defaults, which is how I picked them.

The chooser

The entry point: two buttons, one for the terminal and one for the editor.

The terminal

An xterm.js terminal that installs as a PWA and adds a touch key row on devices without a keyboard. It is where the agent CLIs run, each signed in with that person's own account. This is the half I used from a phone, and the touch key row is the reason it was usable at all.

The workbench

The workbench is the real browser build of VS Code, backed by the same home and the same authenticated WebSocket mechanism. Same files, same logins, same machine as the terminal, so an agent can be working in one tab while I read its output in the other. Click a file path in its terminal and the file opens in the editor.

Why not a hosted agent or a VPS

Two alternatives are worth naming. The hosted agents (Claude Code and Codex in the cloud, plus background agents from Cursor, Copilot and Devin) are less work: point one at a repo and it runs on the vendor's infrastructure with the vendor's model, usually per seat, with your code in their accounts. What you give up is the environment. A small VPS running tmux and code-server is the other shape, and it costs about five dollars a month, but everyone shares one host and one kernel, you keep the box running, and the home dies with the box. Isolation, fast starts and a home that outlives the machine are exactly what Lambda MicroVMs and S3 Files are for.

The starting point was Remote Developer (rDev) by Eric Johnson, which proved the core idea: per-user AWS Lambda MicroVMs behind Cognito, a browser terminal over a WebSocket, and a per-user S3 Files home mounted by a lifecycle hook. Bivack keeps that foundation and takes it somewhere else. rDev's sandbox carried credentials for Amazon Bedrock and the AWS account hosting it; Bivack removes that hosting-account access. The browser VS Code workbench is new, as is the chooser and login frontend around it, the configurable MicroVM image, the one-command deploy and teardown, the NAT modes, the budget wiring, and the break-glass tooling. The attribution is in NOTICE, and it is genuine: the template shape, the image bones, the lifecycle hooks and the WebSocket terminal all trace back to Eric's work.

The constraint that shapes everything

One constraint drives most of the design, so the request path is the place to start.

Browser
  |-- HTTPS ------> CloudFront (static frontend)
  |-- sign in ----> Cognito
  |-- GET /token -> API Gateway -> token Lambda function
  |                                   |-- find or create this user's access point
  |                                   '-- launch or resume the MicroVM
  |                                       -> { authToken, endpoint }
  '-- wss:// -----> MicroVM agent (file system, PTY)
                         '-- mount /home/coder (the /run lifecycle hook)
                                 -> S3 Files access point for this user

Cognito holds the users, and they are admin-created: adding a teammate means creating their login by hand, and each one gets their own access point and MicroVM. API Gateway validates the JWT before the Lambda function runs, so the function only ever sees a verified sub. That sub maps to one S3 Files access point rooted at /users/<sub> and one MicroVM. On the first request it creates the access point, launches a MicroVM, and returns a short-lived token and the endpoint. The MicroVM mounts its own home during the /run lifecycle hook, so the mount is per-user and the image stays shared.

Here is the constraint. A Lambda MicroVM endpoint accepts the auth token only in the X-aws-proxy-auth header. A browser can set that header on a fetch or a WebSocket handshake, but it cannot set a header on a page navigation, or on any of the subresource loads a page makes after it. So you cannot run a web IDE inside the MicroVM and point the browser at it. Not with a redirect, not with a cookie, not with a query string.

That single fact decides the shape of the entire frontend. The terminal is an xterm.js client rather than a served page. The IDE is a self-hosted workbench that talks to the VM over a WebSocket rather than an editor served from the VM. Both run over wss://, and the endpoint is useless without the short-lived token. Every design decision downstream of the ingress follows from a header a browser is not allowed to set.

What goes in the image

The sandbox is not a machine you install things on. It is an image you declare, and deploy.env is where you declare it:

CLAUDE=latest           # install the current release
# OPENCODE=latest       # commented out disables it
KIRO=                   # empty also disables it
TOFU=1.12.6             # install this pinned release

Four coding agents are available (CLAUDE, CODEX, OPENCODE, KIRO) and four infrastructure CLIs (CDK, SAM, TOFU, TERRAFORM). Claude Code is the only one enabled in the generated deploy.env; the rest are opt-in, because every tool is weight in an image that every user boots. Setting a tool to latest takes its current release and a version string pins it. Kiro CLI is latest only, and pinning OpenTofu and Terraform is worth doing if you want the same image twice.

Changing any of those settings changes the packaged MicroVM source hash, so the next ./scripts/deploy.sh rebuilds the image on its own. The trade-off is worth stating plainly: adding a tool is a five to ten minute image build and a VM recycle, not npm install -g. In exchange, nobody hand-installs anything into a sandbox that gets thrown away, and every user gets the same machine.

Each selected CLI signs in once and keeps its session under /home/coder:

CLI	Command	First-run login
Claude Code	`claude`	sign in with your Claude plan
Codex	`codex`	sign in with your OpenAI account
OpenCode	`opencode`	`/connect` to add a provider
Kiro CLI	`kiro-cli`	`kiro-cli login` (device flow)

They share workspace files while keeping their own configuration and history, and each is configured for unattended work: Claude Code uses bypassPermissions, Codex bypasses approvals and its local sandbox, and Kiro CLI carries a persistent allow-all policy. The MicroVM is the isolation boundary, which is the only reason that is a reasonable default.

A few things I learned building this

Put the home on S3 Files, not a disk

The home has to outlive the machine. MicroVMs suspend when idle and terminate after a maximum lifetime, so anything stored only on the VM's local disk is gone when it recycles. I considered EBS, EFS and S3 Files. EBS is tied to one instance and one Availability Zone, which fights the recycle-and-come-back model. EFS would work, and its access points can root at a directory with an enforced UID and GID, so isolation is not the hard part. What made S3 Files the better fit is that the home is the same bytes as an S3 prefix: an access point rooted at /users/<sub> is all that user can see, and everything they write is also readable as ordinary objects in the bucket with the tools I already have.

The trade-off: file operations go over NFS to a network-backed filesystem, so metadata-heavy work is slower than local disk. You notice it when a CLI scans its config or a large cache. It is the right call for durability, and it is not free.

Versioning comes with S3 Files, and so does the bill

S3 Files requires versioning on the bucket (prerequisites). That is fine until you realize how much a home directory churns: package caches, session history, plugin state, logs. Every write becomes a new object version and every delete becomes a delete marker, so the bucket grows even when it looks empty. A lifecycle rule that expires noncurrent versions after a week, drops expired delete markers and aborts stalled multipart uploads keeps the growth bounded. Without it you are paying to store every intermediate state of a file nobody will look at again.

The web workbench is its own project

I expected the IDE to be configuration on top of an existing package. It is closer to building an application. The FileSystemProvider and the terminal backend both run over the same authenticated WebSocket to a small agent in the VM. There is no local file system to read, and the ingress constraint rules out serving the editor from the VM, so the workbench stays a client-side app that talks to the agent. The provider turns that socket into stat, readDirectory, readFile, writeFile, createDirectory, delete, rename and a recursive watch, and the agent pushes change events back so the workbench sees an external edit. Making VS Code treat a remote-over-socket tree as a normal workspace, with all of that, takes more wiring than the documentation suggests.

One thing that surprised me: a browser workbench keeps its user settings in the browser, in IndexedDB, not on the machine it is editing. Workspace settings (.vscode/settings.json) live in the VM, but the global ones do not follow you between browsers. And if you set defaults by writing the user settings file, you only ever apply them once, because the file already exists on the next load. Registering configuration defaults instead lets people override the ones they care about and have it stick.

No AWS credentials in the sandbox, on purpose

Two sets of AWS accounts are in play here, and they are separate. One hosts the stack: the MicroVMs, the bucket, the API. The others are whatever accounts you use for your own work. The sandbox gets no credentials for the hosting account. Its execution role can mount S3 Files and look up its own endpoint, and nothing more. When you need AWS inside the VM, you bring your own account in.

The profiles and token cache live in ~/.aws in the home, so you set them up once rather than once per VM.

rDev took a different path: its MicroVM execution role gives the sandbox Amazon Bedrock access and broad, boundary-limited permissions in the AWS account that runs the stack. You can still add your own provider login there. I moved away from giving the sandbox hosting-account credentials at all: that avoids coupling it to one provider and keeps a compromised agent out of the account that runs everything.

The reach of a compromised agent is the sandbox and everything signed into it. Provider logins persist in the home, so a malicious file that the agent reads can reach ~/.claude, ~/.codex, ~/.kiro, the gh config, an aws sso cache and git credentials. The agent cannot touch the AWS account the stack runs in, which is the line I care about, and it can touch every other account the person signed into inside the sandbox. That is the boundary.

On a shared deployment there is one more reader to account for: the home lives in the bucket owned by whoever operates the stack, so the operator can read every teammate's provider logins. On a personal deployment that is the same person. On a company deployment, it is a decision to make on purpose.

Egress has two prices

Each MicroVM reaches model providers and package registries through the private subnets, so those subnets need a way out to the internet. The default is a small NAT instance running masquerade: a t4g.nano at a few dollars a month, patched weekly by an SSM association. Set NAT_MODE=gateway and it becomes a managed NAT Gateway at roughly ten times the monthly cost, with the patching handled for you. For a small team the instance is the sensible default; pick the gateway if you would rather not own the patch.

Getting started

You will need:

AWS CLI v2, authenticated. 2.35.10 or newer, which is the release that added aws lambda-microvms.
AWS SAM CLI 1.163.0 or newer, the first release whose transform expands AWS::Serverless::MicrovmImage.
Node.js 20 and npm
zip and python3 (packaging and small helpers in the scripts)
A region where AWS Lambda MicroVMs are available (the examples use us-east-1)

Docker is not required. The MicroVM image is built server-side by the Lambda MicroVMs build service. The deploy checks the AWS CLI for MicroVM support before it applies a stack update, because an older CLI is the first thing most people hit.

git clone https://github.com/gunnargrosch/bivack
cd bivack
cp deploy.env.example deploy.env
$EDITOR deploy.env
./scripts/deploy.sh

deploy.env starts with three values:

AWS_PROFILE=your-profile
AWS_REGION=us-east-1
LOGIN_EMAIL=you@example.com

Everything else is optional: the tool settings above, the stack name (STACK_NAME), the memory tier (MEMORY_MIB), the three timers, the first login's temporary password (INITIAL_PASSWORD, random if unset), egress (NAT_MODE), and the budget (BUDGET_EMAIL, BUDGET_USD).

The first run bootstraps the stack, builds the IDE, packages the MicroVM image, uploads the frontend, creates your first login, and smoke-tests a throwaway MicroVM. The image build alone is 5 to 10 minutes, so the first deploy is not a quick one.

FrontendUrl: https://<id>.cloudfront.net
Login:       you@example.com

First sign-in: open the URL, sign in with the temporary password below, and
set a new password when prompted.

  Temporary password: <printed once>

Set BUDGET_EMAIL and the stack also creates a monthly AWS Budget, $25 unless you change BUDGET_USD, that emails that address at 80% and 100%. Leave it unset and no budget is created. It is worth setting: a sandbox left running shows up as an alert rather than a surprise. Cost tracks awake time and storage rather than seats, since the MicroVM bills only while it is running and a suspended VM costs nothing but the home's storage.

Sign in, pick the terminal or the editor, and the CLIs sign in with your own accounts. The first launch of claude on a brand-new VM does its first-run work, so it is slower than every launch after it. The image build runs a /validate hook that exercises that startup path so the platform prefetches it, which brings the cold start back down.

To use AWS from inside the VM, run aws configure sso once to create a session and profile, then sign in by naming one of them:

aws sso login --profile management --use-device-code
# or log the whole session in
aws sso login --sso-session my-org --use-device-code

A bare aws sso login resolves the default profile, which usually has no SSO keys. --use-device-code is required because the default Authorization Code flow redirects to the VM's own 127.0.0.1, which your browser cannot reach. The device-code flow instead prints a URL and code that work from any device.

There is no SSH into a MicroVM. For break-glass access, tools/exec.js opens a shell on a running VM and tools/run-remote.js runs a single command against it. To remove everything the stack created, run ./scripts/teardown.sh: it deletes the stack, the buckets including their object versions, the Cognito user pool, the SSM parameters, running MicroVMs, the MicroVM images and the log groups.

Upgrading

git pull
./scripts/deploy.sh

deploy.sh rebuilds only what changed: the IDE when its sources moved, the MicroVM image when microvm/ or a tool setting moved, the frontend when its assets or generated config moved. A no-change run skips frontend publishing, the CloudFront invalidation and the artifact upload. The buckets and the S3 Files home are never touched, so files, history and logins survive an upgrade. Running VMs keep the old image until they recycle; hit the terminal's power button to move onto a new one immediately.

Two flags are worth knowing before a stack update. --dry-run creates a CloudFormation changeset without executing it, and --review prints the changeset and waits for you to confirm. What you are looking for there is Replace on UserPool, WorkspaceBucket or S3FilesFileSystem, because a replacement on any of those drops users or data. The one time you want it is bumping S3FilesFileSystem's ClientToken, which is the recovery path for a wedged synchronization state. The rest of the flags are smaller: --frontend-only re-uploads the frontend and IDE with no SAM deploy and no image, --no-smoke skips the throwaway test VM, and --build-ide forces an IDE rebuild.

What it does not do

The IDE is the browser build of VS Code, so only extensions with a web entrypoint install, and Microsoft and GitHub sign-in and Settings Sync are unavailable because they are Microsoft-hosted built-ins. Source Control has no provider at all: the browser cannot spawn the git binary and monaco-vscode-api does not ship VS Code's git extension, so git and gh in the terminal are the answer. IDE user settings are per-browser, and auto-save starts off with tooling dotfiles hidden behind files.exclude, both overridable defaults.

The home is network storage, so it is slower than a local disk. Inside the VM, coder has passwordless sudo and the workload has open outbound internet, so the MicroVM is the isolation boundary rather than a hardened jail. Model-provider spend is billed to each user's own provider account with no sandbox-level cap. The stack targets one region.

There is no built-in preview for a dev server. The ingress accepts the auth token only in a header, so there is no port-forward from the browser to a port inside the VM; if you need one, run your own tunnel from inside the VM. The VM memory is a fixed tier (MEMORY_MIB, 4 GB by default, bursting to 4x), and that tier is the ceiling an agent works within.

Conclusion

The travel day worked. I built and released a version of Bivack using the previous version of Bivack, from three modes of transport and two devices, and the only thing I actually needed was a browser and my own logins.

What still stays on my laptop: anything that needs a dev server I can open in a browser tab, anything metadata-heavy enough that NFS latency turns into waiting, and anything I want to leave running for a full workday without touching it. The eight hour ceiling and the two and a half hour idle window are generous for a commute and thin for a weekend batch job.

The parts that took the most work were the plumbing around the agent CLIs: a durable home on S3 Files, a workbench that had to become a real application, and a credentials story that stays deliberately empty. If you deploy it, the S3 versioning bill is the one to watch, and the first launch of any CLI on a fresh machine is the slow one.

Additional Resources

What would you run here, and what would you keep on your laptop? Let me know in the comments.

Building a Communications Stack in Cursor with Sinch

Gunnar Grosch — Fri, 18 Sep 2026 12:12:41 +0000

A communications integration is rarely slow because of the send itself. The time goes on payload shapes, a different auth scheme for each product, and the distance between something that works in staging and something that works on the phone in your hand.

I've built enough of these on the Sinch APIs to know where that time goes, which is what makes the Sinch plugin for Cursor worth testing properly: I can tell whether the code an agent hands back is right. So I gave myself an afternoon and a demo bank to build against.

RockBank is that demo bank: A fictional lender whose customers ignore direct-mail payment reminders. The brief was to move the reminders into the channels people actually read, and to keep the whole messaging behind one send path and webhook endpoint so adding a channel is a configuration change instead of a rewrite.

What the flow does

An SMS payment reminder sent through the Sinch Conversation API
The same reminder upgraded to RCS, with a verified sender and a "Pay now" button in the thread
An automated voice reminder if the payment is still outstanding
Identity verification with a one-time passcode before the payment goes through
An email confirmation through Mailgun once the payment is complete

That's messaging, voice, verification, and email behind one send path and inbound webhook.

What the build needed

RockBank's code isn't published, so this isn't a clone-and-run. What follows is the account setup the snippets assume, and the same setup you'd need to build your own version:

Cursor with the Sinch plugin installed, and a test phone number that belongs to you
A Conversation API app: Project ID, key ID, key secret, and app ID
Separate credentials per product: A Voice application key and secret with a number assigned to it, and a Verification app key and secret, which is an app again of its own
An RCS agent approved for your market, with SMS configured on the same app for fallback. Carrier approval takes time, so start it early. An SMS sender is not a substitute: With no approved agent every reminder lands as plain text.
10DLC registration underway if you send to US numbers. More on that under Gotchas.

Setting up the plugin

Install from the Cursor marketplace, or from the command palette:

/add-plugin sinch-cursor-plugin

The plugin has three parts, and they do different jobs:

Skills load Sinch API knowledge into the agent's context before it writes code: endpoints, auth schemes, payload shapes, channel properties. This is the part that decides whether the generated code compiles against the real API or against a plausible-looking invention.
Commands (such as /send-message and /list-webhooks) call Sinch APIs directly from chat, with no code in between.
The MCP servers, two of them. sinch runs npx -y @sinch/mcp locally and connects the agent to your live account so it can send messages and inspect configuration while you work. sinch-docs is remote, at developers.sinch.com/mcp, for searching the documentation. Only the first one takes credentials.

Credentials are the one part of setup worth being precise about. Five variables go in an env block in ~/.cursor/settings.json, and Cursor needs a restart to pick them up:

{
  "env": {
    "CONVERSATION_PROJECT_ID": "your-project-id",
    "CONVERSATION_KEY_ID": "your-key-id",
    "CONVERSATION_KEY_SECRET": "your-key-secret",
    "CONVERSATION_REGION": "us",
    "CONVERSATION_APP_ID": "your-app-id"
  }
}

If the server still reports missing credentials, export the same five variables in your shell profile and do a full quit and relaunch: It runs as npx -y @sinch/mcp and inherits the environment of the shell Cursor started from.

These five are the MCP server's, and they cover the Conversation API, so the Voice key and secret never enter Cursor. Voice calls only happen when your own code runs.

Confirm the connection before writing anything:

/send-message --to=+15551234567 --message="RockBank test"

The same command takes a fallback chain, which is a useful preview of what the send path will do later:

/send-message --to=+15551234567 --message="RockBank test" --fallback=RCS,SMS

Building the send path on the Conversation API

The shape of the send path is the decision everything else depends on. The Conversation API takes one generic message body and transcodes it per channel, and it treats channel selection and fallback as data on the request instead of branches in your code. For RockBank that is the whole design: the reminder goes out over RCS with SMS behind it, voice joins later, and the call site never learns about any of it.

Worth putting that in the prompt rather than leaving it to be inferred. Ask an agent to "text customers when a payment is due" and you can reasonably get a send path shaped around one channel, because that's what you asked for. State the intent instead, and leave the mechanism to the Skill:

Implement the reminder send path against the Sinch Conversation API. Send RCS with SMS as the fallback, and keep the interface stable so adding a channel later doesn't change any call sites. Also handle delivery receipts and log them.

No field names, no endpoint, no auth scheme. The conversation-api Skill already says how fallback works: Add a channel_priority_order array and list every channel identity on the recipient. That division is the one to aim for in your own prompts. You describe the behavior you want and the constraints it has to hold to, and the Skill supplies the payload.

That last clause does real work. Without it you get a send path with no observability, and you find out how it's going the first time a customer says the reminder never arrived. With it, the agent has to account for what happens after messages:send returns a 200, which is where the interesting failures live.

What came back is one private method that takes any Conversation API message body, with the fallback expressed as channel_priority_order and both channel identities on the recipient:

async def _send(
    self,
    to: str,
    message: dict[str, Any],
    channel_properties: dict[str, str] | None = None,
) -> dict[str, Any]:
    """Send any Conversation API message over RCS, falling back to SMS."""
    properties = {"SMS_SENDER": self.sms_sender} if self.sms_sender else {}
    properties.update(channel_properties or {})

    payload: dict[str, Any] = {
        "app_id": self.app_id,
        "recipient": {
            "identified_by": {
                "channel_identities": [
                    {"channel": "RCS", "identity": to},
                    {"channel": "SMS", "identity": to},
                ]
            }
        },
        "channel_priority_order": ["RCS", "SMS"],
        "message": message,
    }
    if properties:
        payload["channel_properties"] = properties

    path = f"/v1/projects/{self.project_id}/messages:send"
    response = await self.client.post(path, auth=self._auth, json=payload)
    if response.is_error:
        raise SinchClientError(
            f"messages:send failed ({response.status_code}): {response.text}"
        )
    return response.json()


async def send_reminder(self, to: str, text: str) -> dict[str, Any]:
    return await self._send(to, {"text_message": {"text": text}})

Every channel after this one changes the message body it hands to _send, and nothing else.

The SMS_SENDER channel property is there because SMS needs an originator unless the app has a default one set. That came from the Skill, too.

Testing from the editor

This is the part the MCP server is for. With the client written and the file still open, I asked for a real send:

Send a test reminder through this service to my number, with a due date three days out and an amount of $240.

A live message through a live account, from the editor:

{
  "message_id": "01KY292FGM58WNNBETKE1Q4NF8",
  "accepted_time": "2026-07-21T12:05:38.964Z"
}

That response means accepted, not delivered. Delivery happens asynchronously and shows up on the webhook, so the next step is making sure the webhook is actually subscribed to it.

Wiring the inbound webhook

One endpoint carries both directions of traffic: MESSAGE_DELIVERY for receipts and MESSAGE_INBOUND for customer replies. Register it with a Command:

/create-webhook --target=https://rockbank.example.com/sinch/callbacks \
  --triggers=MESSAGE_DELIVERY,MESSAGE_INBOUND --secret=$SINCH_WEBHOOK_SECRET

The target has to be HTTPS and reachable from the internet, so for local work put a tunnel in front of your handler and register the tunnel URL. The secret is optional on the API, but pass one: It's what signs the callbacks, it has to match the value your handler verifies against, and there is no signature to check without it. An app takes up to five webhooks, and re-registering the same target returns a 400.

Then check what the app is actually subscribed to, which is not always what you think you asked for:

/list-webhooks
/list-webhook-triggers

Worth doing before you trust anything downstream. A webhook registered with only MESSAGE_INBOUND accepts your registration happily, and your delivery receipt handler then sits there and never runs. The send path looks healthy and the delivery log stays empty.

The handler itself needs a signature check before it looks at the body:

Write the FastAPI handler for the /sinch/callbacks endpoint. Verify the HMAC-SHA256 signature Sinch sends on each callback before processing the body, reject requests with a stale or reused timestamp, and route delivery receipts and inbound messages to separate handlers.

Sinch signs callbacks with HMAC-SHA256 over the raw body, nonce, and timestamp:

import base64
import hashlib
import hmac
import time

MAX_CALLBACK_AGE_SECONDS = 300

@router.post("/sinch/callbacks")
async def handle_callback(request: Request) -> Response:
    raw_body = await request.body()
    signature = request.headers.get("x-sinch-webhook-signature", "")
    nonce = request.headers.get("x-sinch-webhook-signature-nonce", "")
    timestamp = request.headers.get("x-sinch-webhook-signature-timestamp", "")

    try:
        age = abs(time.time() - int(timestamp))
    except ValueError:
        raise HTTPException(status_code=401, detail="Bad timestamp")
    if age > MAX_CALLBACK_AGE_SECONDS:
        raise HTTPException(status_code=401, detail="Stale callback")

    signed_data = raw_body + b"." + nonce.encode() + b"." + timestamp.encode()
    expected = base64.b64encode(
        hmac.new(
            settings.webhook_secret.encode(), signed_data, hashlib.sha256
        ).digest()
    ).decode()
    if not hmac.compare_digest(expected, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    payload = json.loads(raw_body)
    if "message_delivery_report" in payload:
        await record_delivery(payload["message_delivery_report"])
    elif "message" in payload:
        await record_inbound_message(payload["message"])
    return Response(status_code=200)

A few things to get right here. The signed string is the raw body, the nonce, and the timestamp joined by dots, in that order, and the digest is base64 rather than hex. Compute it over the raw bytes, not over a re-serialized dict, or it will never match. The key is the secret you set when you created the webhook, and x-sinch-webhook-signature-algorithm tells you which algorithm was used (HmacSHA256 today).

A valid signature on its own doesn't tell you the request is fresh. Anyone who captures a signed callback can send it again and the HMAC still checks out, which is what the timestamp and the nonce are there for: Sinch describes the nonce as unique per callback for exactly this purpose. The five-minute window above is my own choice, not a documented value, and it's the cheap half. If you need strict once-only processing, cache the nonces you have already accepted for the length of that window and reject repeats. Idempotent handling is worth having as well, because Sinch retries with exponential backoff and you will legitimately see the same receipt twice, but idempotency is not replay protection: It keeps a replayed callback from corrupting your state without ever telling you it was replayed.

Adding RCS

With the send path already channel-agnostic, RCS is a message type and a channel property:

Upgrade the reminder to an RCS rich card with the RockBank verified sender, a payment summary, and a "Pay now" button that opens our hosted payment page. Keep SMS fallback for devices that can't do RCS.

The card is a card_message with a url_message choice on it, handed to the same _send as before:

async def send_reminder_card(
    self,
    to: str,
    due_date: date,
    amount: Decimal,
    account_last4: str,
    payment_url: str,
) -> dict[str, Any]:
    card: dict[str, Any] = {
        "title": f"Payment due {due_date:%d %b}",
        "description": f"Amount: ${amount:,.2f}. Account ending {account_last4}.",
        "choices": [
            {"url_message": {"title": "Pay now", "url": payment_url}}
        ],
    }
    return await self._send(
        to,
        {"card_message": card},
        channel_properties={"RCS_WEBVIEW_MODE": "TALL"},
    )

channel_properties is a single flat map, so the RCS key and the SMS_SENDER the fallback needs end up in the same dictionary. That merge is why _send takes the properties as an argument instead of building them inline. RCS_WEBVIEW_MODE controls how much of the screen the payment page takes when it opens: FULL, HALF, or TALL.

Two details about RCS that are easy to get wrong:

RCS doesn't process the payment. The "Pay now" button is a URL action. It opens your hosted payment page in a webview over the thread, the customer pays there, and control returns to the conversation. What RCS gives you is the verified sender, the branded card, and a customer who never leaves their messaging app. The payment still runs through your payment provider.

Fallback failures arrive late. Every channel you name in channel_priority_order has to be configured on the app or the request is rejected outright, which is the easy case to debug. The harder case is a configured channel that then fails to deliver: messages:send returns 200, and the outcome shows up later as a MESSAGE_DELIVERY callback, with SWITCHING_CHANNEL marking the point where fallback kicked in. Another reason to get the webhook triggers right before relying on the fallback path.

Voice, verification, and email

The remaining four pieces each took one prompt.

Voice. If the reminder goes unanswered and the payment is still outstanding, RockBank calls. A text-to-speech callout needs no call flow server, just a POST to the Voice API:

Add a voice reminder for payments that are still outstanding two days after the message went out. Use a text-to-speech callout through the Sinch Voice API with our Voice application credentials, and set the caller ID to our registered number.

async def place_reminder_call(self, to: str, message: str) -> dict[str, Any]:
    """Place a text-to-speech reminder call via the Voice API."""
    tts: dict[str, Any] = {
        "destination": {"type": "number", "endpoint": to},
        "cli": self.caller_id,
        "locale": "en-US",
        "text": message,
    }
    response = await self.client.post(
        "/calling/v1/callouts",
        auth=(self.voice_app_key, self.voice_app_secret),
        json={"method": "ttsCallout", "ttsCallout": tts},
    )
    if response.is_error:
        raise SinchClientError(
            f"Voice callout failed ({response.status_code}): {response.text}"
        )
    return response.json()

Note the auth difference: Voice uses an application key and secret, not the project-level credentials the Conversation API uses. Different product, different auth scheme, and the Skills cover both, so the prompt didn't have to explain either.

destination for a phone call is {"type": "number", "endpoint": "+46..."} in E.164, and the response gives you a callId. The API reference lists cli as optional, but set it anyway to a verified number or one assigned from your dashboard: Without a usable caller ID you can get a call ID back for a call that never reaches the phone.

Verification. A one-time passcode before the payment page accepts anything:

Before the payment page accepts anything, verify the customer with a one-time passcode over SMS through the Sinch Verification API. Expose the method so we can switch it per request.

async def start(self, phone: str, method: str = "sms") -> dict[str, Any]:
    response = await self.client.post(
        "/verification/v1/verifications",
        auth=self._verification_auth,
        json={"identity": {"type": "number", "endpoint": phone}, "method": method},
    )
    ...

async def verify(self, reference: str, code: str) -> dict[str, Any]:
    path = f"/verification/v1/verifications/id/{quote(reference, safe='')}"
    response = await self.client.put(
        path,
        auth=self._verification_auth,
        json={"method": "sms", "sms": {"code": code}},
    )
    ...

_verification_auth is a third set of credentials: Verification authenticates with the key and secret of its own app in the dashboard, so it's neither the project-level keys the Conversation API uses nor the Voice application ones.

start returns an id, and that's what you report the code against. The method values are the part worth knowing: sms for a passcode by message, callout for one read out over a phone call, plus flashcall, seamless, and whatsapp. The report body is keyed by the same method, so {"method": "sms", "sms": {"code": "1234"}} for the message and {"method": "callout", "callout": {"code": "1234"}} for the call.

Verifications expire after a few minutes, so treat a 400 on report as "start a new one" rather than as a failed attempt. Switching a customer to callout when the message doesn't arrive is a second start call with a different method, and deciding when to offer that is application logic: How long you wait, how many attempts you allow, and whether the customer asks for it or you decide for them. Worth designing deliberately rather than leaving to a retry loop.

Email. The confirmation goes out through Mailgun, which is in the same plugin:

When a payment or payment plan is confirmed, send a confirmation email through Mailgun with the amount, the date, and a reference number.

Mailgun is a fourth set of credentials, and the odd one out: it authenticates by domain and key rather than by app, like the other three. That's Basic auth against POST /v3/{domain}/messages, with api as the username and an API key as the password. o:testmode=yes accepts a send without delivering it, which is worth knowing while you wire the confirmation up.

Gotchas

Start 10DLC registration before you write the sending code. Sending SMS to US numbers requires it, approval takes days, and no amount of agent speed compresses that. It's the most common reason an afternoon build becomes a next-week build.
A region mismatch reads like an auth problem. All Conversation API URLs are region-specific. If CONVERSATION_REGION doesn't match where the app lives, you get a 404 or an error that points at your credentials. Check the region in the dashboard before you regenerate a perfectly good key.
Test the fallback path as hard as the happy path. RCS availability varies by market, carrier, and device, and your own phone only proves the happy path. Send to a device with no RCS and confirm the SMS actually arrives. messages:transcode previews how a card degrades without sending it.
The MCP server takes real actions on a real account. That's the point of it, and it means pointing it at a test number instead of a list, and thinking about which credentials are sitting in your shell profile.
Keep the agent inside the project root. During one run the agent searched outside the open folder, found an older implementation of the same feature in a sibling directory, and mirrored that instead of using the Skills. The code worked. It was also the wrong code. Open the project you mean to work in.
Read what the agent wrote. The value of an agent that writes real integration code, instead of handing back an opaque result, is that the code is right there to review. The webhook trigger gap and the missing caller ID were both visible in the diff.

What I ended up with

From the customer's side: A reminder arrives three days before the payment is due. On a device that supports RCS it's a branded card from a verified sender with a "Pay now" button. They tap it, verify with a passcode, pay without leaving the thread, and get an email confirmation. If the payment is still outstanding, the journey follows up with an automated voice reminder.

By the end, the journey spans messaging, verification, voice, and email, built through the same Cursor workflow. The time the agent gave back was doc-reading time: Working out payload shapes and auth schemes across four products, plus the deploy-and-check cycles that usually sit between a payload being wrong and me finding out about it. Typing was never the slow part.

Try it yourself

Install the plugin from the Cursor marketplace, export the credentials, relaunch Cursor, and give the agent the Conversation API prompt from above against a test number. The plugin is open source at sinch-plugins on GitHub.

Additional resources

Originally published on the Sinch blog.

Yells at Cloud, Episode 2: The Slow Collapse of Civilization

Gunnar Grosch — Mon, 24 Aug 2026 18:56:14 +0000

Listen: YouTube · Spotify · Apple Podcasts

Summary

AI agents escaped their sandboxes, exploited Artifactory, and attacked real companies. Is that a genuine safety problem, or just another round of labs marketing how powerful their models are? Danielle covers Grok Bot and the idea of virtual coworkers with access to your accounts. Gunnar looks at Amazon's Region Flex project, where Amazon's retail division is moving workloads because the cloud is running out of physical room. Chris asks what happened to The Climate Pledge as Amazon builds a gas-powered AI data center in Texas.

Burst Mode: NVIDIA's Nemotron 3.5 Lightning, Amazon destroying books for AI training data, Twitch scraping streamer content because "if it's opt-in, nobody would opt-in," and Matthew's latest take on CloudFormation Express Mode.

Timestamps

Main topics

0:00: Cold open
2:38: AI agents escape containment (Chris)
14:34: Grok Bot and autonomous virtual coworkers (Danielle)
22:37: Project Region Flex and AWS capacity limits (Gunnar)
30:21: Amazon's polluting Texas data center (Chris)

Burst Mode

36:37: Burst Mode
36:37: NVIDIA Nemotron 3.5 Lightning (Danielle)
42:46: Amazon book destruction (Chris)
45:50: Twitch's honest extraction scheme (Gunnar)
51:09: CloudFormation Express Mode (Matthew)

Hosts

Gunnar Grosch: https://gunnargrosch.com
Danielle Heberling: https://danielleheberling.xyz
Matthew Bonig: https://matthewbonig.com
Chris Farris: https://chrisfarris.com

Follow the show

Website: https://yellsatcloudpod.com
YouTube: https://youtube.com/@yellsatcloudpod
Bluesky: https://bsky.app/profile/yellsatcloudpod.com
Twitter / X: https://twitter.com/yellsatcloudpod

Sinch from the Command Line: Numbers, Calls, Messages, Logs

Gunnar Grosch — Fri, 24 Jul 2026 14:01:52 +0000

In my previous post on Sinch Functions, I kept reaching for the CLI to test things. At some point I realized I'd been treating @sinch/cli as a Functions tool when it actually covers the whole product surface: numbers, voice, messaging, fax, SIP trunking, porting. This post goes wider.

You can do a lot with the Sinch CLI before you've written a line of application code. No Postman, no dashboard tab-switching.

The sections below are independent: different prerequisites, different credentials, no assumed order. Pick whichever is relevant to what you're building.

You'll need:

A Sinch account (Project ID, Key ID, Key Secret from the dashboard)
For voice callouts: a Voice App with a Key and Secret
For messaging: a Conversation App with at least one channel configured
For webhook testing: a Sinch Function project running locally (see Getting Started with Sinch Functions)
For log streaming: a deployed Sinch Function (same Functions post)

Installing and authenticating

npm install -g @sinch/cli

Then:

sinch auth login

The CLI walks you through Project ID, Key ID, and Key Secret, then two follow-up questions:

? Project ID (from Sinch Dashboard): <your-project-id>
? Key ID (from Project → Access Keys): <your-key-id>
? Key Secret: **********************
✔ API credentials verified!

? Add Voice application credentials? (for voice templates and callbacks) (Y/n)
? Voice Application Key: <your-voice-app-key>
? Voice Application Secret: **********************
✔ Voice credentials verified!

? Install Sinch developer skills for AI assistants? (Claude Code, Copilot, Cursor) (Y/n)

✅ Authenticated
  Project ID: <your-project-id>
  Key ID:     <your-key-id>
  Voice App Key: <your-voice-app-key>

Say yes to Voice Application credentials; you'll need them for callouts later. The Skills prompt only appears if Sinch Skills aren't already installed in your AI coding assistant. If you've done this before, it's skipped automatically. Either way, you don't need them for this walkthrough; more on this at the end.

If you've logged in before, the CLI detects existing credentials and offers to reuse them.

All credentials go into your OS keychain: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Nothing lands in a config file in plaintext. sinch auth status will tell you which storage mode is active.

Confirm the connection:

sinch health

✔ API is healthy

🏥 Health Status:
  Status: healthy
  API URL: https://functions.api.sinch.com
  Project ID: <your-project-id>

Getting a number

sinch numbers available search --region US --type LOCAL --capabilities SMS VOICE

Even with all flags passed, the CLI still asks for an optional digit pattern to filter by. This is part of the interactive mode that runs on top of the flags you've already provided. Hit Enter to skip it and get any available number. Add --non-interactive to skip all optional prompts entirely. Results show as a selectable list with capabilities and cost in your account currency:

✔ Found 20 available number(s)
? Select a number to rent (20 available):
❯ +1 202-519-9630  SMS, VOICE  0.80 EUR setup + 0.80 EUR/mo [docs required]
  +1 202-773-9769  SMS, VOICE  0.80 EUR setup + 0.80 EUR/mo [docs required]
  ...

The [docs required] tag on some numbers means regulatory documentation is required. Check the Sinch dashboard for details on what's needed for your region.

For a specific number:

sinch numbers available check +12025550134

To rent:

sinch numbers available rent +12025550134

The interactive rent flow walks you through configuration for each capability the number supports:

? Configure SMS for this number? (y/N)
? Voice configuration:
❯ None (configure later)
  RTC — Real-time Communication
  EST — Elastic SIP Trunking
  FAX
? Callback URL for provisioning events (optional):
? Rent +1 202-555-0172? This will activate it on your project. (Y/n)

If you say yes to SMS, it asks for your SMS service plan ID (find it in the Sinch SMS dashboard) and optionally a campaign ID for US 10DLC compliance. For this walkthrough, say no. You can configure it later from the dashboard. Voice lets you pick RTC, EST (which fetches your SIP trunks for selection), or Fax. Everything you'd normally do across three dashboard tabs, in one wizard. On confirmation:

✔ +1 202-555-0172 rented successfully!

  Phone Number: +1 202-555-0172
  Region:       US
  Type:         LOCAL
  Capabilities: SMS, VOICE
  Cost:         0.80 EUR/month

Manage this number: sinch numbers active get +12025550172

After renting, confirm it's yours:

sinch numbers active list

The command prompts for an optional region filter and number type before listing. Leave both blank to see everything:

✔ Found 3 active number(s)

+1 202-555-0172   [US] LOCAL   SMS, VOICE
+44 20-555-0134   [GB] LOCAL   VOICE
+46 70-555-0180   [SE] MOBILE  SMS

For the full picture on a specific number, pass it in E.164 format (no spaces or dashes):

sinch numbers active get +12025550172

✔ Number retrieved

ℹ Phone Number: +1 202-555-0172
ℹ Region:       US
ℹ Type:         LOCAL
ℹ Capabilities: SMS, VOICE
ℹ Cost:         0.80 EUR/month
ℹ Next Charge:  8/23/2026
ℹ SMS Service Plan: n/a
ℹ Voice Type:   RTC

When you're done with it:

sinch numbers active release +12025550172

Prompts for confirmation unless you pass --force.

Making a call

For this you need a Voice App with a Key and Secret. If you set one up during sinch auth login, you're ready. If not, run sinch auth login again and say yes when it asks for Voice Application credentials.

The examples below use separate numbers from the ones in "Getting a number". These are standalone demos, not a continuation of that workflow.

sinch voice callouts tts +46700000000 "Your shipment has been picked up."

The CLI infers the destination type from the format: E.164 numbers route as PSTN, sip:user@host routes to SIP, a bare string routes to an in-app endpoint. You don't need to think about it for a standard phone call.

✔ TTS callout queued

ℹ Call ID:     5b5accdf-bd0d-4448-a5d3-4cca076c732b
ℹ Destination: +46700000000
ℹ Voice:       en-US

ℹ Track status with: sinch voice calls get 5b5accdf-bd0d-4448-a5d3-4cca076c732b

A few flags worth knowing:

--voice en-US-Neural2-F sets a specific voice. Accepts full locale strings.
--cli +12039710337 sets the caller ID shown to the recipient.
--dtmf "1w2" sends DTMF tones after pickup; w is a 500ms pause.

Poll for the result. For a basic TTS callout with no voice function deployed, expect MANAGERHANGUP: the call connected, the recipient answered, the message played, and the platform ended the call. That's a successful delivery.

sinch voice calls get 5b5accdf-bd0d-4448-a5d3-4cca076c732b

✔ Call info retrieved

ℹ Call ID:    5b5accdf-bd0d-4448-a5d3-4cca076c732b
ℹ Status:     FINAL
ℹ Result:     ANSWERED
ℹ Reason:     MANAGERHANGUP
ℹ Duration:   2s
ℹ Domain:     pstn
ℹ To:         +46700000000 (Number)
ℹ Timestamp:  7/23/2026, 3:45:25 PM
ℹ Rate/min:   0.323 EUR
ℹ Total cost: 0.323 EUR

Once you have a voice function deployed to handle the ICE callback, you can keep the call alive, play a menu, collect input, and respond accordingly.

Sending a message

The examples below use separate numbers from the ones in "Getting a number". These are standalone demos, not a continuation of that workflow.

This requires a Conversation App with at least one channel configured. SMS, WhatsApp, RCS, and others are each set up separately in the Sinch dashboard. Which channels you can actually send through depends on what's configured in your app.

sinch conversation send +46700000000 "Your driver is 10 minutes away."

If you don't specify a Conversation app with -a <app-id>, the CLI prompts you to pick one and offers to save it as the default so you're not asked again:

? Select a Conversation app:
❯ 01KTFHP5SF8SQFSNK5V7NQVKZH — My Conversation App
  Enter app ID manually
? Save as default Conversation App ID? (Y/n)
✅ Default app ID saved. You won't be asked again.

It then asks which channel to use:

? Select channel:
❯ SMS
  WHATSAPP
  MESSENGER
  INSTAGRAM
  VIBER
  TELEGRAM
  RCS
  LINE

Add -c SMS or -c WHATSAPP to skip the prompt and target a specific channel directly. Only channels you've configured in the Conversation App will actually work; the others will be accepted by the CLI but fail at the API level.

Output on success:

✔ Message sent successfully!

ℹ Message ID: 01KY7KS5059DMD3WDFAD3V3J8E
ℹ Recipient:  +46700000000
ℹ Channel:    SMS
ℹ Type:       text

Testing a webhook locally

Requires a Sinch Function project on your machine (see Getting Started with Sinch Functions). Use a dedicated dev Voice App, not one handling live traffic: this rewrites its callback URL.

From your project directory:

sinch functions dev --tunnel

🎯 Starting my-simple-voice-ivr (node)
ℹ Port: 3000

✅ ✅ Server running on http://localhost:3000

[nodemon] starting `npm run build && sinch-runtime`

Function server running on http://localhost:3000

Detected functions:
   ice (voice): POST http://localhost:3000/ice
   pie (voice): POST http://localhost:3000/pie
   dice (voice): POST http://localhost:3000/dice

Starting tunnel...
Tunnel connected successfully!
✅ Updated voice webhook URL
📱 Test Phone Numbers:
   ☎️  +12025550172
💡 Call any of these numbers to test your voice function!

The CLI starts a local server, opens a Cloudflare tunnel, and rewrites your Voice App's callback URL to point at the tunnel. Real Sinch traffic now hits your machine. From a second terminal, call the test number shown in the startup output:

sinch voice callouts tts +12025550172 "Hello from your local function."

The ICE callback fires against your local handler. Incoming requests and responses appear in real time in the dev server output, in the same columnar format as sinch functions logs --follow. File watching is on, so any code change restarts the server automatically.

Streaming logs

After deploying a function, sinch functions logs --follow streams live request and response data as a columnar table. Each row shows method, status code (green for 2xx, red for 4xx/5xx), duration, and URL. Expand any row to see the full request body, response body, and console.log output from inside the function.

sinch functions logs --follow

ℹ 📋 Logs for function: my-voice-function (✅ Running)

Time        Method  Status  Duration  URL
────────────────────────────────────────────────────────────────────────────────
14:32:39  POST    200  2ms        / [ice]
  ┌ Request
  │ {
  │   "event": "ice",
  │   "callId": "8ce5c8b8-d70f-42f3-ad00-750706738f71",
  │   "cli": "46700000000",
  │   "to": { "type": "did", "endpoint": "+12025550172" },
  │   "domain": "pstn",
  │   ...
  │ }
  ├ Response
  │ {
  │   "instructions": [{ "name": "say", "text": "Press 1 for yes.", "locale": "en-US" }],
  │   "action": { "name": "runMenu", "menus": [...] }
  │ }
  └─────────────────────────────────────

If the function has console.log calls, the output appears in a Logs section between Response and the closing separator. -i opens a full-screen TUI instead. Arrow keys navigate between requests, Enter expands the detail, Esc closes it, and Q quits.

Filter by level, text, or time window:

sinch functions logs --follow --level error
sinch functions logs --follow --search "timeout"
sinch functions logs --since 30m

If you're not in a project directory with a sinch.json, pass the function ID directly:

sinch functions logs <function-id> --follow

What else the CLI covers

More messaging types. sinch conversation send supports cards, carousels, choice messages, location messages, media with captions, and pre-approved templates. Card, carousel, and choice messages are built interactively by default; pass --json-message with the full message body for non-interactive use. Templates are fetched from the API and presented as a picker.

Debugging. SINCH_DEBUG=2 on any command shows request method, URL, and status code. SINCH_DEBUG=3 adds response bodies and headers. Useful when you're chasing an auth issue and want to see exactly what's being sent.

SINCH_DEBUG=2 sinch voice callouts tts +46700000000 "Test."

Conference calls. sinch voice callouts conference <destination> <conference-id> dials a number into a conference room, created automatically if it doesn't exist.

Mid-call SVAML. sinch voice calls update <call-id> --svaml '...' injects SVAML into an active call without needing a webhook.

Fax. sinch fax send --from <number> --to <number> --file invoice.pdf

SIP trunking. sinch sip trunks covers trunks, endpoints, ACLs, and credential lists.

Number porting. sinch porting orders create starts a porting order; sinch porting documents upload handles the paperwork.

Everything accepts --json for machine-readable output and --profile <name> to switch between credential sets. With those two flags, the whole CLI is scriptable.

Troubleshooting

Auth errors on callouts. Voice callouts use a separate set of credentials from your Project Key/Secret: the Voice Application Key and Secret. If sinch voice callouts tts fails with an auth error, you probably skipped that step during sinch auth login. Run sinch auth login again and say yes when it asks for Voice Application credentials.
sinch conversation send fails after picking a channel. The CLI accepts any channel in the list, but only channels configured in your Conversation App will go through. Check your app's channel configuration in the Sinch dashboard.
sinch numbers active list output isn't copy-paste compatible with get. list shows numbers in formatted display format (+1 202-555-0172), but get expects E.164 (+12025550172). Strip the spaces and dashes before passing it.
--non-interactive hangs in CI. The CLI prompts for missing required values if you don't provide them as flags. Pass all required flags explicitly alongside --non-interactive.
sinch functions dev --tunnel rewrites your Voice App's callback URL. Use a dedicated dev Voice App, not one handling live traffic. If the tunnel connection fails, check whether port 3000 is already in use.
sinch functions logs says the function wasn't found. Log streaming requires a deployed function. If you've only run it locally with sinch functions dev, deploy it first with sinch functions deploy.

What comes next

The whole point of the CLI is that the integration workflow starts in the terminal, not in code. If you want to take that further, an AI coding assistant can drive the CLI commands for you too: describe what you need, and let it figure out which commands to run. The Sinch Skills installed during sinch auth login give Claude Code, Cursor, and Copilot knowledge of the Sinch APIs, so the same assistant writing your integration code can handle number management, callouts, and message sends alongside it. Same local-first pattern as the Functions post: real Sinch infrastructure, no context switching.

The dashboard is good for configuration you set once. The CLI is better for everything else.

Additional Resources

Curious whether you're using the CLI for anything I didn't cover here. Let me know in the comments.

Getting Started with Sinch Functions

Gunnar Grosch — Tue, 21 Jul 2026 21:49:19 +0000

I've built a lot of voice integrations. Every single one needed a deployment whose only job was to talk to the Sinch API: receive the callback, translate it into SVAML or a Conversation API call, hand off to the rest of the application. Not the interesting part. Just the piece that has to exist because your code and Sinch's network live in different places, with a round trip between them on every call event.

Sinch Functions moves that piece into the network itself. Your voice and messaging handlers run on the same infrastructure that's already carrying your calls and messages, right where the callbacks originate. This isn't a general-purpose Lambda replacement: the rest of your application, and any compute that isn't glue against Sinch's APIs, stays exactly where it is, whether that's AWS, Azure, or your own infrastructure. Your order lookup, your database writes, your actual business logic: still on Lambda or wherever you already have it. Functions is specifically for the code that exists only to bridge your app and the Sinch network, not a place to run your whole system.

I've been trying it out and this post walks through getting set up, writing a basic voice function, and deploying it.

Pricing is usage-based and separate from your Voice and Conversation usage: $0.10 per compute-hour (first hour free each month), $0.05 per GB-month of storage (first 0.1 GB free), $0.05 to $0.15 per GB-month for the database depending on tier (first 0.1 GB free), and $5.00 per month per function if you want it kept always-on instead of scaling to zero. These are the current Standard rates from your project's Billing Overview in the Sinch dashboard; treat them as a snapshot, not a guarantee, given the Alpha status below.

Sinch Functions is listed as Alpha in the Sinch Build dashboard. Expect the CLI, runtime APIs, pricing, and this walkthrough itself to change before general availability. Treat it as something to experiment with, not something to put in front of production traffic yet.

You'll need

Node.js 20 (the other supported runtime is C#, but this walkthrough uses Node.js)
A Sinch account with a phone number assigned to a Voice App, ideally a Voice App you don't use for anything real yet; more on why under Running Locally below
Project ID, Key ID, and Key Secret from the Sinch dashboard

Installing the CLI

npm install -g @sinch/cli

Then authenticate:

sinch auth login

The CLI prompts for your Project ID, Key ID, and Key Secret, then two follow-up questions. Say yes when it asks to add Voice application credentials (Key and Secret from your Voice App); this walkthrough builds a voice function and won't work without them. It'll also offer to install Sinch's developer skills for AI coding assistants like Claude Code and Cursor; that's a genuinely interesting feature but a big enough topic (it installs globally across every agent it finds on your machine) that it deserves its own post rather than a detour here. Everything from this step is stored locally and injected automatically when you run or deploy. You don't reference any of it in code.

Confirm the connection before moving on:

sinch health

✔ API is healthy

🏥 Health Status:
  Status: healthy
  API URL: https://functions.api.sinch.com
  Project ID: <your-project-id>

Creating your first function

Initialize a project from a template:

sinch functions init simple-voice-ivr --name my-simple-voice-ivr

This template is also available for C#; pass --runtime csharp if you'd rather use that. The command walks you through a few prompts: a company name used in the voice prompts, whether to auto-configure voice integration on deploy (say yes, it's what wires up the callback URL automatically), and whether to enable a database (pick "No database" for this one, since a basic IVR greeting doesn't need persistence). It then installs dependencies for you, so there's no separate npm install step. Once it's done:

cd my-simple-voice-ivr

Here's what the template generates:

my-simple-voice-ivr/
├── .github/
├── .vscode/
├── node_modules/
├── .env
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── function.ts
├── package.json
├── package-lock.json
├── runtime.json
├── sinch.json
├── test.http
└── tsconfig.json

function.ts is the only file you need to touch for this walkthrough. AGENTS.md and CLAUDE.md are instructions for AI coding assistants working in this project, test.http is a set of ready-made requests if your editor supports the REST Client format, and runtime.json and sinch.json are metadata the CLI manages for you.

function.ts is where your logic lives. Named exports become HTTP endpoints. The runtime maps them automatically based on the export name.

Open it before changing anything. The template already generated a complete, working Yes/No IVR: an ice handler that plays a menu, a pie handler that responds to the key press and retries on bad input, a dice handler that logs when the call ends, and a default handler for a base HTTP endpoint. It's worth reading through once to see the full shape of a real voice function. I'm about to replace most of it with a simpler version to build it back up in stages, not because anything is wrong with what's there.

Before touching the generated menu logic, replace it with the simplest possible ice handler, just answering the call:

import type { VoiceFunction, FunctionContext } from '@sinch/functions-runtime';
import type { Voice } from '@sinch/voice';
import { createIceBuilder, createUniversalConfig } from '@sinch/functions-runtime';

export default {
  async ice(context: FunctionContext, callbackData: Voice.IceRequest) {
    const config = createUniversalConfig(context);
    const companyName = config.getVariable('COMPANY_NAME', 'Your Company');

    return createIceBuilder()
      .say(`Hello! Thanks for calling ${companyName}.`)
      .hangup()
      .build();
  },
} satisfies VoiceFunction;

ice is the Incoming Call Event, the first callback Sinch sends when a call arrives, and it's one of four voice callbacks, each firing at a different point in a call's lifecycle: the call rings in (ICE), the call is answered (ACE), the caller presses a key on a menu (PIE), and the call ends (DICE). Each maps to a named export in function.ts. createIceBuilder() returns a builder with .say() and .hangup() directly, no menu required. createUniversalConfig(context) reads the COMPANY_NAME variable you set during init, so the greeting isn't hardcoded. Don't return raw JSON from voice handlers; use the builders.

This walkthrough never implements ace. ice already runs first and does the real work, so most simple IVRs don't need to act separately on the moment the call is answered. I haven't wired it up myself either, so treat that as an educated guess rather than something confirmed; worth exploring if your use case actually needs it.

Save that before adding anything else. The next section covers testing it, both locally and with a real call, before the menu gets added on top of it.

Running locally

sinch functions dev

This starts a local server on port 3000 with hot reload. On first run, the CLI asks whether to enable a public tunnel, with four options: enable it once, skip it once, always enable and remember, or never enable and remember. Pick one of the "enable" options. It creates a Cloudflare tunnel and updates your Voice App's callback URL to point at your machine. Real Sinch traffic hits your local function. The tunnel only exists for the lifetime of sinch functions dev: it tears down when you stop the process, and your Voice App's callback URL reverts on next deploy.

This rewrites the callback URL for the Voice App itself, not some separate dev-only layer. Use a dedicated Voice App with its own number for local development, one you never assign to real customer-facing traffic. If you run sinch functions dev against the same Voice App that's actually handling live calls, you've just rerouted production traffic to your laptop for as long as the dev server is running, so this is worth being deliberate about.

Once it's up, the CLI prints the number to call directly, something like 📱 Test Phone Numbers: +15559876543. No need to go look it up in the dashboard.

Test it with curl too:

curl -s -X POST http://localhost:3000/ice \
  -H "Content-Type: application/json" \
  -d '{"event":"ice","callId":"test-123","cli":"+15551234567","to":{"type":"number","endpoint":"+15559876543"},"domain":"pstn","originationType":"pstn"}' \
  | cat

to.endpoint is the Sinch number the CLI just printed, the one being called. cli is a fake caller ID standing in for whoever's calling; it doesn't need to be a real number for a local curl test. The local dev server needs both event and callId (capital I) in the body; leave either out and you'll get "Missing event type in request body."

That confirms the handler returns valid SVAML, but curl doesn't place an actual call. Since the tunnel is live, call the number you assigned to the Voice App and you should hear the greeting, with the company name you entered during init, for real before the call hangs up.

Keep an eye on the terminal where sinch functions dev is running while you do this. It logs each incoming request and the function's actual response in real time, and it's worth seeing at least once: you'll notice a dice callback fires automatically when the call ends, even though you haven't written a dice handler yet. Locally, the runtime handles that gracefully and just logs "DICE callback not implemented, returning 200." Once deployed, the same missing handler gets a 404 ("Function 'dice' not found") instead. Harmless since the call has already ended by the time dice fires, but worth knowing so a 404 in your production logs doesn't send you looking for a real bug.

Adding a menu

A call that just answers and hangs up isn't much of an IVR. In function.ts, add createMenu to the existing import line (createUniversalConfig is already there from the minimal version), then replace the body of the ice method (leave everything else in the file as is) with this:

import { createIceBuilder, createMenu, createUniversalConfig } from '@sinch/functions-runtime';

// inside export default { ... }, replace the ice method with:
async ice(context: FunctionContext, callbackData: Voice.IceRequest) {
  const config = createUniversalConfig(context);
  const companyName = config.getVariable('COMPANY_NAME', 'Your Company');

  const voiceMenu = createMenu()
    .prompt(`Welcome to ${companyName}! Press 1 for Yes, or press 2 for No.`)
    .repeatPrompt('Please press 1 for Yes, or 2 for No.')
    .option('1', 'return(yes)')
    .option('2', 'return(no)')
    .timeout(5000)
    .repeats(2)
    .maxDigits(1)
    .build();

  return createIceBuilder()
    .runMenu(voiceMenu)
    .build();
},

createMenu() builds the prompt and DTMF options, and runMenu() replaces the plain .say()/.hangup() chain on the builder with one that waits for input. Call the number again with sinch functions dev still running: you'll hear the menu prompt, but pressing 1 or 2 won't do anything yet, since nothing handles the result.

Responding to input

Add pie, the Prompt Input Event, fired when the caller presses a key on the menu. Add createPieBuilder to the import line, then add this as a second method alongside ice inside the same export default { ... } object:

import { createIceBuilder, createMenu, createUniversalConfig, createPieBuilder } from '@sinch/functions-runtime';

// inside export default { ... }, alongside ice:
async pie(context: FunctionContext, callbackData: Voice.PieRequest) {
  const { menuResult } = callbackData;
  const selectedOption = menuResult?.inputMethod === 'dtmf' ? menuResult.value : null;

  switch (selectedOption) {
    case 'yes':
      return createPieBuilder()
        .say('Great! You selected Yes.', 'en-US')
        .say('Thank you for calling. Goodbye!', 'en-US')
        .hangup()
        .build();

    case 'no':
      return createPieBuilder()
        .say('Okay, you selected No.', 'en-US')
        .say('Thank you for calling. Goodbye!', 'en-US')
        .hangup()
        .build();

    default: {
      const config = createUniversalConfig(context);
      const companyName = config.getVariable('COMPANY_NAME', 'Your Company');
      const retryMenu = createMenu()
        .prompt(`Welcome to ${companyName}! Press 1 for Yes, or press 2 for No.`)
        .option('1', 'return(yes)')
        .option('2', 'return(no)')
        .timeout(5000)
        .repeats(1)
        .maxDigits(1)
        .build();

      return createPieBuilder()
        .say('Invalid selection. Please try again.', 'en-US')
        .runMenu(retryMenu)
        .build();
    }
  }
},

It reads menuResult off the callback data and responds through createPieBuilder(), using the same menu-building calls as ice to re-prompt on invalid input. Curl can't fake a DTMF session, but you don't need to deploy to test it either: with sinch functions dev still running, the tunnel already points your Voice App's callback URL at your machine, so call the number now and press 1 or 2 for real. Hot reload picks up changes to pie without restarting the dev server.

One more worth adding: dice, the Disconnect Call Event, fired after the call has already ended. There's nothing to respond with here, it's just a hook for logging:

async dice(context: FunctionContext, callbackData: Voice.DiceRequest) {
  const duration = callbackData.duration != null ? `${callbackData.duration}ms` : 'unknown';
  console.info(`Call ended - reason: ${callbackData.reason}, duration: ${duration}`);
},

The reason to implement it is basic operational visibility: knowing why and how long calls actually ran, whether callers hang up early, get disconnected, or make it through the whole menu, is the kind of thing you want logged for any real IVR, independent of anything else. It also means you won't see the dashboard's error rate sitting at a nonzero number for a function that's actually working fine, since every call would otherwise fire a 404 once dice runs without a handler (covered under Running Locally above).

Here's the complete function.ts at this point, all four handlers assembled:

import type { VoiceFunction, FunctionContext } from '@sinch/functions-runtime';
import type { Voice } from '@sinch/voice';
import { createIceBuilder, createMenu, createUniversalConfig, createPieBuilder } from '@sinch/functions-runtime';

export default {
  async ice(context: FunctionContext, callbackData: Voice.IceRequest) {
    const config = createUniversalConfig(context);
    const companyName = config.getVariable('COMPANY_NAME', 'Your Company');

    const voiceMenu = createMenu()
      .prompt(`Welcome to ${companyName}! Press 1 for Yes, or press 2 for No.`)
      .repeatPrompt('Please press 1 for Yes, or 2 for No.')
      .option('1', 'return(yes)')
      .option('2', 'return(no)')
      .timeout(5000)
      .repeats(2)
      .maxDigits(1)
      .build();

    return createIceBuilder()
      .runMenu(voiceMenu)
      .build();
  },

  async pie(context: FunctionContext, callbackData: Voice.PieRequest) {
    const { menuResult } = callbackData;
    const selectedOption = menuResult?.inputMethod === 'dtmf' ? menuResult.value : null;

    switch (selectedOption) {
      case 'yes':
        return createPieBuilder()
          .say('Great! You selected Yes.', 'en-US')
          .say('Thank you for calling. Goodbye!', 'en-US')
          .hangup()
          .build();

      case 'no':
        return createPieBuilder()
          .say('Okay, you selected No.', 'en-US')
          .say('Thank you for calling. Goodbye!', 'en-US')
          .hangup()
          .build();

      default: {
        const config = createUniversalConfig(context);
        const companyName = config.getVariable('COMPANY_NAME', 'Your Company');
        const retryMenu = createMenu()
          .prompt(`Welcome to ${companyName}! Press 1 for Yes, or press 2 for No.`)
          .option('1', 'return(yes)')
          .option('2', 'return(no)')
          .timeout(5000)
          .repeats(1)
          .maxDigits(1)
          .build();

        return createPieBuilder()
          .say('Invalid selection. Please try again.', 'en-US')
          .runMenu(retryMenu)
          .build();
      }
    }
  },

  async dice(context: FunctionContext, callbackData: Voice.DiceRequest) {
    const duration = callbackData.duration != null ? `${callbackData.duration}ms` : 'unknown';
    console.info(`Call ended - reason: ${callbackData.reason}, duration: ${duration}`);
  },
} satisfies VoiceFunction;

ice, pie, and dice are all confirmed working end to end: the menu, both valid answers, bad input triggering the retry, and dice returning 200 instead of a 404.

Not included: default, a method name from the original generated template that becomes a base HTTP endpoint (not to be confused with the export default wrapping the whole object). Add it back if you want a custom endpoint; it's not needed for the IVR itself.

Configuration and secrets

Non-sensitive configuration like company names, support numbers, or feature flags goes in sinch.json under variables:

{
  "name": "my-simple-voice-ivr",
  "runtime": "nodejs20",
  "variables": {
    "SUPPORT_NUMBER": "+15551234567"
  }
}

init already wrote a .env for you, populated with your Project ID, Key ID, Voice Application Key, and the company name you entered. The actual secrets (Key Secret, Voice Application Secret) are left blank there on purpose since they're pulled from your OS keychain at runtime, not stored in the file.

Here's the part to pay attention to: the generated .gitignore does not exclude .env. It covers node_modules/, package-lock.json, and a few log/OS files, but not .env. If you git init && git add . in a fresh project, your Project ID and Key ID go into the repo in plaintext. Add .env to .gitignore yourself before your first commit.

For your own secrets, like a third-party API key, declare the name in .env with an empty value:

ELEVENLABS_API_KEY=

Then set the actual value:

sinch secrets add ELEVENLABS_API_KEY sk-...

Locally, values go into your OS keychain. In production, the platform uses an encrypted secret store. Access them in code:

import { createUniversalConfig } from '@sinch/functions-runtime';

const config = createUniversalConfig(context);
const apiKey = config.requireSecret('ELEVENLABS_API_KEY');

requireSecret throws at startup if the value is missing. Good behavior for anything your function can't run without.

To attach a debugger while testing any of this:

sinch functions dev --debug

This starts the Node.js inspector on port 9229. Connect from VS Code, Cursor, or WebStorm with F5, or attach manually to ws://localhost:9229. Secrets load automatically from your OS keychain in this mode too, so you don't need to re-enter anything to debug a handler that calls requireSecret.

Deploying

sinch functions deploy

Deploy asks two more questions first. The first is whether to generate or update documentation. Say yes; it's more useful than it sounds. It reads your actual code and generates a full write-up: an overview, a step-by-step caller experience walkthrough, key features, and a call flow diagram showing the branches through ice and pie as boxes and arrows. You can view it anytime from the function's Documentation tab in the dashboard, or in the generated README.md.

The second question is what access level the function should have. Pick Always Private (internal access only, Sinch services) rather than plain Private: this function only ever receives callbacks from Sinch's own platform, so there's no reason to expose it publicly. The "Always" matters here. Plain Private only applies to this one deploy and asks again next time. Always Private is saved to the project's sinch.json (as "accessPreference": "always-private"), so you don't have to get the answer right on every future redeploy.

The CLI then lists every configuration variable and secret it's about to ship, packages your code, and uploads it.

Your function ends up live at a URL like https://my-simple-voice-ivr.private.fn.sinch.com; the exact format depends on the access level you picked. The platform updates your Voice App's callback URL automatically, pointing it away from the dev tunnel and at the deployed function. Nothing to configure manually.

Call the number again to confirm production behaves the same as local dev did: the Yes/No menu from ice, then a response from pie after pressing 1 or 2.

None of the choices you made here are permanent. The function's Settings tab in the dashboard lets you change access level, database tier, always-on, and every configuration variable and secret after the fact, no redeploy needed for most of it. It also has a Danger Zone with a one-click "Delete function," worth knowing about once you're done experimenting, given the Alpha status.

To follow logs:

sinch functions logs --follow

Each request streams in fully expanded: time, method, status, duration, and the complete request and response bodies, no navigation needed. Logs live here, not in CloudWatch or whatever you've already got wired up for the rest of your stack.

Troubleshooting

Port 3000 already in use. sinch functions dev defaults to port 3000, and that's a common default for a lot of other local dev servers too. If something else already has it, run sinch functions dev --port 8080 (or any free port) instead, and point curl at the new port.
Tunnel won't establish. sinch functions dev fails to create the Cloudflare tunnel. Usually a network or firewall issue blocking outbound connections; retry, or run with --no-tunnel and test with curl against localhost instead.
"Missing secret" at runtime versus at startup. config.requireSecret(...) throws immediately on cold start if the secret was never set with sinch secrets add. A runtime error deeper in your handler instead usually means the secret exists but the key name doesn't match what your code requested; check for typos between the .env declaration and the requireSecret call.
Calls connect but nothing happens. If the caller hears silence or a generic carrier message instead of your greeting, the Voice App's callback URL likely isn't pointed at your deployed function. This fails silently from the caller's side; check the Voice App configuration in the dashboard against your deployment output.

Cleaning up

When you're done, delete the function:

sinch functions delete <function-id>

(del also works, and it asks for confirmation unless you pass -f.) Find the function ID with sinch functions list if you don't have it handy, or in the dashboard's Overview tab. Same result as the dashboard's Settings → Danger Zone → Delete function button, either way works. Nothing else to clean up locally beyond deleting the project directory itself.

What else you can build

The simple-voice-ivr template gets you started, but the platform supports more than IVR menus. Browse what's available:

sinch templates list
sinch templates list --runtime node

The dashboard lists four popular use cases: phone tree IVRs (press 1 for sales, 2 for support, built with SVAML actions like the one above), AI voice agents, number masking (connecting two parties without exposing either real phone number), and SMS autoresponders (custom or AI-powered replies to inbound messages). Some templates ship in both runtimes; simple-voice-ivr and number-masking each have a Node.js and a C# version.

AI voice agents are where it gets interesting, and there's more than one way to build one. 11labs-leadgen and 11labs-support connect calls to ElevenLabs conversational agents, but both are C# templates today. On the Node.js side, realtime-deepgram, realtime-google, and realtime-openai each wire a single WebSocket up to a different provider's voice API (Deepgram's Nova STT plus Aura TTS, or native audio-in/audio-out with Gemini Live or the OpenAI Realtime API, no separate STT/TTS needed for the latter two). Picking one of those and building a real voice agent on it is specific enough to deserve its own post rather than a mention here.

The Node.js runtime also gives you custom HTTP endpoints, Conversation API webhooks, and a startup hook for initialization logic. The context object includes a persistent cache shared across invocations, durable blob storage, and an embedded SQLite database. None of it requires provisioning, but all of it is still scoped to Sinch-triggered work: a place to react to calls and messages, not to relocate your API layer.

Additional Resources

If you've got a Sinch integration that's really just gluing callbacks together, curious whether this looks worth trying. Let me know in the comments.

Yells at Cloud, Episode 1: Generally Available

Gunnar Grosch — Sun, 19 Jul 2026 17:10:26 +0000

Listen: YouTube · Spotify · Apple Podcasts

Summary

AWS shipped Lambda MicroVMs, Firecracker-based sandboxes that snap back to life in milliseconds, and AJ cannot figure out who they're actually for. The pricing charges you two to three times more than it charges AWS' own services built on top of it, which is a choice. Matthew explained why CloudFormation Express Mode breaks a contract CFN has held since day one: it reports a stack as done before the resources are actually available, and disables rollback by default. Danielle brought actual good news: Cloudflare's temporary accounts let agents deploy and test without ever touching your credentials, which Matthew promptly called growth hacking. Chris covered AWS WAF's new AI traffic monetization. Publishers can now charge crawlers per request instead of just blocking them. AJ called it too little too late. And Gunnar made the case that Microsoft and AWS launching billion-dollar forward-deployed engineering programs is basically an admission that enterprise AI adoption is stuck and the tools don't work without hand-holding.

Burst Mode: Claude Sonnet 5 is "available" on Bedrock in the sense that Danielle got an AccessDeniedException and was told to call sales. Matthew on IAM Identity Center finally getting programmatic access: what took so long? AJ on Anthropic renegotiating with Amazon to token-based pricing and what that means as open-weight models close the gap. Chris was at the AWS DC Summit when the Secretary of Energy got roundly booed for claiming AI data centers won't materially impact energy consumption. And Gunnar on a paper showing that multi-agent teams consistently underperform their smartest member. Not because of disagreement. Because of dilution.

Timestamps

Main topics

0:00: Cold open
0:52: Lambda MicroVMs (AJ)
14:05: CloudFormation / CDK Express Mode (Matthew)
25:01: Cloudflare Temporary Accounts (Danielle)
31:37: AWS WAF AI Traffic Monetization (Chris)
39:06: Microsoft Frontier Co. & AWS Forward Deployed Engineering (Gunnar)

Burst Mode

49:07: Burst Mode
49:30: Claude Sonnet 5 on Bedrock: "available" (Danielle)
51:13: IAM Identity Center programmatic access (Matthew)
52:21: Anthropic / Amazon token pricing renegotiation (AJ)
55:10: AWS DC Summit: Secretary of Energy gets booed (Chris)
58:17: Multi-agent systems underperform their best member (Gunnar)

Hosts

Gunnar Grosch: https://gunnargrosch.com
Danielle Heberling: https://danielleheberling.xyz
AJ Stuyvenberg: https://aaronstuyvenberg.com
Matthew Bonig: https://matthewbonig.com
Chris Williams: https://mistwire.com

Follow the show

Website: https://yellsatcloudpod.com
YouTube: https://youtube.com/@yellsatcloudpod
Bluesky: https://bsky.app/profile/yellsatcloudpod.com
Twitter / X: https://twitter.com/yellsatcloudpod

Picking a Phone Verification Method: SMS, Flash Call, Phone Call, and Data Verification

Gunnar Grosch — Sun, 14 Jun 2026 21:34:07 +0000

When your app needs to confirm that a user actually owns the phone number they gave you, the pattern looks the same from the outside: send something to the device, user usually confirms it. Under that surface, there are four distinct approaches using phone and carrier networks, each with different security characteristics, user experiences, and requirements. The right one depends on your context.

If you want the implementation side, the Sinch Verification API is a good starting point. I've covered the code in detail in Phone-Based User Verification in TypeScript and Python.

The four methods

Method	Delivery	User action	Requires mobile data
SMS OTP	Text message	Read and type a numeric code (auto-fill possible on Android)	No
Flash Call	Missed call (caller ID is the code)	None (Android SDK) / Enter caller ID (iOS, web)	No
Phone Call Verification	Inbound phone call	Listen and type a numeric code	No
Data Verification	Carrier network check	None	Yes

The differences matter more than they appear in that table.

SMS OTP

The default choice for most apps. It works on any phone, any network, over Wi-Fi or cellular. Your users already know what to do with a six-digit code. Delivery is global, the integration is straightforward, and it pairs with any backend.

On Android, the SMS Retriever API makes auto-fill possible: the mobile SDK can read the incoming message and fill the code without user input, if your app implements it. Most apps don't, so users typically still read and type the code manually.

The trade-off is that a code the user can read is a code that can be relayed, whether by accident or by a phishing page. For most consumer flows that's an acceptable trade. For account recovery or financial transactions, you may want to weigh methods where no code changes hands at all.

Flash Call

A call is placed to the user's number and immediately disconnected. The incoming caller ID is the verification code. On Android, the mobile SDK can intercept the caller ID automatically, completing verification without any user input. On iOS and web, the user reads the incoming number from their recent calls and enters it manually.

On Android, both SMS and Flash Call can complete without user input. The difference is that Flash Call never delivers a visible code at all. There's nothing to relay to a phishing page, misread, or enter incorrectly. On iOS the UX is more similar to SMS since the user still has to retrieve and enter a value, just from the call log instead of a text. Flash Call is still PSTN-based, so it shares the same SIM-level exposure as SMS. The specific benefit is phishing-resistance, not a broader security upgrade.

Flash Call is typically priced at a fixed rate per attempt, while SMS pricing varies by destination country and operator. In markets where SMS termination is expensive, Flash Call can be meaningfully cheaper at scale. Voice calls typically cost more than SMS, and Data Verification is priced separately.

Phone Call Verification

A text-to-speech call reads the code aloud. By default the user listens and types it in. Most providers also support prompting the user to press a digit on the keypad to confirm, which helps bypass voicemail: if the user doesn't answer, the call goes to voicemail and the code is spoken to the wrong listener. The keypress prompt ensures a human answered before the code is read out.

Choose it for coverage: it reaches numbers that SMS can't. Landlines, VoIP numbers, users in regions where SMS delivery is consistently unreliable. For mobile-first apps, it adds friction without much benefit over SMS. For apps where users might be verifying a non-mobile number or where SMS delivery is unreliable in your target market, it closes a gap the other methods leave open.

Data Verification

Your backend calls the verification API with the user's phone number. The carrier authenticates the device through its network infrastructure, with no visible interaction. The result comes back in the API response. If it succeeds, verification is done before the user does anything.

There's no code for the user to handle at any point. The constraint is cellular data: it must be enabled and available on the device. Modern mobile OSes can route the authentication request over the cellular interface even when Wi-Fi is connected, but if cellular data is off or unavailable, the carrier can't authenticate the device and the request fails. A second constraint worth knowing: on dual-SIM devices, the carrier authenticates based on the SIM handling data traffic. If that SIM is different from the number being verified, the check fails. You need a fallback either way.

One more practical note: on Sinch, Data Verification isn't self-serve. Enabling it requires carrier routing agreements, so you'll need to contact your account manager before it's available. Plan for that lead time if you're building it into your architecture.

Data Verification is a good first attempt for mobile apps where you control the client environment, but it can't stand alone.

How to pick

The decision comes down to a few questions:

Is this a mobile app or a web app? For web, SMS is the baseline. Flash Call and Phone Call Verification are useful as fallbacks but neither delivers the native SDK experience that makes them frictionless on mobile. For mobile apps, a practical default: Flash Call on Android (the SDK intercepts automatically, zero user input), SMS on iOS (Flash Call is less streamlined there). Layer Data Verification on top of that if your carrier coverage allows it.

How much friction can your flow afford? Signup confirmation can tolerate a code-entry step. A checkout flow or account recovery step benefits from fewer interruptions. Data Verification and Flash Call (with the Android SDK) add zero friction for the user. If reducing drop-off at the verification step matters to your conversion, start there.

Who are your users and where are they? SMS delivery is not uniform globally. In some regions, high termination costs make SMS pricing volatile at scale, and Flash Call's fixed per-attempt pricing is worth considering. In others, carrier support for CLI delivery or Data Verification varies. If you're building for a specific geography, check delivery rates and method availability for that market before committing.

Do your users have landlines or VoIP numbers? If yes, Phone Call Verification is the only method that reaches them. Build it as a fallback option even if it's not your primary path.

Fallback chains

No single method works for every user in every context. Build a fallback chain rather than picking one and moving on.

The general sequence: attempt Data Verification first for mobile users (best UX, no code handling), fall back to Flash Call or SMS if it fails or the user is on Wi-Fi, and offer Phone Call Verification as a last resort for users who don't receive the first attempt. On the web, start with SMS and offer Phone Call Verification as the fallback path, surfaced as a "didn't receive the code?" option in your UI.

If you're using a mobile SDK, it will typically provide a callback you can hook into to trigger a fallback automatically when the primary method fails. If you're integrating via the REST API directly, you implement the fallback yourself: catch the failure response from start, then issue a new request with a different method value.

The two-step API is the same regardless of method: start to trigger delivery, report to validate what the user confirms. Switching between methods is a one-field change in the request body, which keeps the fallback logic straightforward to implement.

Wrapping up

SMS OTP is broadly compatible and the right default for most apps. Flash Call eliminates the code-entry step and offers fixed-rate pricing. Phone Call Verification covers landlines and numbers that SMS can't reach. Data Verification is the lowest friction option for mobile but requires cellular data, a fallback, and provisioning through your account manager.

For most apps, the answer isn't picking one but combining them: Data Verification or Flash Call as the primary path for mobile, SMS as the reliable fallback, Phone Call Verification as the last resort. That covers most users and handles the edge cases where your first choice fails.

If you want the backend implementation for any of these methods, including TypeScript and Python examples for the Sinch Verification API, that's covered in Phone-Based User Verification in TypeScript and Python.

Additional Resources

What verification method are you using, and what drove the choice? Let me know in the comments.

Phone-Based User Verification in TypeScript and Python

Gunnar Grosch — Wed, 10 Jun 2026 13:07:26 +0000

A user signs up for your app. You need to confirm the phone number they entered actually belongs to them. A returning user wants to log in without a password. An account change needs a second factor before it goes through.

The underlying pattern is always the same: send a code to the device, wait for the user to confirm it.

The Sinch Verification API handles this with a two-step flow. Your backend calls start to trigger code delivery, and report to validate what the user submits. It supports four methods: SMS, FlashCall (a missed call where the incoming caller ID is the code), voice (text-to-speech), and Data Verification (silent authentication through the carrier's network, no user input at all). The payload shape is the same for all four, so switching methods is a one-field change.

This post covers the backend piece. Whether your frontend is a web app, iOS, or Android, the pattern is the same: your client calls your API, your API calls Sinch. A mobile app calling a Lambda function, a web form submitting to an Express server, a Next.js API route. The code here works for all of them.

This post uses the official Sinch Node.js SDK. Python and no-dependency Node.js examples are in the raw HTTP section at the end.

Prerequisites

You'll need a Sinch account (sign up here, a trial account is enough to test, see pricing for details) and Node.js 18+ or Python 3.9+.

In the Sinch Dashboard:

Create a Verification app. Go to Verification > Apps and click New app. Enter a name and optional description.
Copy your App Key and App Secret. They appear on the right side of the creation dialog under "Your summary". Copy both before closing.
Set the authentication level. In the Settings panel on the left, find Minimal Authentication Level and set it to Application. This ensures only signed requests (like the ones in this post) are accepted. The default is Public, which allows unsigned requests and is intended for mobile clients calling Sinch directly.

Note: on a trial account you can only verify numbers on your verified numbers list. To verify any number, upgrade your account.

How verification works

The flow is two steps:

Start: your backend calls the Verification API with the phone number and method. Sinch delivers the code to the device.
Report: the user enters the code. Your backend calls the API with the phone number and code. Sinch returns SUCCESSFUL or FAILED.

For SMS and voice, the code is a numeric OTP. For FlashCall, the "code" is the full incoming caller ID from the missed call. For Data Verification there is no report step: Sinch authenticates the device silently through the carrier's network and returns the result in the start response.

The SDK approach (Node.js)

The Node.js SDK handles authentication internally. You initialize it once with your credentials. The Verification API has method-specific calls for start and report rather than a single generic endpoint, so each method gets its own SDK call.

Note: the Python SDK doesn't include Verification yet. Python developers can use the raw HTTP section below.

Install the SDK:

npm install @sinch/sdk-core

import { SinchClient } from "@sinch/sdk-core";

const sinchClient = new SinchClient({
  applicationKey: process.env.SINCH_APP_KEY!,
  applicationSecret: process.env.SINCH_APP_SECRET!,
});

const E164_REGEX = /^\+[1-9]\d{1,14}$/;

export async function startVerification(
  phoneNumber: string,
  method: "sms" | "flashcall" | "callout" | "data" = "sms"
) {
  if (!E164_REGEX.test(phoneNumber)) {
    throw new Error(`Invalid phone number format. Use E.164 (e.g. +15551234567), got: ${phoneNumber}`);
  }

  if (method === "sms") {
    return sinchClient.verification.verifications.startSms({
      startVerificationWithSmsRequestBody: {
        identity: { type: "number", endpoint: phoneNumber },
      },
    });
  }
  if (method === "flashcall") {
    return sinchClient.verification.verifications.startFlashCall({
      startVerificationWithFlashCallRequestBody: {
        identity: { type: "number", endpoint: phoneNumber },
      },
    });
  }
  if (method === "callout") {
    return sinchClient.verification.verifications.startPhoneCall({
      startVerificationWithPhoneCallRequestBody: {
        identity: { type: "number", endpoint: phoneNumber },
      },
    });
  }
  return sinchClient.verification.verifications.startData({
    startDataVerificationRequestBody: {
      identity: { type: "number", endpoint: phoneNumber },
    },
  });
}

export async function reportVerification(
  phoneNumber: string,
  code: string,
  method: "sms" | "flashcall" | "callout" = "sms"
) {
  if (method === "sms") {
    return sinchClient.verification.verifications.reportSmsByIdentity({
      endpoint: phoneNumber,
      reportSmsVerificationByIdentityRequestBody: { sms: { code } },
    });
  }
  if (method === "flashcall") {
    return sinchClient.verification.verifications.reportFlashCallByIdentity({
      endpoint: phoneNumber,
      reportFlashCallVerificationByIdentityRequestBody: { flashCall: { cli: code } },
    });
  }
  return sinchClient.verification.verifications.reportPhoneCallByIdentity({
    endpoint: phoneNumber,
    reportPhoneCallVerificationByIdentityRequestBody: { phoneCall: { code } },
  });
}

Call startVerification when the user submits their phone number, and reportVerification when they submit the code:

// Step 1: user submits phone number
const started = await startVerification("+15559876543", "sms");
console.log(started.id);

// Step 2: user submits the code from their device
const result = await reportVerification("+15559876543", "123456", "sms");
if (result.status === "SUCCESSFUL") {
  // issue session token, complete login, approve account change, etc.
}

A successful start response:

{
  "id": "01ABC123DEF456GHI789JKL012",
  "method": "sms",
  "sms": {
    "template": "Your verification code is {{CODE}}. Verified by Sinch",
    "interceptionTimeout": 198
  }
}

The response includes additional fields (_links, etc.) that you don't need for the basic flow.

A successful report response:

{
  "id": "01ABC123DEF456GHI789JKL012",
  "method": "sms",
  "status": "SUCCESSFUL",
  "source": "manual"
}

If the code is wrong or expired, the SDK throws. Treat that as a prompt for the user to request a new code, not a retry of the same one.

Raw HTTP

If you're using Python, or prefer no runtime dependency in Node.js, the same flow works with plain HTTP. Each request must be signed with HMAC-SHA256 using your App Secret. The signature covers the HTTP method, a hash of the request body, the content type, a timestamp, and the request path. This lets the server verify the request hasn't been tampered with and isn't a replay.

Python

import hashlib
import hmac as hmac_mod
import base64
import json
import os
import re
import urllib.request
import urllib.error
import urllib.parse
from datetime import datetime, timezone

APP_KEY = os.environ["SINCH_APP_KEY"]
APP_SECRET = os.environ["SINCH_APP_SECRET"]

CONTENT_TYPE = "application/json; charset=UTF-8"
E164_REGEX = re.compile(r"^\+[1-9]\d{1,14}$")


def sign(method, path, body):
    timestamp = datetime.now(timezone.utc).isoformat()
    content_md5 = base64.b64encode(hashlib.md5(body.encode()).digest()).decode() if body else ""
    string_to_sign = f"{method}\n{content_md5}\n{CONTENT_TYPE}\nx-timestamp:{timestamp}\n{path}"
    signature = base64.b64encode(
        hmac_mod.new(base64.b64decode(APP_SECRET), string_to_sign.encode(), hashlib.sha256).digest()
    ).decode()
    return f"Application {APP_KEY}:{signature}", timestamp


def sinch_request(url, http_method, payload):
    path = urllib.parse.urlparse(url).path
    body = json.dumps(payload)
    auth, timestamp = sign(http_method, path, body)
    req = urllib.request.Request(
        url, data=body.encode(),
        headers={"Content-Type": CONTENT_TYPE, "Authorization": auth, "x-timestamp": timestamp},
        method=http_method,
    )
    try:
        with urllib.request.urlopen(req) as resp:
            return json.loads(resp.read())
    except urllib.error.HTTPError as e:
        raise RuntimeError(f"Sinch API error {e.code}: {e.read().decode()}")


def start_verification(phone_number, method="sms"):
    if not E164_REGEX.match(phone_number):
        raise ValueError(f"Invalid phone number format. Use E.164 (e.g. +15551234567), got: {phone_number}")
    return sinch_request(
        "https://verification.api.sinch.com/verification/v1/verifications", "POST",
        {"identity": {"type": "number", "endpoint": phone_number}, "method": method},
    )


def report_verification(phone_number, code, method="sms"):
    body = {"method": method}
    if method == "sms": body["sms"] = {"code": code}
    elif method == "flashcall": body["flashcall"] = {"cli": code}
    elif method == "callout": body["callout"] = {"code": code}
    return sinch_request(
        f"https://verification.api.sinch.com/verification/v1/verifications/number/{phone_number}",
        "PUT", body,
    )

Node.js (no SDK)

import { createHmac, createHash } from "crypto";

const APP_KEY = process.env.SINCH_APP_KEY!;
const APP_SECRET = process.env.SINCH_APP_SECRET!;

const CONTENT_TYPE = "application/json; charset=UTF-8";

function sign(method: string, path: string, body: string) {
  const timestamp = new Date().toISOString();
  const contentMd5 = body
    ? createHash("md5").update(body, "utf8").digest("base64")
    : "";
  const stringToSign = `${method}\n${contentMd5}\n${CONTENT_TYPE}\nx-timestamp:${timestamp}\n${path}`;
  const signature = createHmac("sha256", Buffer.from(APP_SECRET, "base64"))
    .update(stringToSign)
    .digest("base64");
  return { auth: `Application ${APP_KEY}:${signature}`, timestamp };
}

async function sinchRequest(method: string, url: string, body?: object) {
  const bodyStr = body ? JSON.stringify(body) : "";
  const path = new URL(url).pathname;
  const { auth, timestamp } = sign(method, path, bodyStr);
  const response = await fetch(url, {
    method,
    headers: { "Content-Type": CONTENT_TYPE, Authorization: auth, "x-timestamp": timestamp },
    ...(bodyStr && { body: bodyStr }),
  });
  if (!response.ok) throw new Error(`Sinch API error ${response.status}: ${await response.text()}`);
  return response.json();
}

export async function startVerification(phoneNumber: string, method = "sms") {
  return sinchRequest("POST", "https://verification.api.sinch.com/verification/v1/verifications", {
    identity: { type: "number", endpoint: phoneNumber },
    method,
  });
}

export async function reportVerification(phoneNumber: string, code: string, method = "sms") {
  const body: Record<string, unknown> = { method };
  if (method === "sms") body.sms = { code };
  else if (method === "flashcall") body.flashcall = { cli: code };
  else if (method === "callout") body.callout = { code };
  return sinchRequest(
    "PUT",
    `https://verification.api.sinch.com/verification/v1/verifications/number/${phoneNumber}`,
    body,
  );
}

Both functions raise on a non-2xx response. A wrong or expired code returns HTTP 400. Catch that and prompt the user to request a new code.

Sinch also publishes SDKs for Java and .NET if those are your languages.

Things worth knowing

Verifications expire

A started verification is only valid for a short window: a few minutes for SMS. If the user takes too long, the report call will fail. Build your UI to handle this: show a "resend code" option and treat expiry errors as a prompt to start fresh, not a permanent failure.

Phone numbers must be E.164

The phone number must be in E.164 format: +15551234567, not 5551234567 or (555) 123-4567. Both the SDK and raw HTTP examples validate this before calling the API. The Sinch Verification API won't normalize it for you.

FlashCall code format

For FlashCall, the code you pass to reportVerification is the full incoming caller ID: the complete phone number that called the device. Your mobile client captures this from the call log and passes it to your backend.

Data Verification requires cellular data

Data Verification only works when the device is on cellular data. If the user is on Wi-Fi, the carrier can't authenticate the device. Configure a fallback chain: attempt data first, then fall back to FlashCall or SMS. The API supports this natively so you don't have to retry manually.

Wrapping up

Two functions, a clear two-step flow, and support for four verification methods. The SDK version needs no auth code. Initialize once and call. The raw HTTP version adds no dependencies at all. Both drop into any backend regardless of framework or platform.

If you're building a mobile app, Sinch also publishes native SDKs for iOS and Android. They handle the client side of verification: automatically capturing the incoming caller ID for FlashCall so the user never has to read it, and managing the carrier network handshake for Data Verification. The backend code in this post pairs directly with those SDKs.

Additional Resources

What are you building that needs user verification? Let me know in the comments.

DEV Community: Gunnar Grosch

Build, Operate, and Automate Sinch APIs with the Sinch CLI

You'll need

Install and authenticate

Get a phone number

Create a Voice service

Build a voice function

Make it speak on an outbound call

Test it locally

Deploy it

Place the call

Watch the logs

Secrets

Stream call audio or connect the Voice Relay

Send an SMS with the Sinch Conversation API

More in the CLI

Automate it

Use the Sinch CLI with coding agents

Troubleshooting

Command reference

Where to go next

Additional resources

Build a voice IVR with Sinch Functions

You'll need

Why Functions fits this job

Install and authenticate the CLI

Create the function

Write the first handler

Run it locally

Add a menu

When a menu needs your code

Store secrets safely

Deploy the function

Test the deployed function

Troubleshooting

Cleaning up

Where to go next

Additional resources

Yells at Cloud, Episode 3: Super Intelligence, Artificial Slowdown

Summary

Timestamps

Links

Hosts

Follow the show

Connect AI Agents to Phone Calls with Sinch Voice API v2

Why Voice Relay matters

The Voice API v2 model

You'll need

Connect an agent with Voice Relay

What success looks like

Where your application sits

Voice Relay or raw audio streaming?

Production considerations

Troubleshooting

Preview status

What's next

Additional Resources

Building Bivack: A Cloud Dev Sandbox for Coding Agents on AWS Lambda MicroVMs

Why the agent needs its own machine

What using it is like

The chooser

The terminal

The workbench

Why not a hosted agent or a VPS

The constraint that shapes everything

What goes in the image

A few things I learned building this

Put the home on S3 Files, not a disk

Versioning comes with S3 Files, and so does the bill

The web workbench is its own project

No AWS credentials in the sandbox, on purpose

Egress has two prices

Getting started

Upgrading

What it does not do

Conclusion

Additional Resources

Building a Communications Stack in Cursor with Sinch

What the flow does

What the build needed