DEV Community: Gunnar Grosch

Give an OpenAI GPT-Live voice agent a phone number with Sinch Functions

Gunnar Grosch — Wed, 11 Nov 2026 14:15:15 +0000

In Connect AI agents to phone calls with Sinch Voice API v2, the agent stayed in text. Using Voice Relay, Sinch turned the caller's speech into text, the agent answered in text, and Sinch spoke the answer. That's the right setup when your agent is a text application. Speech-to-speech models work differently: They take the caller's audio in and speak their answer back, so there's no text step to wait for. The Realtime Voice: OpenAI template in Sinch Functions connects a phone call to OpenAI's GPT-Live model that way. You'll deploy it with the Sinch CLI and call it from your own phone.

The template runs as a Sinch Function, so there's no server for you to host and no tunnel to keep open. Its demo agent is the host at Bella Vista, a small Italian restaurant, with two tools: Check availability and book a table. I made the test calls for this post against a deployed copy of it.

You'll need

A Sinch account with access to Voice API v2
The Sinch CLI 0.8.2 or later, logged in with sinch auth login
Node.js 24 or later
An OpenAI API key from an account with billing set up (GPT-Live isn't on the API's free tier, and a ChatGPT subscription doesn't include API access)
A phone to call from

The CLI rents a US number for the agent. If you call it from outside the US, it's an international call for you. Voice API v2 is in public preview, so features and behavior can still change.

Relay or realtime?

Both templates put an AI agent on a Voice API v2 call. They differ in what travels between Sinch and the agent:

	Voice Relay (earlier post)	Realtime (this post)
Between Sinch and the agent	Text	Raw call audio
Speech recognition and voice	Sinch	The OpenAI model
Model	Any text model	A speech-to-speech model

Pick relay when your agent is a text application you want to keep, or when you want Sinch voices. Realtime is the better fit when you want the model's own voice and the shortest path from the caller's words to an answer. Both can run as a Sinch Function. The earlier post hosted its own relay server, and the voice-relay-agent template runs relay inside a function instead. The Sinch Functions template list has realtime templates for OpenAI, Google Gemini Live, xAI Grok, and Deepgram, too. They share the same function structure.

How the template works

When a call comes in, Voice API v2 sends a call.incoming event to the function. The function answers with a call plan in SVAML that bridges the caller to a second leg, a STREAM leg pointing back at the function's own WebSocket:

{
  "callName": "caller",
  "commands": [
    { "command": "answer" },
    { "command": "bridgeCall", "bridgeName": "bridge" },
    {
      "command": "dial",
      "callName": "stream",
      "to": {
        "type": "STREAM",
        "stream": {
          "endpoint": "wss://YOUR_FUNCTION_HOST/stream",
          "streamOptions": { "version": 1, "codec": "PCM", "sampleRate": 8000 }
        }
      },
      "maxCallDurationSeconds": 1800,
      "events": {
        "onAnswer": [{ "command": "bridgeCall", "bridgeName": "bridge" }]
      }
    }
  ]
}

When the stream leg answers, it joins the same bridge as the caller. That's the same answer, bridge, and dial shape the relay post used, with STREAM where the relay post had VOICE_RELAY. The full plan also hangs up the caller if the stream leg can't connect, and hangs up the stream leg when the caller hangs up.

From there, the Sinch Functions runtime does the work:

Sinch opens the WebSocket and sends the caller's audio as 8 kHz PCM.
The runtime opens a session with OpenAI's GPT-Live (gpt-live-1), converts the audio to the G.711 format the session uses, and passes it through in both directions.
GPT-Live does the talking. When a turn needs reasoning or a tool call, GPT-Live hands it to a second, text-based model, the backend model, and the runtime runs your tool code inside the function.
When the call ends, the function saves the transcript, timings, and token usage to function storage.

The runtime also adds two tools of its own: hangup_call, so the agent can end the call after saying goodbye, and transfer_to_human when you set a number to transfer to.

Create the function

sinch functions init scaffolds the function. With --create-voice-service and --rent-number, it also creates a Voice API v2 service, rents a US number, and links the number to the service:

sinch functions init realtime-openai --runtime node --name realtime-openai-phone-agent \
  --create-voice-service --rent-number US --force --non-interactive

Renting a number costs money, which is why the command needs --force. Without the flags, init asks. Creating a new Voice service is the default answer, and the number prompt shows the price before it orders anything. Either way, the output names the service and the number:

Created Voice service e7756e27-4346-422e-b81c-329874b9a1fb
   Rented +12084419139 and linked it to Voice service e7756e27-4346-422e-b81c-329874b9a1fb

The function's .env file keeps both, as VOICE_SERVICE_ID and VOICE_FROM_NUMBER.

Add your OpenAI key and a dashboard password

The function reads two secrets. OPENAI_API_KEY is your OpenAI key. ADMIN_PASSWORD protects the dashboard and transcript pages, which use the username admin. Run without flags, init asks for both. After a non-interactive init, add them yourself:

cd realtime-openai-phone-agent
sinch secrets add OPENAI_API_KEY YOUR_OPENAI_API_KEY
sinch secrets add ADMIN_PASSWORD YOUR_DASHBOARD_PASSWORD

The CLI stores secrets in your OS keychain and sends them with the deploy. The password only unlocks the two dashboard pages, so you can share it without sharing access to your Sinch project.

What's in the function

Everything the agent says and does lives in function.ts. The blocks below are excerpts from the file init generated. It deploys as it is once the secrets are set, and you customize it by editing these parts in place. The core is one realtimeAgent call:

const agent = realtimeAgent({
  provider: 'openai',
  prompt: `You are the host at Bella Vista, a small Italian restaurant. Keep replies short and conversational, the way a person would speak on the phone. Callers may ask about hours, the menu, or want to check availability and book a table — use the tools for that. If a caller wants to speak with a person, offer to transfer them. Speak in plain sentences only — no markdown, asterisks, or other symbols, since your words are read aloud. Reply in English unless the caller clearly speaks another language for more than a word or two. Confirm the reservation name with the caller before booking. After booking, read back the date, time, party size, and confirmation number, then say goodbye — only end the call after that.`,
  greeting: 'Thanks for calling Bella Vista, how can I help?',
  transferTo: process.env.TRANSFER_TO,
  tools: restaurantTools(),
  onEnd: async (ctx) => {
    // ... saves the transcript, timings, and usage to function storage
  },
});

The greeting is spoken by GPT-Live, in the model's voice, as soon as the stream connects. The tools are plain functions with a JSON Schema for their arguments. This is the booking tool:

const book_table = tool<{
  date: string;
  time: string;
  party_size: number;
  customer_name: string;
  notes?: string;
}>({
  name: 'book_table',
  description: 'Book a table reservation.',
  parameters: {
    type: 'object',
    properties: {
      date: { type: 'string', description: 'Date in YYYY-MM-DD' },
      time: { type: 'string', description: 'Time in HH:MM 24h' },
      party_size: { type: 'number', description: 'Number of guests' },
      customer_name: { type: 'string', description: 'Name for the reservation' },
      notes: { type: 'string', description: 'Special requests' },
    },
    required: ['date', 'time', 'party_size', 'customer_name'],
  },
  handler: async ({ date, time, party_size, customer_name, notes }, ctx) => {
    const confirmationId = `BK-${Date.now().toString(36).toUpperCase()}`;
    await ctx.storage.write(
      `bookings/${confirmationId}.json`,
      JSON.stringify({ date, time, party_size, customer_name, notes })
    );
    return {
      success: true,
      confirmation_id: confirmationId,
      message: `Booking confirmed for ${customer_name} on ${date} at ${time} (${party_size} guests). Confirmation: ${confirmationId}.`,
    };
  },
});

The handler runs inside the function, so it can reach anything the function can: Function storage here, your booking system in a real deployment. The demo's availability check says yes to everything, so swap in your own before you put a real number on it.

Deploy and call

Deploy the function to the public namespace, so Sinch can reach both the webhook and the WebSocket:

sinch functions deploy --public --no-docs

--no-docs skips the step that regenerates README.md. The template's transfer number, TRANSFER_TO, is empty by default, so the deploy warns about it before it starts:

⚠ Validation passed with warnings
⚠️  TRANSFER_TO is empty and not found in credentials or keychain — it will not be available in production
   💡 Set a value in .env or add a secret: sinch secrets add TRANSFER_TO <value>
? Deploy anyway? (Y/n)

Answer Y to deploy without transfers. To enable them, set TRANSFER_TO=+15551234567 in the function's .env file with the number to transfer to, and deploy again.

When it finishes, the deploy has built the function, started it, and pointed the Voice API v2 service at it:

✔ ✅ Function deployed successfully

ℹ 🎉 Deployment Complete!
ℹ    Function: realtime-openai-phone-agent
ℹ    Status: ✅ Running
ℹ    URL: https://firm-beacon.fn.sinch.io

ℹ 📞 Voice Integration:
ℹ    Voice service e7756e27-4346-422e-b81c-329874b9a1fb webhook set by the Functions API to: https://firm-beacon.fn.sinch.io/webhook/voice

The URL in the output is your function's address. Follow the logs in a second terminal with sinch functions logs --follow, then call the number.

This is one of my test calls, booking a table for three. It ran with the backend model set to gpt-6-luna, covered in Make it yours:

Agent:  Thanks for calling Bella Vista. How can I help?
Caller: Can I book a table for three people for Saturday at 4 p.m.?
        [check_availability]
Agent:  Okay, let me check if we have a table open then. Yeah, that time is
        available. What name should I put the reservation under?
Caller: It's under Riley.
Agent:  Riley. Okay, just to confirm, that's under the name Riley?
Caller: Yes.
        [book_table, BK-MVTOZNRS]
Agent:  Great, one moment. You're all set for three this Saturday at 4 p.m.,
        under Riley. Your confirmation number is B K dash M V T O Z N R S.
        Thanks for calling Bella Vista. Goodbye.
Caller: Thanks, bye.
Agent:  Take care, bye.
        [hangup_call]

In this call, the agent started speaking 0.2 to 0.8 seconds after the caller stopped, including the turns that called a tool. Those numbers come from the runtime's own timestamps for when the caller's speech ended and the agent's audio started, so they don't include the phone network's delay. The call lasted 56 seconds.

Read the dashboard

The template adds two pages to the function. /conversations returns the last 20 saved calls as JSON, and /dashboard shows them with timing per turn. Open /dashboard on your function's URL from the deploy output, for example https://firm-beacon.fn.sinch.io/dashboard, and log in with admin and your password.

The dashboard with sample calls.

The number to watch is caller waits: The time from when the caller stops talking until they hear the agent. The bars labeled agent in the chart show that wait for each reply. The yellow part is time spent in your tools, and the blue part is the rest of the wait. Striped segments are estimates the dashboard uses when a call is missing a timestamp. The estimated cost is a rough figure from token and session counts. The rates it uses are in PRICE_TABLE in assets/dashboard.html, so set them to GPT-Live's per-minute price and your backend model's token prices.

Make it yours

Most of the changes you'll want are in the realtimeAgent options:

prompt and greeting set who the agent is. Put the facts it should know in the prompt, such as opening hours and a short menu, or the model fills the gaps on its own.
tools is where your business logic goes. Each tool's description and parameters tell the model when to call it.
voice picks one of OpenAI's voices. Without it, OpenAI uses its default.
transferTo enables the transfer_to_human tool.
providerOptions.openai passes OpenAI-specific settings through. The backend model that handles tools and reasoning is one of them. Add it to the existing realtimeAgent call:

const agent = realtimeAgent({
  provider: 'openai',
  // ... prompt, greeting, tools
  providerOptions: { openai: { backendModel: 'gpt-6-luna' } },
});

The template's default backend model is gpt-5.6-luna. The test call above ran with gpt-6-luna, the model OpenAI's delegation guide uses in its examples.

The template also exists for C#, with the agent as a class and each tool as a method marked [AgentTool]. The flow on the call is the same.

Before you take real calls

Cost

At the time of writing, GPT-Live costs $0.05 per minute of session time, and the backend model's tokens are billed on top. Sinch voice minutes and the number are billed separately. The test call above used 44 seconds of GPT-Live session time, about $0.04, and about 9,600 backend input tokens. Check OpenAI's model page for current rates and for the limit on concurrent sessions at your usage tier.

Ending calls

The agent ends a call by calling hangup_call, so the model decides when the conversation is over. The runtime adds instructions for that to your prompt, and your own prompt shapes it too, so test the endings your callers will actually use. The stream leg also has a maximum duration of 30 minutes, which caps any call that stays open.

Bookings

Treat the result of book_table as the record of a booking, and check bookings in your own system. The confirmation the agent reads out is the model repeating that result to the caller, so use the tool results, which the transcript also stores, for anything that depends on the booking, like a reminder message.

Who can see the transcripts

Transcripts include everything the caller said, and the function logs include the caller's number. Keep ADMIN_PASSWORD strong, and treat function storage as a place that holds customer data.

Troubleshooting

The call doesn't reach the function

Check that the service points at the function with sinch voice services get YOUR_SERVICE_ID, using VOICE_SERVICE_ID from .env. The webhook should be your function's URL followed by /webhook/voice. If it isn't, deploy again, and wait for the deploy to finish before you call.

The call connects and ends right away

The function couldn't open the OpenAI session, so it ends the call instead of leaving the caller in silence. The logs show the call.incoming and, a second later, a call.hangup with MANAGER_HANGUP. Check the stored key with sinch secrets get OPENAI_API_KEY --show, make sure it belongs to a paid OpenAI tier, and deploy again after you change it.

The dashboard returns 401

Log in with the username admin and the ADMIN_PASSWORD you set. If you've lost the password, set a new one with sinch secrets add ADMIN_PASSWORD and deploy again.

Clean up

Delete the function when you're done:

sinch functions delete YOUR_FUNCTION_ID

The function ID is in .env as FUNCTION_ID, and in the output of sinch functions list. Deleting the function also deletes the Voice API v2 service that init created. Release the number separately, so you stop paying for it:

sinch numbers active release YOUR_PHONE_NUMBER

The number is VOICE_FROM_NUMBER in .env. A released number stays in sinch numbers active list until the end of its billing period. If you added the secrets with sinch secrets add, remove them with sinch secrets delete OPENAI_API_KEY and sinch secrets delete ADMIN_PASSWORD.

Next steps

Start by pointing check_availability and book_table at your real booking system, then call it with the questions your customers actually ask. To compare voices and latency, the Gemini Live, Grok, and Deepgram templates take the same realtimeAgent options, with that vendor's API key as the secret.

Additional resources

What would you put behind a GPT-Live phone number first? Tell me in the comments.

Originally published on the Sinch blog.

Check a Phone Number Before You Send an OTP

Gunnar Grosch — Tue, 03 Nov 2026 13:02:19 +0000

In Verify phone numbers with the Sinch Verification API, an approval callback decides whether a code goes out, based on the calling code and how often a number asks. That policy doesn't know what kind of line it's sending to. The Sinch Number Lookup API can: One call returns the line type and the carrier of a number. This post puts that call in front of the verification start. Mobile numbers get an SMS, landlines get a phone call, and numbers Lookup has no record of are blocked. For a VoIP number the code returns a challenge decision and stops, because the challenge itself, such as a CAPTCHA, belongs to your signup flow. You run everything from the command line, and the decision function is tested without a phone.

You'll need

The Sinch account and Verification app from the previous post, with its application key and secret
Phone call verification enabled on that app, if landlines should get a code
The project ID and an access key for the same project, from Settings and Access keys in the Sinch Build Dashboard
Node.js 22 or later, and a phone that can receive SMS

Verifications are billable, so test with your own number. The code was tested with @sinch/sdk-core 1.6.0 on Node.js 24.

If the Verification app still has the Callback URL from the previous post, keep that server running or clear the field, because every start needs an answer from it. Clearing it also turns off that post's approval callback, so set it again later if you rely on it.

What Lookup tells you

The default feature, LineType, returns a line object with a type and, for most numbers, the carrier. type is Landline, Mobile, VoIP, Special, Freephone, or Other. The guidance on combining Lookup and Verification maps those types to a method: A landline can't receive SMS, so use a voice call; a mobile number can take either; and a VoIP number carries a higher fraud risk, so add a CAPTCHA first. The code follows that table and covers the cases it leaves open.

Line type is available worldwide, but it's corrected for numbers that moved to another carrier only in the US and Canada, so a ported number elsewhere can show its old type. Looking up Canadian numbers also requires a CLNPC license, which the overview describes.

Lookup also has SIM swap detection (beta, US and Canada, needs carrier approval) and VoIP detection (alpha), each enabled per project on request. The decision function reads both when they're in a response. The code here requests line type only, so it runs on any project with Lookup access. Each feature in a response carries its own error. In testing, a feature that isn't enabled for a project came back inside an HTTP 200 with an error object, such as {"status":100,"title":"Feature Disabled"}. The code treats that as no signal.

Set up Lookup access

In the Sinch Build Dashboard, open Number Lookup and then Access Requirements.
Select Submit use cases and declare what you use line type for. Until you do, Lookup returns HTTP 403 with "Line type use cases not specified."
Under Settings and Access keys, create an access key and copy the key ID and secret.

The Number Lookup terms list fraud prevention, identity verification, and validating a phone number among the allowed uses, which covers checking a number before you send it a code.

Lookup takes the project access key, and the SDK turns it into an OAuth token for you. Verification takes the application key and secret, and the SDK signs each request with them. Store all five as environment variables:

export SINCH_PROJECT_ID=YOUR_PROJECT_ID
export SINCH_KEY_ID=YOUR_ACCESS_KEY_ID
export SINCH_KEY_SECRET=YOUR_ACCESS_KEY_SECRET
export SINCH_APP_KEY=YOUR_SINCH_APP_KEY
export SINCH_APP_SECRET=YOUR_SINCH_APP_SECRET

Create the project

Every file you need is on this page. Create the project and install the dependencies:

mkdir sinch-lookup-gate && cd sinch-lookup-gate
mkdir -p src scripts test
npm init -y
npm pkg set type=module
npm install @sinch/sdk-core@1.6.0
npm install --save-dev typescript tsx vitest @types/node

You'll end up with this:

sinch-lookup-gate/
  tsconfig.json
  src/        env.ts, types.ts, decide.ts, lookup.ts, verify.ts, gate.ts
  scripts/    lookup.ts, check.ts, report.ts
  test/       decide.test.ts

The decision function and its tests need no credentials. If you only want those, create tsconfig.json, then skip to Write the decision function.

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src", "scripts", "test"]
}

Create src/env.ts. It reads the credentials and builds the SDK clients:

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

export interface SinchCredentials {
  projectId: string;
  keyId: string;
  keySecret: string;
  /** Verification application key and secret. Only needed to start or report verifications. */
  applicationKey?: string;
  applicationSecret?: string;
}

/** The SDK's own retry is off because lookup.ts retries. `logger: null` stops it printing failed requests. */
const createSinchClient = (credentials: SinchCredentials, timeoutSeconds: number): SinchClient =>
  new SinchClient({ ...credentials, retryPolicy: RetryPolicy.NONE, timeoutSeconds, logger: null });

/** Lookup fails fast, because the gate's failure mode handles an outage. Three attempts stay under seven seconds. */
export const createLookupClient = (credentials: SinchCredentials) => createSinchClient(credentials, 2).numberLookup;

/** A start that times out on your side may still have been sent, so Verification gets more time. */
export const createVerificationClient = (credentials: SinchCredentials) =>
  createSinchClient(credentials, 10).verification;

export const requireEnv = (name: string): string => {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing environment variable ${name}`);
  }
  return value;
};

export const credentialsFromEnv = (): SinchCredentials => {
  const applicationKey = process.env["SINCH_APP_KEY"];
  const applicationSecret = process.env["SINCH_APP_SECRET"];
  return {
    projectId: requireEnv("SINCH_PROJECT_ID"),
    keyId: requireEnv("SINCH_KEY_ID"),
    keySecret: requireEnv("SINCH_KEY_SECRET"),
    ...(applicationKey && applicationSecret ? { applicationKey, applicationSecret } : {}),
  };
};

/** For code that starts or reports verifications: The application key and secret are required. */
export const verificationCredentialsFromEnv = (): SinchCredentials => {
  const credentials = credentialsFromEnv();
  if (!credentials.applicationKey || !credentials.applicationSecret) {
    throw new Error("Missing environment variables SINCH_APP_KEY and SINCH_APP_SECRET");
  }
  return credentials;
};

The SDK retries HTTP 429 on its own, but src/lookup.ts retries more than that, so the SDK's retry is off to keep one policy. The two clients get different timeouts instead of the 60-second default. Lookup gets two seconds per request, because the gate's failure mode handles an outage. In testing, every lookup finished well within that, including the first one with its OAuth token. Verification gets 10 seconds, because a start that times out on your side may still have gone through, and the user would get a code your app reported as failed.

Check your access

Create scripts/lookup.ts. It looks up one number and prints the raw response:

import { createLookupClient, credentialsFromEnv } from "../src/env.js";

const phoneNumber = process.argv[2];
if (!phoneNumber) {
  console.error("Usage: npx tsx scripts/lookup.ts +46701234567");
  process.exit(1);
}

const lookupClient = createLookupClient(credentialsFromEnv());

try {
  const result = await lookupClient.lookup({
    numberLookupRequestBody: { number: phoneNumber, features: ["LineType"] },
  });
  console.log(JSON.stringify(result, null, 2));
} catch (error) {
  // The SDK throws with the HTTP status in statusCode and the body as a JSON string in data.
  const { statusCode, data, message } = error as { statusCode?: number; data?: string; message?: string };
  console.error(statusCode ? `Lookup failed with HTTP ${statusCode}: ${data}` : `Lookup failed: ${message}`);
  process.exitCode = 1;
}

Run it with your own number in E.164 format:

npx tsx scripts/lookup.ts YOUR_PHONE_NUMBER

For a mobile number you should see something like:

{
  "countryCode": "SE",
  "traceId": "ba2bf0b429267927ce2908d9acfc1cdb",
  "number": "+46701234567",
  "line": {
    "carrier": "Telia Sverige AB",
    "type": "Mobile",
    "mobileCountryCode": "240",
    "mobileNetworkCode": "01"
  }
}

A 403 with "Line type use cases not specified." means the declaration hasn't applied yet. See Troubleshooting.

Write the decision function

Create src/types.ts. It describes the parts of a response the code reads, and the three decisions:

/**
 * The parts of a Number Lookup response this project reads. Every field is optional: a feature
 * that isn't enabled returns an `error` instead of data, and many numbers leave out most `line`
 * fields. The SDK's NumberLookupResponse fits this shape.
 */
export interface LookupResult {
  traceId?: string;
  line?: { carrier?: string; type?: string; error?: unknown };
  simSwap?: { swapped?: boolean; error?: unknown };
  voIPDetection?: { probability?: string; error?: unknown };
}

export type VerificationMethod = "sms" | "callout";

export type Decision =
  | { action: "block"; reason: string }
  | { action: "step-up"; reason: string }
  | { action: "send"; method: VerificationMethod; reason: string };

Create src/decide.ts. It turns a response into a decision and does no I/O:

import type { Decision, LookupResult } from "./types.js";

const STEP_UP_LINE_TYPES = new Set(["VoIP", "Special", "Freephone", "Other"]);

/** Turns a Lookup response into a decision. A feature that returned an `error` carries no signal. */
export const decide = ({ line, simSwap, voIPDetection }: LookupResult): Decision => {
  if (simSwap && !simSwap.error && simSwap.swapped === true) {
    return { action: "step-up", reason: "SIM swap detected" };
  }
  const probability = voIPDetection && !voIPDetection.error ? voIPDetection.probability : undefined;
  if (probability === "Likely" || probability === "High") {
    return { action: "step-up", reason: `VoIP probability ${probability}` };
  }

  const lineType = line && !line.error ? line.type : undefined;
  if (lineType === "Landline") {
    return { action: "send", method: "callout", reason: "landline cannot receive SMS" };
  }
  if (lineType === "Mobile") {
    return { action: "send", method: "sms", reason: "mobile line" };
  }
  if (lineType !== undefined && STEP_UP_LINE_TYPES.has(lineType)) {
    return { action: "step-up", reason: `line type ${lineType}` };
  }
  // No usable line type, or one this code doesn't know: send an SMS, as you would without Lookup.
  return { action: "send", method: "sms", reason: "no line type signal" };
};

A SIM swap or a high VoIP probability asks for a challenge first. Then the line type picks the method: A phone call for a landline, an SMS for a mobile number, and a challenge for VoIP and the less common types. Without a usable line type, the code sends an SMS, as you would without Lookup.

step-up means "don't send yet", and the reason says why. The right challenge depends on the signal. A CAPTCHA, which the Sinch guidance suggests for VoIP numbers, checks that a person is there. A SIM swap raises a different question: Whether the person holding the phone now is the account holder. A CAPTCHA can't answer that, so for an existing account, use a factor that doesn't depend on the phone number, such as a confirmation email or a session the user already has.

Test it without a phone

Create test/decide.test.ts. The first three responses were captured from Lookup, with fictional numbers:

import { describe, expect, it } from "vitest";
import { decide } from "../src/decide.js";

// Captured Lookup responses, with the numbers replaced by fictional ones.
const seMobile = {
  countryCode: "SE",
  traceId: "a10075fd5f248094a3674f203cc0f496",
  number: "+46701234567",
  line: { carrier: "Telia Sverige AB", type: "Mobile", mobileCountryCode: "240", mobileNetworkCode: "01" },
};
const usVoip = {
  countryCode: "US",
  traceId: "3c52b29db9cf8885002e85872f387149",
  number: "+12025550100",
  line: { carrier: "Sinch Voice", type: "VoIP" },
};
const gbLandline = {
  countryCode: "GB",
  traceId: "e61554f6b76aaf759ad7cf729be283e9",
  number: "+441632960123",
  line: { carrier: "DIDWW Ireland Limited", type: "Landline" },
};

describe("decide", () => {
  it("should send an SMS to a mobile line", () => {
    expect(decide(seMobile)).toEqual({ action: "send", method: "sms", reason: "mobile line" });
  });

  it("should call a landline", () => {
    expect(decide(gbLandline)).toEqual({ action: "send", method: "callout", reason: "landline cannot receive SMS" });
  });

  it("should step up a VoIP line", () => {
    expect(decide(usVoip)).toEqual({ action: "step-up", reason: "line type VoIP" });
  });

  it.each(["Special", "Freephone", "Other"])("should step up line type %s", (type) => {
    expect(decide({ line: { type } }).action).toBe("step-up");
  });

  it("should step up after a SIM swap", () => {
    expect(decide({ ...seMobile, simSwap: { swapped: true } })).toEqual({
      action: "step-up",
      reason: "SIM swap detected",
    });
  });

  it.each(["Likely", "High"])("should step up for VoIP probability %s", (probability) => {
    expect(decide({ ...seMobile, voIPDetection: { probability } }).action).toBe("step-up");
  });

  it("should ignore features that returned an error", () => {
    const featureDisabled = { status: 100, title: "Feature Disabled" };
    const result = { ...seMobile, simSwap: { error: featureDisabled }, voIPDetection: { error: featureDisabled } };
    expect(decide(result).action).toBe("send");
  });

  it("should send an SMS when there's no usable line type", () => {
    expect(decide({})).toEqual({ action: "send", method: "sms", reason: "no line type signal" });
  });
});

Run the tests:

npx vitest run

You should see:

 Test Files  1 passed (1)
      Tests  11 passed (11)

These tests cover the decision function only. The version I tested also has mocked tests for the retries, the gate, and the verification start, which this post leaves out.

Call Lookup

Create src/lookup.ts. It calls Lookup, retries what can succeed on a second try, and turns a 404 into an error of its own:

import type { LookupResult } from "./types.js";

/** The part of the SDK's `sinch.numberLookup` that this project uses. */
export interface LookupClient {
  lookup(data: { numberLookupRequestBody: { number: string; features?: string[] } }): Promise<LookupResult>;
}

/** Lookup gave no answer after the retries. */
export class LookupUnavailableError extends Error {}

/** Lookup returned 404: the number isn't in its data set. */
export class NumberNotFoundError extends Error {}

export interface RetryOptions {
  maxAttempts: number;
  baseDelayMs: number;
  sleep?: (delayMs: number) => Promise<void>;
}

export const DEFAULT_RETRY: RetryOptions = { maxAttempts: 3, baseDelayMs: 200 };

/** The SDK's RequestFailedError has the HTTP status in `statusCode`. */
export const getStatusCode = (error: unknown): number | undefined => {
  const statusCode = (error as { statusCode?: unknown } | null)?.statusCode;
  return typeof statusCode === "number" ? statusCode : undefined;
};

/** The SDK's RequestFailedError has the response body as a JSON string in `data`. */
export const getErrorBody = (error: unknown): Record<string, unknown> | undefined => {
  const data = (error as { data?: unknown } | null)?.data;
  if (typeof data !== "string") {
    return undefined;
  }
  try {
    const body: unknown = JSON.parse(data);
    return typeof body === "object" && body !== null ? (body as Record<string, unknown>) : undefined;
  } catch {
    return undefined; // Not JSON: the error isn't recognized, so it isn't retried.
  }
};

/**
 * Retry 429, 5xx, and errors without a status (timeouts and network failures). Of the 403s, only
 * retry undeclared use cases: A new declaration can take a few minutes to apply.
 */
const isRetryable = (error: unknown): boolean => {
  const statusCode = getStatusCode(error);
  if (statusCode === 403) {
    return getErrorBody(error)?.["title"] === "Line type use cases not specified.";
  }
  return statusCode === undefined || statusCode === 429 || statusCode >= 500;
};

export const lookupNumber = async (
  client: LookupClient,
  phoneNumber: string,
  features: string[] = ["LineType"],
  retry: RetryOptions = DEFAULT_RETRY,
): Promise<LookupResult> => {
  const sleep = retry.sleep ?? ((delayMs: number) => new Promise<void>((resolve) => setTimeout(resolve, delayMs)));
  let lastError: unknown;

  for (let attempt = 1; attempt <= retry.maxAttempts; attempt += 1) {
    try {
      return await client.lookup({ numberLookupRequestBody: { number: phoneNumber, features } });
    } catch (error) {
      if (getStatusCode(error) === 404) {
        throw new NumberNotFoundError("Number not found", { cause: error });
      }
      if (!isRetryable(error)) {
        throw error;
      }
      lastError = error;
      if (attempt < retry.maxAttempts) {
        await sleep(retry.baseDelayMs * 2 ** (attempt - 1));
      }
    }
  }
  throw new LookupUnavailableError(`Lookup unavailable after ${retry.maxAttempts} attempts`, { cause: lastError });
};

A timeout or a network failure throws without a statusCode. HTTP 429, 5xx, timeouts, network errors, and the 403 for undeclared use cases are retried. HTTP 400 for a malformed number, 401 for a wrong key, and the other 403s, for a disabled country or feature, won't change on a retry, so they stop right away. The three 403s share a status code, so the code reads the title from the body to tell them apart.

Three attempts at up to two seconds each, plus 600 milliseconds of waiting, put the worst case for one lookup at about 6.6 seconds, and the first call also fetches an OAuth token. Lower maxAttempts if your signup needs a faster answer.

Start the verification

Create src/verify.ts. It starts an SMS or phone call verification, and wraps a failed start so the caller can tell a denial from an outage:

import { getErrorBody, getStatusCode } from "./lookup.js";
import type { VerificationMethod } from "./types.js";

type Identity = { type: "number"; endpoint: string };

/** The part of the SDK's `sinch.verification.verifications` that this project uses. */
export interface VerificationsClient {
  startSms(data: { startVerificationWithSmsRequestBody: { identity: Identity } }): Promise<{ id?: string }>;
  startPhoneCall(data: { startVerificationWithPhoneCallRequestBody: { identity: Identity } }): Promise<{ id?: string }>;
}

/** The start failed. `errorCode` is the Verification API's own code, for example 42202. */
export class VerificationStartError extends Error {
  readonly statusCode: number | undefined;
  readonly errorCode: number | undefined;

  constructor(error: unknown) {
    const statusCode = getStatusCode(error);
    const errorCode = getErrorBody(error)?.["errorCode"];
    super(`Verification start failed: HTTP ${statusCode ?? "none"}, error code ${String(errorCode ?? "none")}`, {
      cause: error,
    });
    this.statusCode = statusCode;
    this.errorCode = typeof errorCode === "number" ? errorCode : undefined;
  }

  /** Error code 40303: the approval callback denied the start, or fraud protection stopped it. */
  get denied(): boolean {
    return this.errorCode === 40303;
  }
}

export type StartVerification = (
  phoneNumber: string,
  method: VerificationMethod,
) => Promise<{ verificationId: string | undefined }>;

export const createStartVerification =
  (client: VerificationsClient): StartVerification =>
  async (phoneNumber, method) => {
    const identity: Identity = { type: "number", endpoint: phoneNumber };
    try {
      const response =
        method === "sms"
          ? await client.startSms({ startVerificationWithSmsRequestBody: { identity } })
          : await client.startPhoneCall({ startVerificationWithPhoneCallRequestBody: { identity } });
      return { verificationId: response.id };
    } catch (error) {
      throw new VerificationStartError(error);
    }
  };

Create src/gate.ts. It validates the number, looks it up, decides, and starts a verification when the decision is to send:

import { decide } from "./decide.js";
import { LookupUnavailableError, NumberNotFoundError } from "./lookup.js";
import type { Decision, LookupResult } from "./types.js";
import { VerificationStartError, type StartVerification } from "./verify.js";

export type FailureMode = "fail-open" | "fail-closed";

export class InvalidPhoneNumberError extends Error {}

export interface GateDeps {
  lookup: (phoneNumber: string) => Promise<LookupResult>;
  /** Leave undefined for a dry run that only reports the decision. */
  startVerification?: StartVerification;
  failureMode: FailureMode;
}

export interface GateOutcome {
  decision: Decision;
  lookupFailed: boolean;
  lookupResult?: LookupResult;
  verificationId?: string;
}

export const isE164 = (phoneNumber: string): boolean => /^\+[1-9]\d{6,14}$/.test(phoneNumber);

/**
 * Looks the number up, decides, and starts a verification when the decision is "send".
 * A 404 from Lookup and a denied start become "block". When Lookup stays unavailable,
 * fail-open sends an SMS and fail-closed rethrows. Every other error reaches the caller.
 */
export const gate = async (phoneNumber: string, deps: GateDeps): Promise<GateOutcome> => {
  if (!isE164(phoneNumber)) {
    throw new InvalidPhoneNumberError(`Not an E.164 phone number: ${phoneNumber}`);
  }

  const outcome: GateOutcome = { decision: { action: "block", reason: "" }, lookupFailed: false };
  try {
    outcome.lookupResult = await deps.lookup(phoneNumber);
    outcome.decision = decide(outcome.lookupResult);
  } catch (error) {
    if (error instanceof NumberNotFoundError) {
      outcome.decision = { action: "block", reason: "number not found" };
    } else if (error instanceof LookupUnavailableError && deps.failureMode === "fail-open") {
      outcome.lookupFailed = true;
      outcome.decision = { action: "send", method: "sms", reason: "lookup unavailable, failing open" };
    } else {
      throw error;
    }
  }

  if (outcome.decision.action === "send" && deps.startVerification) {
    try {
      const { verificationId } = await deps.startVerification(phoneNumber, outcome.decision.method);
      if (verificationId !== undefined) {
        outcome.verificationId = verificationId;
      }
    } catch (error) {
      if (!(error instanceof VerificationStartError && error.denied)) {
        throw error;
      }
      outcome.decision = { action: "block", reason: "verification start denied" };
    }
  }
  return outcome;
};

Two errors become block decisions. A 404 means the number isn't in the Lookup data set, and this code treats that as a reason not to send. In testing, numbers in ranges set aside for fiction returned 404. A start that fails with error code 40303 is blocked too: Your approval callback denied it, or fraud protection stopped it. Every other error reaches the caller.

Run it

Create scripts/check.ts. It runs the gate for one number and prints the outcome. It starts a verification only when you pass --send:

import {
  createLookupClient,
  createVerificationClient,
  credentialsFromEnv,
  verificationCredentialsFromEnv,
} from "../src/env.js";
import { gate } from "../src/gate.js";
import { lookupNumber } from "../src/lookup.js";
import { createStartVerification } from "../src/verify.js";

const [phoneNumber, ...flags] = process.argv.slice(2);
if (!phoneNumber) {
  console.error("Usage: npx tsx scripts/check.ts +46701234567 [--send] [--fail-closed]");
  process.exit(1);
}

// Starting a verification also needs the application key and secret.
const send = flags.includes("--send");
const credentials = send ? verificationCredentialsFromEnv() : credentialsFromEnv();
const lookupClient = createLookupClient(credentials);
const startVerification = send
  ? createStartVerification(createVerificationClient(credentials).verifications)
  : undefined;

try {
  const outcome = await gate(phoneNumber, {
    lookup: (number) => lookupNumber(lookupClient, number),
    ...(startVerification ? { startVerification } : {}),
    failureMode: flags.includes("--fail-closed") ? "fail-closed" : "fail-open",
  });
  const { decision, lookupFailed, lookupResult, verificationId } = outcome;
  const printed = { decision, lookupFailed, line: lookupResult?.line, traceId: lookupResult?.traceId, verificationId };
  console.log(JSON.stringify(printed, null, 2));
} catch (error) {
  console.error(error instanceof Error ? error.message : error);
  process.exitCode = 1;
}

Check your own number:

npx tsx scripts/check.ts YOUR_PHONE_NUMBER

For a mobile number you should see:

{
  "decision": {
    "action": "send",
    "method": "sms",
    "reason": "mobile line"
  },
  "lookupFailed": false,
  "line": {
    "carrier": "Telia Sverige AB",
    "type": "Mobile",
    "mobileCountryCode": "240",
    "mobileNetworkCode": "01"
  },
  "traceId": "4ca9dd249c2547c914ef623d3c032716"
}

A VoIP number gets a challenge, and a landline gets a phone call:

{
  "decision": {
    "action": "step-up",
    "reason": "line type VoIP"
  },
  "lookupFailed": false,
  "line": {
    "carrier": "Sinch Voice",
    "type": "VoIP"
  },
  "traceId": "7886cdb869cebc7f218d8024ab8a2d76"
}

{
  "decision": {
    "action": "send",
    "method": "callout",
    "reason": "landline cannot receive SMS"
  },
  "lookupFailed": false,
  "line": {
    "carrier": "DIDWW Ireland Limited",
    "type": "Landline"
  },
  "traceId": "ad30d8578ba9bd182f68e4cce0854a44"
}

+12025550123 is in a range set aside for fiction. In testing it returned 404, so it's blocked:

npx tsx scripts/check.ts +12025550123

{
  "decision": {
    "action": "block",
    "reason": "number not found"
  },
  "lookupFailed": false
}

To use SIM swap and VoIP detection once they're enabled for your project, request them in the lookup line of scripts/check.ts:

    lookup: (number) => lookupNumber(lookupClient, number, ["LineType", "SimSwap", "VoIPDetection"]),

A feature that returns an error leaves the decision to the other signals.

To send a real code, add --send. It needs SINCH_APP_KEY and SINCH_APP_SECRET too, and stops with a message if either is missing:

npx tsx scripts/check.ts YOUR_PHONE_NUMBER --send

You should see the same decision with a verificationId, and an SMS arrives:

{
  "decision": {
    "action": "send",
    "method": "sms",
    "reason": "mobile line"
  },
  "lookupFailed": false,
  "line": {
    "carrier": "Telia Sverige AB",
    "type": "Mobile",
    "mobileCountryCode": "240",
    "mobileNetworkCode": "01"
  },
  "traceId": "4bb8a902474ad56216ef42d56bab57a0",
  "verificationId": "01a12046-c7d4-83ab-367e-000000000000"
}

The CLI is a demonstration. A public signup endpoint still owns request limits, spend controls, the challenge state, and whether the verification completed. In that route, gate takes the place of the start call, and your code acts on the decision. The sketch assumes deps includes startVerification. Without it, gate is a dry run and returns send without starting anything:

const { decision, verificationId } = await gate(phoneNumber, deps);
if (decision.action === "send") {
  // A code is on its way. Keep verificationId for the report.
} else if (decision.action === "step-up") {
  // Show your challenge, and start the verification after it passes.
} else {
  // Blocked: Ask for another number.
}

The gate keeps no record of challenges, so the same number gets the same step-up until your flow handles it: Validate the challenge on your server, tie the result to the number and the signup attempt, and then start the verification with a method the number supports. Special, Freephone, and Other numbers take the same path.

Check the code

A verification ID means the code went out, not that the number is verified. Create scripts/report.ts. It reports the code from the SMS:

import { createVerificationClient, requireEnv, verificationCredentialsFromEnv } from "../src/env.js";

const verification = createVerificationClient(verificationCredentialsFromEnv());
const verificationId = requireEnv("VERIFICATION_ID");
const code = requireEnv("CODE");

try {
  const report = await verification.verifications.reportSmsById({
    id: verificationId,
    reportSmsVerificationByIdRequestBody: { sms: { code } },
  });
  // Continue the signup only when status is SUCCESSFUL.
  console.log("Report:", JSON.stringify(report));
} catch (error) {
  // A wrong code throws with HTTP 400 and error code 40003.
  const { statusCode, data, message } = error as { statusCode?: number; data?: string; message?: string };
  console.error(statusCode ? `Report failed with HTTP ${statusCode}: ${data}` : `Report failed: ${message}`);
  process.exitCode = 1;
}

Check the types of every file:

npx tsc --noEmit

You should see no output. Run the script with the ID from the output and the code from the SMS:

VERIFICATION_ID=YOUR_VERIFICATION_ID CODE=YOUR_SMS_CODE npx tsx scripts/report.ts

You should see:

Report: {"id":"01a12046-c7d4-83ab-367e-000000000000","method":"sms","status":"SUCCESSFUL"}

Continue the signup only when status is SUCCESSFUL. A phone call verification reports the spoken code with reportPhoneCallById, which the Other methods table in the previous post lists.

In my own run, a mobile number went through Lookup, the gate started an SMS verification, the code arrived, and reporting it returned SUCCESSFUL.

Design decisions

A few things I learned building this:

Fail open when Lookup is down

If Lookup stays unavailable after the retries, the gate can send an SMS without the check or refuse the signup. It sends by default, because a short Lookup outage shouldn't stop real users, and the verification still runs. Pass --fail-closed, or set failureMode to fail-closed in your own code, when sending to an unchecked number is worse than a failed signup. The setting covers an outage only:

What happens	`fail-open`	`fail-closed`
Lookup unavailable after three attempts	Sends an SMS	Stops with an error
A response without a usable line type, and no other signal asking for a challenge	Sends an SMS	Sends an SMS
HTTP 404 "Number not found."	Blocks	Blocks
HTTP 400, 401, or another 403	Stops with an error	Stops with an error

To stop sending when there's no line type data, change the last line of decide to return step-up. That applies in both modes, because decide doesn't know the failure mode.

Block only what Lookup can't find

A VoIP number can belong to a real person, and line type isn't corrected for ported numbers outside the US and Canada. That's why VoIP gets a challenge instead of a block, and why the only block based on Lookup is a 404. The trade-off is that a real number missing from the Lookup data set gets refused. If that costs you more than a wasted send, return step-up for it in src/gate.ts instead.

Retry only what a retry can fix

A 403 is normally permanent. The exception is "Line type use cases not specified." The code retries that one 403, so a lookup made while a new declaration is still applying gets another chance, and no other 403 is retried. One lookup is at most three requests, and each lookup happens right before the start call. Nothing is cached: A lookup takes a few hundred milliseconds, so there's little to gain, and check the Lookup terms before you keep results.

Troubleshooting

Lookup returns 403 with "Line type use cases not specified"

Declare your use cases under Number Lookup and Access Requirements. A new declaration can take a few minutes to apply. Wait and run the check again.

Every request fails with HTTP 401

Lookup uses the project access key, not the Verification app's key. Check SINCH_PROJECT_ID, SINCH_KEY_ID, and SINCH_KEY_SECRET.

The start fails with error code 42202

In testing, this meant the Verification app had a Callback URL that didn't answer. Start the callback server from the previous post, or clear the field and give it a few minutes to apply.

The start fails with error code 42901

The Verification API limits how often you can start a verification for the same number. In testing, a second start for the same number within seconds returned 429 with error code 42901. Wait before you try again.

A landline fails with error code 40001

The message lists the methods enabled for your app. Contact Sinch to enable phone call verification, or return step-up for landlines in src/decide.ts.

Clean up

If you created an access key only for this post, delete it under Settings and Access keys. If you cleared the Callback URL and rely on the approval callback, set it again.

Next steps

The gate covers the verifications your backend starts. Verifications started from the mobile SDKs skip it, and the approval callback from the previous post is where you can catch them. The callback answers only allow or deny, so treat step-up and block as deny there, and give the lookup a shorter deadline than 6.6 seconds, because the callback has about 15 seconds for everything it does.

Additional resources

How does your signup flow handle VoIP numbers today, and would you fail open or closed when Lookup is down? Let me know in the comments.

Verify Phone Numbers with the Sinch Verification API

Gunnar Grosch — Tue, 03 Nov 2026 13:01:32 +0000

Before the Sinch Verification API sends a verification code, it can ask your server whether to send it. That matters if your signup form passes the phone number straight to a start call, because then anyone who can reach the form can make your backend text any number they type. This post builds the callback that answers, approving the numbers you serve and denying the rest, together with the TypeScript that starts and checks verifications. You can run and test all of it on your own machine, and put it behind any HTTPS host.

You'll need

A Sinch account and a Verification app in the Sinch Build Dashboard
The application key and application secret of that app (they differ from your project access keys)
Node.js 22 or later
A phone that can receive SMS, and its number in E.164 format, for example +46701234567
A tunnel to your local server to receive real callbacks, for example ngrok

Each verification is billable, and the status response reports the price charged, so test with your own number.

This takes about 30 minutes. The code was written and tested with @sinch/sdk-core 1.6.0 on Node.js 24 and Node.js 22.

This post uses SMS. The start verification endpoint lists five method values, and the Other methods section at the end compares them and shows the SDK calls for each.

Set up the Verification app

In the Sinch Build Dashboard, open Verification and create an app.
Copy the application key and the application secret.
Under Minimal Authentication Level, select Application. The Sinch Verification API rejects requests that use a weaker method, and the SDK signs every request with your key and secret, which is what this level expects.
Leave the Callback URL empty for now. You set it later in this post.

In your terminal, store the credentials and your test number as environment variables so they stay out of the code:

export SINCH_APP_KEY=YOUR_SINCH_APP_KEY
export SINCH_APP_SECRET=YOUR_SINCH_APP_SECRET
export PHONE_NUMBER=YOUR_PHONE_NUMBER_IN_E164_FORMAT

Create the project

Every file you need is on this page. Create a project directory and install the dependencies:

mkdir sinch-verification && cd sinch-verification
npm init -y
npm pkg set type=module
npm install @sinch/sdk-core@1.6.0 express
npm install --save-dev typescript tsx @types/node @types/express

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src", "scripts"]
}

tsx runs TypeScript without checking types, so you run the compiler yourself later in this post to catch type errors.

Create src/env.ts. It reads a required environment variable and fails with a clear message when one is missing:

/** Reads a required environment variable and fails with a clear message when it is missing. */
export const requireEnv = (name: string): string => {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing environment variable ${name}`);
  }
  return value;
};

Start and check a verification

A verification has two calls. You start it, which sends the code, and you report the code the user typed. The scripts below call the SDK directly and stand in for your signup and login routes. The SDK throws a RequestFailedError for a failed request, with the HTTP status in statusCode and the JSON body as a string in data. For the SDK basics, see the Node.js quickstart.

Start a verification

Create scripts/start.ts. It starts an SMS verification for PHONE_NUMBER and prints its status:

import { SinchClient } from "@sinch/sdk-core";
import { requireEnv } from "../src/env.js";

const verification = new SinchClient({
  applicationKey: requireEnv("SINCH_APP_KEY"),
  applicationSecret: requireEnv("SINCH_APP_SECRET"),
}).verification;
const phoneNumber = requireEnv("PHONE_NUMBER");

try {
  const started = await verification.verifications.startSms({
    startVerificationWithSmsRequestBody: {
      identity: { type: "number", endpoint: phoneNumber },
      reference: `demo-${Date.now()}`,
    },
  });
  if (!started.id) throw new Error("Sinch returned no verification ID");

  console.log(`Started verification ${started.id}`);
  const status = await verification.verificationStatus.getById({ id: started.id });
  console.log("Status:", JSON.stringify(status));
} catch (error) {
  // The SDK throws a RequestFailedError. A request that your callback denies fails with HTTP 403.
  const { statusCode, data, message } = error as { statusCode?: number; data?: string; message?: string };
  console.error(statusCode ? `Start failed with HTTP ${statusCode}: ${data}` : `Start failed: ${message}`);
  process.exitCode = 1;
}

The reference ties the verification to something in your own system, such as a signup ID, and it must be unique for each verification. Run the script:

npx tsx scripts/start.ts

You should see the verification ID and a PENDING status, and an SMS arrives on your phone:

Started verification 01a0f775-e360-c702-f711-000000000000
Status: {"id":"01a0f775-e360-c702-f711-000000000000","method":"sms","status":"PENDING","reference":"demo-1790858093271","source":"","identity":{"type":"number","endpoint":"+46701234567"},"countryId":"SE"}

Check the code the user typed

Create scripts/report.ts. It reports the code the user typed and prints the result:

import { SinchClient } from "@sinch/sdk-core";
import { requireEnv } from "../src/env.js";

const verification = new SinchClient({
  applicationKey: requireEnv("SINCH_APP_KEY"),
  applicationSecret: requireEnv("SINCH_APP_SECRET"),
}).verification;
const verificationId = requireEnv("VERIFICATION_ID");
const code = requireEnv("CODE");

try {
  const report = await verification.verifications.reportSmsById({
    id: verificationId,
    reportSmsVerificationByIdRequestBody: { sms: { code } },
  });
  console.log("Report:", JSON.stringify(report));
} catch (error) {
  // A wrong code throws with HTTP 400 and error code 40003.
  const { statusCode, data, message } = error as { statusCode?: number; data?: string; message?: string };
  console.error(statusCode ? `Report failed with HTTP ${statusCode}: ${data}` : `Report failed: ${message}`);
  process.exitCode = 1;
}

Run it with the verification ID from the previous step and the code from the SMS:

VERIFICATION_ID=YOUR_VERIFICATION_ID CODE=YOUR_SMS_CODE npx tsx scripts/report.ts

You should see:

Report: {"id":"01a0f775-e360-c702-f711-000000000000","method":"sms","status":"SUCCESSFUL","reference":"demo-1790858093271"}

Decide on status, not on the HTTP code, and use reason only as a hint for your logs. A wrong code is an expected result even though the SDK throws for it. It returns HTTP 400 with error code 40003:

Report failed with HTTP 400: {
  "errorCode": 40003,
  "message": "Invalid identity or code.",
  "reference": "0d3858ec-11f5-4192-91a5-a764da61b13a"
}

Set your own limit on attempts.

Add the approval callback

When you set a Callback URL on the app, Sinch sends a VerificationRequestEvent to it for each new verification, including the ones you start from your backend, and your answer decides whether the code goes out. The reply is {"action":"allow"} or {"action":"deny"}. Careless callback setup can expose you to artificial inflation of traffic, so the handler below checks every request instead of approving them all.

You can run these checks in your own start endpoint before you call Sinch, and if your backend is the only thing that starts verifications, that works. The callback covers what a check in your endpoint can't: Verifications started from the mobile SDKs, which require callbacks, and anything else that uses the same app credentials. It is also the gate Sinch enforces before a code is sent, so a request your callback doesn't approve never goes out.

Point the Verification app at your machine

Sinch needs a public HTTPS address for the callback. Give a change to the Callback URL a few minutes before you test it, so set it up first and write the code in the meantime. Any host that passes the request body to your handler unchanged works: A container, a virtual machine, or a serverless platform. During development, a tunnel to your local server is enough, as long as it needs no query parameters. With ngrok, run this in a second terminal:

ngrok http 3000

Copy the https:// forwarding address that ngrok prints. In the app settings, enter it in Callback URL, with the path /verification/callback at the end, and save. If the address changes when you restart the tunnel, update the Callback URL to match.

Don't start a real verification until your server is running. While a Callback URL is set, a start needs an answer from it.

Write the callback

Create src/policy.ts. It approves a request when the number starts with a calling code you serve, the number hasn't asked for too many codes recently, and the total across all numbers stays within a budget:

export interface PolicyOptions {
  /** Calling-code prefixes you serve, for example ["+46", "+47"]. */
  allowedCallingCodes: string[];
  /** Most starts allowed for one number in the window. */
  maxStartsPerWindow: number;
  /** Most starts allowed across all numbers in the window. Set it well above normal traffic. */
  maxStartsPerWindowTotal: number;
  windowMs: number;
  now?: () => number;
}

export type Decision = "allow" | "deny";

/**
 * A small approval policy: a destination allowlist, a per-number limit, and a total budget.
 * The counters live in memory, so they only cover one running instance. Use a shared store
 * such as DynamoDB or Redis when more than one instance serves callbacks.
 */
export const createPolicy = (options: PolicyOptions) => {
  const now = options.now ?? Date.now;
  const startsByNumber = new Map<string, number[]>();
  let allStarts: number[] = [];
  let lastSweepAt = now();

  // Forget numbers that have no recent starts, so the map doesn't grow without bound.
  const sweep = (cutoff: number) => {
    for (const [phoneNumber, starts] of startsByNumber) {
      const recentStarts = starts.filter((startedAt) => startedAt > cutoff);
      if (recentStarts.length === 0) {
        startsByNumber.delete(phoneNumber);
      } else {
        startsByNumber.set(phoneNumber, recentStarts);
      }
    }
    lastSweepAt = now();
  };

  return (phoneNumber: string): Decision => {
    const cutoff = now() - options.windowMs;
    if (now() - lastSweepAt >= options.windowMs) {
      sweep(cutoff);
    }

    if (!options.allowedCallingCodes.some((prefix) => phoneNumber.startsWith(prefix))) {
      return "deny";
    }

    const recentStarts = (startsByNumber.get(phoneNumber) ?? []).filter((startedAt) => startedAt > cutoff);
    allStarts = allStarts.filter((startedAt) => startedAt > cutoff);
    if (recentStarts.length >= options.maxStartsPerWindow || allStarts.length >= options.maxStartsPerWindowTotal) {
      return "deny";
    }

    startsByNumber.set(phoneNumber, [...recentStarts, now()]);
    allStarts.push(now());
    return "allow";
  };
};

A limit per number doesn't stop someone who rotates through many numbers, so the policy also keeps a total budget across all numbers. Using the budget up blocks legitimate signups until the window resets, so set it well above your normal traffic. The request event also carries a price, which you can use to deny unusually expensive destinations.

Create src/callback.ts. It validates the signature, checks that the request is recent, and answers the event:

import { VerificationCallbackWebhooks } from "@sinch/sdk-core";
import type { Decision } from "./policy.js";

export interface CallbackRequest {
  /** The exact bytes Sinch sent, as a string. Parsing and re-serializing changes them. */
  rawBody: string;
  /** Header names in lowercase. */
  headers: Record<string, string | undefined>;
  method: string;
  /** The path of the Callback URL, for example /verification/callback. */
  path: string;
}

export interface CallbackConfig {
  applicationKey: string;
  applicationSecret: string;
  /** Called with the phone number of each VerificationRequestEvent. */
  decide: (phoneNumber: string) => Decision;
  now?: () => number;
  maxClockSkewMs?: number;
}

export interface CallbackResponse {
  statusCode: number;
  body: Record<string, unknown>;
}

const DEFAULT_MAX_CLOCK_SKEW_MS = 5 * 60 * 1000;

const isFresh = (timestamp: string | undefined, now: number, maxSkewMs: number): boolean => {
  if (!timestamp) return false;
  const sentAt = Date.parse(timestamp);
  return Number.isFinite(sentAt) && Math.abs(now - sentAt) <= maxSkewMs;
};

/**
 * Validates a Verification callback and answers it. A VerificationRequestEvent needs
 * {"action":"allow"} or {"action":"deny"}, so answer quickly. Other events get 200.
 */
export const handleVerificationCallback = (
  request: CallbackRequest,
  config: CallbackConfig,
): CallbackResponse => {
  const now = (config.now ?? Date.now)();
  const webhooks = new VerificationCallbackWebhooks({
    applicationKey: config.applicationKey,
    applicationSecret: config.applicationSecret,
  });

  // The SDK validator also accepts Basic auth with the key and secret in clear text.
  // Sinch signs callbacks with the Application scheme, so accept nothing else.
  const scheme = request.headers["authorization"]?.split(" ")[0]?.toLowerCase();
  const signedByApplication =
    scheme === "application" &&
    webhooks.validateAuthenticationHeader(request.headers, request.rawBody, request.path, request.method);

  if (!signedByApplication || !isFresh(request.headers["x-timestamp"], now, config.maxClockSkewMs ?? DEFAULT_MAX_CLOCK_SKEW_MS)) {
    return { statusCode: 401, body: { error: "Invalid signature" } };
  }

  let event;
  try {
    event = webhooks.parseEvent(JSON.parse(request.rawBody));
  } catch {
    return { statusCode: 400, body: { error: "Unrecognized event" } };
  }

  if (event.event === "VerificationRequestEvent") {
    return { statusCode: 200, body: { action: config.decide(event.identity.endpoint) } };
  }
  return { statusCode: 200, body: {} };
};

The handler takes the raw request body as a string because the signature covers the exact bytes Sinch sent. The Design decisions section explains why that matters. Sinch signs callbacks the same way it signs API requests, which the callback signing documentation describes, and the SDK's VerificationCallbackWebhooks class does the check.

Create src/server.ts. It wires the handler to Express, using express.raw so the body stays as bytes, and prints one line per callback without the phone number:

import express from "express";
import { handleVerificationCallback, type CallbackConfig } from "./callback.js";

/**
 * Express wiring. express.raw keeps the request body as the exact bytes Sinch sent,
 * which the signature check needs. express.json() would parse it and lose them.
 */
export const createApp = (config: CallbackConfig, callbackPath = "/verification/callback") => {
  const app = express();

  app.post(callbackPath, express.raw({ type: () => true }), (req, res) => {
    const headers: Record<string, string | undefined> = {};
    for (const [name, value] of Object.entries(req.headers)) {
      headers[name] = Array.isArray(value) ? value[0] : value;
    }

    const { statusCode, body } = handleVerificationCallback(
      {
        rawBody: Buffer.isBuffer(req.body) ? req.body.toString("utf8") : "",
        headers,
        method: req.method,
        path: req.path,
      },
      config,
    );
    // One line per callback, without the phone number, so you can see that Sinch reached you.
    console.log(JSON.stringify({ message: "callback handled", statusCode, action: body["action"] }));
    res.status(statusCode).json(body);
  });

  return app;
};

Create src/main.ts. It starts the server with a policy for your markets:

import { requireEnv } from "./env.js";
import { createPolicy } from "./policy.js";
import { createApp } from "./server.js";

const app = createApp({
  applicationKey: requireEnv("SINCH_APP_KEY"),
  applicationSecret: requireEnv("SINCH_APP_SECRET"),
  decide: createPolicy({
    // List the calling codes you serve. +1 covers the US, Canada, and other countries in the
    // North American Numbering Plan, so a US-only service should also check area codes.
    allowedCallingCodes: ["+46", "+47", "+45", "+358", "+1"],
    maxStartsPerWindow: 5,
    maxStartsPerWindowTotal: 1000, // Set this well above your normal traffic.
    windowMs: 10 * 60 * 1000,
  }),
});

const port = Number(process.env["PORT"] ?? 3000);
app.listen(port, () => console.log(`Listening on http://localhost:${port}/verification/callback`));

Check the types:

npx tsc --noEmit

You should see no output. Start the server:

npx tsx src/main.ts

You should see:

Listening on http://localhost:3000/verification/callback

Test the callback without Sinch

Create scripts/send-test-callback.ts. It builds a request event the way Sinch writes it, signs it with your secret, and posts it to the server:

import { createHash, createHmac } from "node:crypto";
import { requireEnv } from "../src/env.js";

const applicationKey = requireEnv("SINCH_APP_KEY");
const applicationSecret = requireEnv("SINCH_APP_SECRET");
const url = new URL(process.env["CALLBACK_URL"] ?? "http://localhost:3000/verification/callback");
const phoneNumber = process.argv[2] ?? "+46701234567";

// Written the way Sinch writes it, including numbers such as 0.0 that JSON.parse would change.
const rawBody =
  `{"price":{"currencyId":"EUR","amount":0.0367},"rate":{"currencyId":"EUR","amount":0.0},` +
  `"id":"test-verification-id","event":"VerificationRequestEvent","method":"sms",` +
  `"identity":{"verified":false,"type":"number","endpoint":"${phoneNumber}"},"reference":"test-reference"}`;

// Sign the way Sinch signs callbacks: HMAC-SHA256 over the method, the body hash, the content type,
// the timestamp header, and the path, using the base64-decoded application secret.
const contentType = "application/json; charset=utf-8";
const timestamp = new Date().toISOString();
const bodyHash = createHash("md5").update(Buffer.from(rawBody, "utf8")).digest("base64");
const stringToSign = `POST\n${bodyHash}\n${contentType}\nx-timestamp:${timestamp}\n${url.pathname}`;
const signature = createHmac("sha256", Buffer.from(applicationSecret, "base64"))
  .update(stringToSign)
  .digest("base64");

const response = await fetch(url, {
  method: "POST",
  headers: {
    "content-type": contentType,
    "x-timestamp": timestamp,
    authorization: `application ${applicationKey}:${signature}`,
  },
  body: rawBody,
});
console.log(response.status, await response.text());

In a second terminal, send a request for a number the policy serves:

npx tsx scripts/send-test-callback.ts +46701234567

You should see:

200 {"action":"allow"}

Send one for a calling code that isn't in the allowlist:

npx tsx scripts/send-test-callback.ts +447700900123

You should see:

200 {"action":"deny"}

A request signed with the wrong secret gets 401 {"error":"Invalid signature"}.

Try it with Sinch

By now the Callback URL has had time to apply. With the server and the tunnel running, start a verification:

npx tsx scripts/start.ts

The start works as before. The server prints one line for the request event, with the status code and the decision:

{"message":"callback handled","statusCode":200,"action":"allow"}

If no line appears, the Callback URL hasn't applied yet: The start still went out and the SMS still arrived, just without asking your server. Wait a little longer and start another verification. To see a deny, remove your calling code from the allowlist in src/main.ts, restart the server, and run the script again. You should see:

Start failed with HTTP 403: {
  "errorCode": 40303,
  "message": "Denied by callback.",
  "reference": "6a0bd2be-392a-4c86-9d9a-7799ae477443"
}

The server prints a line with "action":"deny", and no SMS is sent. When a verification finishes, Sinch also sends a VerificationResultEvent, which the handler answers with HTTP 200 and no action.

What you have now

You have a backend that starts SMS verifications and reads the result of a code check, and a callback that approves or denies every request before Sinch sends anything. In my own run, a start for an allowed number reached the endpoint as a real VerificationRequestEvent, the endpoint answered allow, the SMS arrived, the correct code returned SUCCESSFUL, and the endpoint received the VerificationResultEvent afterward.

Design decisions

A few things I learned building this:

Fallback is code you write

A start request takes one method, so falling back to another way of delivering the code is your code's job: Catch the start error and start the next method. Stop on errors where another method can't help, such as bad credentials, no credit, a duplicate reference, a denied or failing callback, and rate limiting. Each attempt is a new start, so it counts against the limit in your policy and replaces the previous verification. Keep that limit above the number of methods you try, or a user who asks to be called instead gets locked out.

Keep the callback fast and reliable

Sinch waits for your answer before it sends the code, so the callback sits in the signup path. In testing, a callback that returned an error status or took longer than about 15 seconds ended the verification as denied, and the start call failed with HTTP 422 and error code 42202. The result is that nothing goes out unless your endpoint says allow. Keep the handler small, answer from memory or a fast store, and make a deny a deliberate reply instead of an error. The counters in src/policy.ts live in memory, so they only count requests that one running instance sees. Use a shared store such as DynamoDB or Redis when more than one instance serves callbacks.

Validate the signature over the raw body

Sinch signs the exact request body, so validate the string you received. A body such as {"rate":{"amount":0.0}} changes when you parse it and write it back, because JSON.parse reads 0.0 as 0, and a signature computed over the changed body doesn't match. Request events can include numbers written this way. Express needs express.raw, as in src/server.ts. On other hosts, find the setting that hands your handler the raw string before any JSON parsing, and check that a proxy in front of it doesn't re-encode the body. The handler in src/callback.ts also accepts only the application scheme and rejects requests older than five minutes, so a replayed or downgraded request fails.

Treat each verification as single use

Mark a verification as used in your own store when it succeeds, so a login flow doesn't treat a second report of the same code as a new sign-in. Set your own limit on attempts, because a wrong code is an ordinary result and not a failure of the verification. A new start for the same number replaces the earlier verification, which matters for "send it again" buttons.

Other methods

The start request takes a method, and the start verification endpoint lists five values. Which methods you can use depends on how your app is set up, and Data must be enabled before you can use it. The SDK methods in the table are on verification.verifications, the object the scripts above use. Data is the exception, because the mobile SDKs run it.

Method	`method` value	What the user does	Start with	Report with
SMS	`sms`	Types the code from a text message	`startSms`	`reportSmsById`
Flash call	`flashcall`	Nothing on Android. On iOS and in JavaScript, enters the calling number.	`startFlashCall`	`reportFlashCallById`, with the full calling number from the call log as `cli`
Phone call	`callout`	Listens to the call and types the code	`startPhoneCall`	`reportPhoneCallById`, with the spoken code
Data	`seamless`	Nothing	The Android or iOS SDK	Nothing to report. The two steps become one, because the SDK completes the check over the device's mobile data connection. Read the outcome from the result event or the status calls.
WhatsApp	`whatsapp`	Types the code from a WhatsApp message	`startWhatsApp`	`reportWhatsAppById`, with the code

On Android, the SDK can intercept an SMS automatically, and iOS and JavaScript need manual entry. A phone call reads the code aloud with text-to-speech. A flash call is a missed call whose caller ID is the code, and its start response contains a cliFilter that identifies the call, plus interceptionTimeout and reportTimeout values. In my run both timeouts were 45 seconds. A mobile app can capture the incoming number and send it to your backend, or the user can type it.

Data verifies through the mobile carrier, needs mobile data on the device, and must be enabled for your app. Contact Sinch to enable it, and check availability for your destinations. Keep another method as a fallback. WhatsApp is listed as a method value on the start verification endpoint, so contact Sinch if it isn't enabled for your app. The mobile SDKs are where the client side matters most for Data and flash call, and the documentation covers them.

Troubleshooting

A request returns 403 with the message "Forbidden resource"

The app's Minimal Authentication Level is Application, so every request must be signed. Use the SDK, which signs each request, or sign requests as the signed request documentation describes.

A start returns 400 with the message "The 'method' can only be one of"

The method isn't enabled for your app yet. Use one of the methods the message lists, or contact Sinch to enable the one you need.

No callbacks arrive

Give a Callback URL change a few minutes. Check that the field shows your address and that your server printed a callback handled line for the start. Then send a signed test request with scripts/send-test-callback.ts to confirm the endpoint works. If that works, wait a little longer and start another verification.

A start returns 422 with error code 42202

In testing, this error meant Sinch didn't get a valid answer from the callback. Return HTTP 200 with {"action":"allow"} or {"action":"deny"} within about 15 seconds, and check the endpoint logs for 401 responses.

Signature validation fails on real callbacks but passes in your tests

Check two things. First, something may have parsed the body before the handler saw it: Pass the raw string to handleVerificationCallback. In Express, express.raw must run for the route, and express.json must not. Second, the signature covers the path of the URL you gave Sinch. If a proxy or gateway adds or strips a prefix before your server sees the request, pass handleVerificationCallback the path from the Callback URL instead of the path your server sees.

A start returns 409 with error code 40900

The reference is already in use. Use a unique reference for each verification.

Clean up

Stop the local server and the tunnel, and clear the Callback URL in the app settings so Sinch stops calling an address that no longer exists. While a Callback URL is set, Sinch calls it for every new verification, so remove the setting when you remove the endpoint.

Next steps

The Number Lookup API returns the line type of a number, which lets you screen out numbers that can't receive SMS before you start a verification.

Additional resources

Which verification methods does your app need, and where do you draw the line between approving and denying a request? Let me know in the comments.

Yells at Cloud, Episode 4: The Vulnpocalypse

Gunnar Grosch — Mon, 26 Oct 2026 23:51:48 +0000

Listen: YouTube · Spotify · Apple Podcasts

Summary

PHP is 31, runs most of the web, and finally made the front page of the Wall Street Journal. All it took was an unauthenticated remote code execution bug. Danielle opens with a goodbye: AWS is ending support for Infrastructure Composer, which grew out of Stackery, the startup she worked at. Chris walks through a week of vulnerabilities: an eMudhra CA private key that was the number 4, PHP2Shell and the Chainguard embargo fight, a Node.js RCE, and the Railway and TiDB breaches. Gunnar brings the one piece of good news, Lambda Web Functions, and asks whether serverless is still meant for humans to understand, or only for agents. And Ken looks at Claude Code agent teams and mods, which the docs say plainly aren't sandboxed.

Burst Mode: Danielle on Eric Mann's Longhorn PHP keynote, The Commit You Can't Take Back, and the day a PM added "destroy" to the dropdown. Chris on the crappy state of MCPs. Ken on recursive self-improvement and why you should write evals instead of prompts. And Gunnar on Mistral, which answered last episode's "are they still around?" with a trillion-parameter model named after a cat meme: Le Chonk.

Timestamps

Main topics

0:00: Intro, brought to you by PHP
0:35: Check-ins: retro gaming, an MCP gateway, ProductFest
3:49: Infrastructure Composer end of support (Danielle)
12:28: The Vulnpocalypse: eMudhra, PHP2Shell, Node.js and more (Chris)
29:57: Lambda Web Functions: is serverless still for humans? (Gunnar)
42:24: Claude is teamin' and modin' (Ken)

Burst Mode

52:06: Burst Mode
52:32: The Commit You Can't Take Back (Danielle)
54:53: The crappy state of MCPs (Chris)
57:03: Recursive self-improvement (Ken)
1:00:48: Mistral is still around: Le Chonk (Gunnar)
1:05:25: What we're looking forward to
1:08:32: Wrap

Links

Check-ins

Infrastructure Composer end of support

The Vulnpocalypse

Lambda Web Functions

Claude is teamin' and modin'

The Commit You Can't Take Back

The crappy state of MCPs

Recursive self-improvement

Mistral Large 4 (Le Chonk)

Wrap

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

Send Appointment Reminder Calls at Scale with Voice API v2

Gunnar Grosch — Thu, 01 Oct 2026 08:18:43 +0000

Reminder calls the day before help cut no-shows, but calling a list of customers is more work than calling one. You need a queue so you don't dial 500 numbers in the same second, a way to stop calling once the reminders are no longer useful, a plan for voicemail, and a way to tell afterwards who confirmed, who didn't answer, and who never got called at all.

Batch calling in Sinch Voice API v2 handles the queue for you. You send one request with the call flow and a list of recipients, and Sinch places the calls at the rate you set. This post builds an appointment reminder with it: Each customer hears their own name and time, a person gets a "press 1 to confirm" menu, a voicemail gets a short message, and every answer lands in your backend tagged with the appointment it belongs to. I ran the core flow against real calls while writing it.

Voice API v2 is in public preview. See Preview status before you plan a production rollout.

You'll need

A Sinch account and a project in the Sinch Build Dashboard
An access key ID and secret from the project's Access Keys page
A voice-capable number in the project
A Voice API v2 service
Node.js 24 or newer
The Sinch CLI, installed and logged in

Batch calls use the project's default Voice service unless you pass another serviceId.

You'll end up with two folders side by side:

reminder-webhook/         The Sinch Function that receives confirmations
  function.ts             You add the confirm handler here
  .env                    Gets REMINDER_SIGNING_SECRET= from sinch secrets add
appointment-reminders/    The scripts that send the batch and report on it
  package.json
  tsconfig.json
  sinch-client.ts         The shared Sinch client
  appointments.ts         The list of people to call
  reminder-flow.ts        The call flow
  send-reminders.ts       Validates the flow and starts the batch
  report.ts               Waits for the batch and prints each outcome

sinch functions init also generates other files in reminder-webhook. You only edit function.ts.

How batch calling works

Batch calling in Voice API v2 places one call per entry in a list, from a single request, at a rate you set.

Voice API v2 describes a call as a list of JSON commands called SVAML (Sinch Voice Application Markup Language): Dial this number, play this message, collect a key press. A batch is a normal Voice API v2 call request with a parameters array added. There's no separate "create batch" endpoint:

commands is one SVAML call flow. Any string in it can contain placeholders such as @name or @phoneNumber.
parameters is a list with one object per call. Sinch fills the placeholders from each object and queues one call session for it. Keys are 1 to 32 characters, every value is a string, and every entry needs a key for every placeholder the flow uses.
batchOptions controls pacing. maxCps caps how many calls start per second (1 to 1000) and ttlSeconds is how long Sinch keeps starting queued calls (1 to 10800, three hours). Anything not started by then expires.

The response gives you a batchId. With it you can read a summary of the batch, list its call sessions, or stop it. In the Node.js SDK these are sinchClient.voice.v2.batches.start, get, getDetails, and stop.

Deploy the confirmation endpoint

You'll build a small endpoint that records confirmations, a call flow that dials each customer and asks them to press 1 or 2, a script that sends the batch, and one that reports on the results.

When a customer presses 1 or 2, the call flow sends a POST to your endpoint and waits for the commands to play next. Build that endpoint first, so you have its URL for the rest of the post. Any public HTTPS endpoint works. Here it's a Sinch Function:

sinch functions init simple-voice-ivr --name reminder-webhook
cd reminder-webhook

init asks a few questions. Pick your Voice API v2 service, answer No to "Auto-configure voice integration on deploy" so deploying doesn't repoint that service's inbound webhook, and pick No database.

Appointment IDs are easy to guess, so the endpoint shouldn't accept a confirmation from anyone who finds its URL. For forgery protection, the send script signs each appointment ID and action with a secret, and the endpoint checks the signature. It refuses every request if the secret isn't set. Generate the secret and store it in your OS keychain from inside the function folder:

export REMINDER_SIGNING_SECRET=$(openssl rand -hex 32)
sinch secrets add REMINDER_SIGNING_SECRET "$REMINDER_SIGNING_SECRET"

secrets add also adds an empty REMINDER_SIGNING_SECRET= line to .env, which tells deploy to send the value along. Keep the variable exported in this shell: The send script uses the same secret.

init created function.ts in reminder-webhook. Every exported function in it becomes an HTTP endpoint named after the export, so exporting confirm gives you /confirm. Open function.ts, add the two import lines at the top, and add the confirm function at the end of the file:

import { createHmac, timingSafeEqual } from 'node:crypto';
import type { FunctionContext, FunctionRequest, FunctionResponse } from '@sinch/functions-runtime';

export async function confirm(_context: FunctionContext, request: FunctionRequest): Promise<FunctionResponse> {
  const { appointment, action, token } = request.query as { appointment?: string; action?: string; token?: string };
  if (!appointment || !token || (action !== 'confirm' && action !== 'reschedule')) {
    return { statusCode: 400, body: { error: 'appointment, action, and token are required' } };
  }

  const signingSecret = process.env.REMINDER_SIGNING_SECRET;
  if (!signingSecret) {
    console.error('REMINDER_SIGNING_SECRET is not set');
    return { statusCode: 500, body: { error: 'not configured' } };
  }

  const expected = createHmac('sha256', signingSecret).update(`${appointment}:${action}`).digest();
  const received = Buffer.from(token, 'hex');
  if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
    return { statusCode: 403, body: { error: 'invalid token' } };
  }

  // Update your scheduling system here. Keep it fast: the call waits for this response.
  console.info(`Appointment ${appointment}: ${action}`);

  const reply = action === 'confirm'
    ? 'Thanks, your appointment is confirmed. Goodbye.'
    : 'No problem. Please call us to pick a new time. Goodbye.';

  return {
    statusCode: 200,
    body: {
      commands: [
        {
          command: 'messages',
          messages: [{ type: 'SAY', say: { text: reply, voiceName: 'Emma' } }],
          events: { onFinish: [{ command: 'hangup' }] },
        },
      ],
    },
  };
}

Deploy it:

sinch functions deploy

Take the URL deploy prints and add /confirm. That's your CONFIRM_URL.

Once the batch runs, each key press arrives as a request like this one. The body has the full call record, with callId, sessionId, batchId, and the number that was called, plus the key that was pressed:

{
  "event": "call.webhook.appointment.confirmed",
  "call": {
    "callId": "01M3Q01XSRH9FB6KV5F487XWW8",
    "sessionId": "01M3Q01XSQ2W41CR8FXW309753",
    "batchId": "01M3Q01XMS16K5H7G0TEZZTQD4",
    "to": { "type": "PHONE", "phone": { "number": "+15551234567" } },
    "direction": "OUTBOUND",
    "callResult": "IN_PROGRESS"
  },
  "menu": { "menuName": "confirm", "input": "1" }
}

confirm only needs the query string, but log callId and sessionId if you want to trace a confirmation back to the call. The call waits for your response for up to five seconds. If the request fails or takes longer, the call ends. So answer fast, and for anything slow, such as a CRM write, record the result and do the work after you've responded. For extra resilience, the webhook command also takes a fallbackUrl, a second endpoint Sinch tries when the first one fails.

Set up the reminder project

Create a second project for the scripts, next to reminder-webhook rather than inside it:

cd ..   # back out of reminder-webhook
mkdir appointment-reminders && cd appointment-reminders
npm init -y
npm pkg set type=module
npm install @sinch/sdk-core
npm install --save-dev typescript @types/node

Node.js 24 runs TypeScript files directly, so there's no build step. tsc is only for type checking. Create tsconfig.json in appointment-reminders:

{
  "compilerOptions": {
    "target": "es2024",
    "module": "nodenext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  }
}

In the same terminal, export your credentials and settings:

export SINCH_PROJECT_ID=YOUR_PROJECT_ID
export SINCH_KEY_ID=YOUR_KEY_ID
export SINCH_KEY_SECRET=YOUR_KEY_SECRET
export SINCH_FROM_NUMBER=YOUR_SINCH_NUMBER
export BUSINESS_NAME="Neurovia"
export CONFIRM_URL=https://YOUR_FUNCTION_URL/confirm

REMINDER_SIGNING_SECRET is still exported from the function step. If you're in a new shell, export it again with the same value you stored with sinch secrets add.

Create sinch-client.ts. Both scripts use it to call the Sinch APIs:

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

export const requireEnv = (name: string): string => {
  const value = process.env[name];
  if (!value) throw new Error(`Missing environment variable ${name}`);
  return value;
};

export const sinchClient = new SinchClient({
  projectId: requireEnv('SINCH_PROJECT_ID'),
  keyId: requireEnv('SINCH_KEY_ID'),
  keySecret: requireEnv('SINCH_KEY_SECRET'),
});

Create appointments.ts with the list of people to call. Replace YOUR_PHONE_NUMBER with your own number, so the first batch you send calls only you. The other entries stay commented out until that works:

// Tomorrow's appointments. In a real system these come from your scheduling database.
// Start with one entry: your own phone number, in E.164 format such as +15551234567.
export const appointments = [
  { appointmentId: 'A-1001', phoneNumber: 'YOUR_PHONE_NUMBER', name: 'Ada', time: '9:30 AM' },
  // Uncomment and edit these once the first test call works:
  // { appointmentId: 'A-1002', phoneNumber: '+15557654321', name: 'Grace', time: '11 AM' },
  // { appointmentId: 'A-1003', phoneNumber: '+15559876543', name: 'Alan', time: '2:30 PM' },
];

const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
export const reminderDate = tomorrow.toLocaleDateString('sv-SE'); // YYYY-MM-DD in local time

The SDK authenticates with OAuth 2.0 from your key ID and secret, so there's no token handling to write.

Build the reminder call flow

The call flow is the same for every customer. Only the placeholders change. Create reminder-flow.ts:

import type { Voice } from '@sinch/sdk-core';

type SvamlCommand = Voice.v2.SvamlCommand;

const say = (text: string): Voice.v2.Message => ({
  type: 'SAY',
  say: { text, voiceName: 'Emma' },
});

const sayThenHangUp = (text: string): SvamlCommand => ({
  command: 'messages',
  messages: [say(text)],
  events: { onFinish: [{ command: 'hangup' }] },
});

export function buildReminderFlow(businessName: string, fromNumber: string, confirmUrl: string): SvamlCommand[] {
  const answerUrl = (action: 'confirm' | 'reschedule') =>
    `${confirmUrl}?appointment=@appointmentId&action=${action}&token=@${action}Token`;

  const confirmMenu: SvamlCommand = {
    command: 'menu',
    startMenu: 'confirm',
    menus: {
      confirm: {
        prompt: {
          allowBargeIn: true,
          messages: [
            say(`Hi @name, this is ${businessName} with a reminder about your appointment tomorrow at @time. Press 1 to confirm, or 2 if you need to reschedule.`),
          ],
        },
        inputTimeoutDurationSeconds: 6,
        repeatCount: 1,
        maximumInputLength: 1,
        matches: {
          '1': [{ command: 'webhook', webhookName: 'appointment.confirmed', url: answerUrl('confirm') }],
          '2': [{ command: 'webhook', webhookName: 'appointment.reschedule', url: answerUrl('reschedule') }],
        },
        onFail: [sayThenHangUp(`Sorry, we didn't get that. Please call ${businessName} to confirm. Goodbye.`)],
      },
    },
  };

  return [
    {
      command: 'dial',
      callName: 'appt-@appointmentId',
      from: { type: 'PHONE', phone: { number: fromNumber } },
      to: { type: 'PHONE', phone: { number: '@phoneNumber' } },
      dialTimeoutDurationSeconds: 30,
      maxCallDurationSeconds: 120,
      events: {
        onAnswer: [
          {
            command: 'amd',
            events: {
              onHuman: [confirmMenu],
              onUnknown: [confirmMenu],
              onBeep: [sayThenHangUp(`Hi @name, this is ${businessName} with a reminder about your appointment tomorrow at @time. Call us if you need to reschedule. Goodbye.`)],
            },
          },
        ],
      },
    },
  ];
}

On each call:

dial calls @phoneNumber from your number. callName is set to appt-@appointmentId, which comes back on every call record later. That's how you match results to appointments.
amd runs answering machine detection once the call is answered. It has four outcomes: Human, machine, beep, and unknown. Detection listens before anything plays, so the customer hears a short pause after picking up.
A person (onHuman) hears who's calling, their appointment time, and a menu. Pressing 1 or 2 fires a webhook to your confirmation endpoint. The URL carries the appointment ID, the choice, and the token for that choice.
Unknown (onUnknown) gets the same menu. People often pick up without saying anything, and a silent answer tends to come back as unknown. Hanging up on unknown hangs up on real customers. The trade-off: When a voicemail is detected as unknown, the menu prompt ends up on the voicemail instead of the shorter message. It still carries the reminder.
Voicemail gets a short message in onBeep. According to the answering machine detection tutorial, a voicemail greeting triggers machine first and beep after it, so the message goes in onBeep, where it plays after the tone. onMachine is left out so the call waits for the beep.
No key press (onFail) after the prompt and one repeat ends the call with a request to call you back.

Everything except the confirmation runs inside Voice API v2. The flow is defined inline with nested events, so there are no webhook round trips while the call rings, detects, and plays the menu.

Write the send script

Create send-reminders.ts. It validates the flow, then starts the batch with one entry per appointment:

import { createHmac } from 'node:crypto';
import type { Voice } from '@sinch/sdk-core';
import { appointments, reminderDate } from './appointments.ts';
import { buildReminderFlow } from './reminder-flow.ts';
import { requireEnv, sinchClient } from './sinch-client.ts';

const reminderFlow = buildReminderFlow(
  requireEnv('BUSINESS_NAME'),
  requireEnv('SINCH_FROM_NUMBER'),
  requireEnv('CONFIRM_URL'),
);

// Forgery protection: one token per appointment and action, so the confirm endpoint can
// reject requests that didn't come from this batch.
const signingSecret = requireEnv('REMINDER_SIGNING_SECRET');
const sign = (appointmentId: string, action: 'confirm' | 'reschedule'): string =>
  createHmac('sha256', signingSecret).update(`${appointmentId}:${action}`).digest('hex');

const parameters = appointments.map((appointment) => ({
  ...appointment,
  confirmToken: sign(appointment.appointmentId, 'confirm'),
  rescheduleToken: sign(appointment.appointmentId, 'reschedule'),
}));

// Only call between 9 AM and 8 PM. This sample assumes your customers share the time zone
// of the machine running it. For several time zones, send one batch per zone.
function secondsLeftInCallingWindow(): number {
  const now = new Date();
  if (now.getHours() < 9) throw new Error('Calling hours start at 9 AM');
  const end = new Date(now);
  end.setHours(20, 0, 0, 0);
  const seconds = Math.floor((end.getTime() - now.getTime()) / 1000);
  if (seconds <= 0) throw new Error('Calling hours are over for today');
  return Math.min(seconds, 10_800); // the API allows at most three hours
}

// The validate endpoint doesn't take parameters, and a raw @phoneNumber fails the E.164
// check, so validate a copy with the first entry's values filled in.
function fillPlaceholders(commands: Voice.v2.SvamlCommand[], values: Record<string, string>): Voice.v2.SvamlCommand[] {
  const placeholder = new RegExp(`@(${Object.keys(values).join('|')})\\b`, 'g');
  const filled = JSON.stringify(commands).replace(placeholder, (_match, key: string) => values[key]);
  return JSON.parse(filled) as Voice.v2.SvamlCommand[];
}

async function main(): Promise<void> {
  const ttlSeconds = secondsLeftInCallingWindow();

  if (parameters.length === 0) throw new Error('No appointments to remind');
  const invalidNumbers = parameters.filter(({ phoneNumber }) => !/^\+[1-9]\d{1,14}$/.test(phoneNumber));
  if (invalidNumbers.length > 0) {
    throw new Error(`Not E.164: ${invalidNumbers.map(({ appointmentId }) => appointmentId).join(', ')}`);
  }

  const validation = await sinchClient.voice.v2.svaml.validate({
    validateSvamlRequestBody: {
      svaml: { commands: fillPlaceholders(reminderFlow, parameters[0]) },
      validationType: 'STRICT',
    },
  });
  if (!validation.isValid) {
    throw new Error(`Reminder flow is invalid: ${validation.errors?.join('; ')}`);
  }

  // One key per reminder run: a rerun within 10 minutes returns the same batch
  // instead of calling everyone twice.
  const batch = await sinchClient.voice.v2.batches.start({
    'Idempotency-Key': `appointment-reminders-${reminderDate}`,
    startBatchRequestBody: {
      commands: reminderFlow,
      parameters,
      batchOptions: { maxCps: 5, ttlSeconds },
    },
  });

  console.log(`Started batch ${batch.batchId} with ${parameters.length} reminder${parameters.length === 1 ? '' : 's'}`);
}

main().catch((error: unknown) => {
  console.error('Failed to send reminders:', error instanceof Error ? error.message : error);
  process.exit(1);
});

The details in that script:

Sign each appointment and action. confirmToken and rescheduleToken are HMACs of the appointment ID and the action. The matching one ends up in the webhook URL, so a leaked confirm link can't be used to reschedule. This protects against forged requests. It isn't a login, and the tokens don't expire.
Check the input. The script stops if the list is empty or any number isn't in E.164 format (+15551234567), before anything is sent.
Validate the flow. svaml.validate checks the flow against the live schema without placing a call. It doesn't take parameters, and a raw @phoneNumber fails the E.164 check, so the script fills in one entry's values before validating.
Set maxCps. It defaults to 1000. Pick a rate your number, your carrier, and anyone who calls back can handle. Five calls a second works through 500 reminders in under two minutes.
Tie ttlSeconds to calling hours. The script only runs between 9 AM and 8 PM, and stops starting calls at 8 PM or after three hours, whichever comes first. "Local" here means the machine running the script, so the sample assumes your customers are in the same time zone. If they aren't, send one batch per time zone.
Use a stable Idempotency-Key. If the script retries or runs twice within 10 minutes, Sinch returns the same batchId instead of calling everyone again. A random key per run wouldn't protect you from a second run, so the key comes from the reminder date. The window is only 10 minutes, so also record in your own system which appointments you've sent reminders for.
One entry per person. Sessions in a batch run in parallel and don't follow list order. Two entries for the same number ring the same phone at the same time.

Send your first batch

With your own number in the one active entry in appointments.ts, check the types from the appointment-reminders folder:

npx tsc

No output means no type errors. Then send the batch:

node send-reminders.ts

Started batch 01M3Q6P4YM2F0FFVS8GGZQ0X8G with 1 reminder

Your phone rings within a few seconds. Pick up and say hello. After a short pause, you hear the reminder. Press 1, and you hear "Thanks, your appointment is confirmed."

To see the confirmation arrive, open a second terminal in the reminder-webhook folder and stream the function's logs:

sinch functions logs --follow

The request to /confirm shows up with action=confirm and your appointment ID, and the function logs Appointment A-1001: confirm. Keep the batch ID from the send output. The report script uses it next.

Write the report script

The batch summary counts sessions by state: queued, inProgress, completed, and expired. A completed session means the call ended, not that someone answered. The outcome of each call is on the session. report.ts waits until nothing is queued or in progress, reads each session (10 at a time), maps it back to an appointment through callName, and lists the appointments that never got a call. Create report.ts:

import { setTimeout as sleep } from 'node:timers/promises';
import type { Voice } from '@sinch/sdk-core';
import { appointments } from './appointments.ts';
import { sinchClient } from './sinch-client.ts';

const batchId = process.argv[2];

async function waitForBatch(): Promise<void> {
  const firstSummary = await sinchClient.voice.v2.batches.get({ batchId });
  // No call starts after the TTL, and none lasts longer than maxCallDurationSeconds (120).
  const deadline = Date.now() + ((firstSummary.ttlSeconds ?? 10_800) + 180) * 1000;

  for (let summary = firstSummary; Date.now() < deadline; summary = await sinchClient.voice.v2.batches.get({ batchId })) {
    console.log(`queued ${summary.queued}, in progress ${summary.inProgress}, completed ${summary.completed}, expired ${summary.expired}`);
    if (summary.queued === 0 && summary.inProgress === 0) return;
    await sleep(10_000);
  }
  throw new Error(`Batch ${batchId} is still running after its TTL`);
}

async function fetchCalls(sessionIds: string[]): Promise<Voice.v2.Call[]> {
  const calls: Voice.v2.Call[] = [];
  // Ten session lookups at a time.
  for (let start = 0; start < sessionIds.length; start += 10) {
    const results = await Promise.allSettled(
      sessionIds.slice(start, start + 10).map((sessionId) => sinchClient.voice.v2.sessions.get({ sessionId })),
    );
    results.forEach((result, index) => {
      if (result.status === 'fulfilled') calls.push(...result.value.calls);
      else console.error(`Could not read session ${sessionIds[start + index]}:`, result.reason);
    });
  }
  return calls;
}

async function main(): Promise<void> {
  if (!batchId) throw new Error('Usage: node report.ts BATCH_ID');
  await waitForBatch();

  const { sessions } = await sinchClient.voice.v2.batches.getDetails({ batchId });
  const calls = await fetchCalls(sessions.map((session) => session.id));

  const calledIds = new Set<string>();
  for (const call of calls) {
    const appointmentId = call.callName?.replace(/^appt-/, '') ?? 'unknown';
    calledIds.add(appointmentId);
    console.log(`${appointmentId}  ${call.callResult}  ${call.callReason ?? ''}  ${call.callDurationSeconds ?? 0}s`);
  }

  // Expired sessions aren't returned, so compare against the original list.
  for (const { appointmentId } of appointments) {
    if (!calledIds.has(appointmentId)) console.log(`${appointmentId}  NOT CALLED  expired before it started`);
  }
}

main().catch((error: unknown) => {
  console.error('Failed to report on batch:', error instanceof Error ? error.message : error);
  process.exit(1);
});

Run it with the batch ID from your first batch:

node report.ts 01M3Q6P4YM2F0FFVS8GGZQ0X8G

queued 0, in progress 1, completed 0, expired 0
queued 0, in progress 1, completed 0, expired 0
queued 0, in progress 0, completed 1, expired 0
A-1001  COMPLETED  MANAGER_HANGUP  21s

The script compares against the current appointments.ts. In a real system the list can change between sending and reporting, so store the list you sent together with the batchId and report against that.

callResult and callReason tell you what happened: COMPLETED for a call that connected, and FAILED, BUSY, or NO_ANSWER with a reason for the ones that didn't. Sessions that expired before they started aren't returned by getDetails at all, which is why the script compares against the appointment list. Those customers need another channel, such as an SMS.

The report tells you a call connected. Whether the customer pressed 1 or 2 is in your confirmation endpoint's records.

When that works with your own number, add the real appointment list and send it the same way.

Stop a batch

If the schedule changes after you've sent the batch, stop it:

await sinchClient.voice.v2.batches.stop({ batchId });

Queued calls won't start. Calls already in progress finish normally. The request returns 202 with { "result": "STOP_REQUESTED" }.

Production considerations

Calling rules. Automated calls are regulated in most markets. Check consent, calling hours, caller ID, and opt-out requirements for every country you call before the first batch goes out.
Pick maxCps with callbacks in mind. If reminders lead customers to call back, a high rate turns into a wave of inbound calls at once.
Persist the batchId with the job that sent it. There's no endpoint that lists batches, so a lost ID means no summary.
Keep the confirmation endpoint fast and idempotent. A customer who presses 1 twice shouldn't confirm twice in your system.
Plan the fallback. Decide what happens to unanswered, failed, and expired reminders. An SMS through the Sinch Conversation API is a common second attempt.
Watch the 600-character limit on each SAY message, after placeholders are filled in.

Troubleshooting

Calling hours are over for today or Calling hours start at 9 AM. The send script only runs between 9 AM and 8 PM on the machine's clock. Send during that window, or change the hours in secondsLeftInCallingWindow to match your business.
A customer presses a key other than 1 or 2. The menu plays the prompt once more. If there's still no match, the onFail message asks them to call you, and the call ends.
The call connects, stays silent, then hangs up. Detection came back as unknown and the flow has no onUnknown handler, or it hangs up there. Give onUnknown the same menu as onHuman.
Pressing a key does nothing, or the call drops after the menu. The confirmation webhook failed or took longer than five seconds. Check that CONFIRM_URL is public, ends in /confirm, and responds quickly. sinch functions logs --follow in reminder-webhook shows each request.
The endpoint returns 403 invalid token. REMINDER_SIGNING_SECRET differs between the send script and the function. Set the same value in both, and deploy the function again after sinch secrets add.
Not E.164: A-1001. You haven't replaced YOUR_PHONE_NUMBER in appointments.ts, or a number is missing the + and country code.
svaml.validate says the number must be a valid E.164 phone number. You validated the flow with placeholders still in it. Validate a copy with real values, as send-reminders.ts does.
Some appointments show as not called. Their sessions expired before they started. Send the batch earlier in the day, raise maxCps, or reach those customers another way.
The second call to the same number fails with NOT_AVAILABLE. Two entries in the same batch called one phone at once. Keep one entry per person.

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

You now have reminders that call a whole list at a controlled pace, adapt to people and voicemail, and report back per appointment. From here you can record calls to your own storage with startRecording, hand confirmed callers to an agent with bridgeCall, or put an AI agent on the line with Voice Relay, which Connect AI Agents to Phone Calls with Sinch Voice API v2 walks through.

Additional resources

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

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