DEV Community: Gunnar Grosch

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

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

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

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

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

You'll need:

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

Installing and authenticating

npm install -g @sinch/cli

Then:

sinch auth login

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

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

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

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

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

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

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

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

Confirm the connection:

sinch health

✔ API is healthy

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

Getting a number

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

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

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

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

For a specific number:

sinch numbers available check +12025550134

To rent:

sinch numbers available rent +12025550134

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

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

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

✔ +1 202-555-0172 rented successfully!

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

Manage this number: sinch numbers active get +12025550172

After renting, confirm it's yours:

sinch numbers active list

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

✔ Found 3 active number(s)

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

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

sinch numbers active get +12025550172

✔ Number retrieved

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

When you're done with it:

sinch numbers active release +12025550172

Prompts for confirmation unless you pass --force.

Making a call

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

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

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

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

✔ TTS callout queued

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

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

A few flags worth knowing:

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

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

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

✔ Call info retrieved

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

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

Sending a message

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

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

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

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

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

It then asks which channel to use:

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

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

Output on success:

✔ Message sent successfully!

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

Testing a webhook locally

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

From your project directory:

sinch functions dev --tunnel

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

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

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

Function server running on http://localhost:3000

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

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

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

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

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

Streaming logs

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

sinch functions logs --follow

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

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

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

Filter by level, text, or time window:

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

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

sinch functions logs <function-id> --follow

What else the CLI covers

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

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

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

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

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

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

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

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

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

Troubleshooting

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

What comes next

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

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

Additional Resources

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

Getting Started with Sinch Functions

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

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

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

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

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

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

You'll need

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

Installing the CLI

npm install -g @sinch/cli

Then authenticate:

sinch auth login

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

Confirm the connection before moving on:

sinch health

✔ API is healthy

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

Creating your first function

Initialize a project from a template:

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

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

cd my-simple-voice-ivr

Here's what the template generates:

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

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

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

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

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

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

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

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

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

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

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

Running locally

sinch functions dev

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

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

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

Test it with curl too:

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

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

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

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

Adding a menu

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

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

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

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

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

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

Responding to input

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Configuration and secrets

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

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

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

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

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

ELEVENLABS_API_KEY=

Then set the actual value:

sinch secrets add ELEVENLABS_API_KEY sk-...

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

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

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

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

To attach a debugger while testing any of this:

sinch functions dev --debug

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

Deploying

sinch functions deploy

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

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

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

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

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

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

To follow logs:

sinch functions logs --follow

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

Troubleshooting

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

Cleaning up

When you're done, delete the function:

sinch functions delete <function-id>

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

What else you can build

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

sinch templates list
sinch templates list --runtime node

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

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

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

Additional Resources

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

Yells at Cloud, Episode 1: Generally Available

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

Listen: YouTube · Spotify · Apple Podcasts

Summary

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

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

Timestamps

Main topics

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

Burst Mode

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

Hosts

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

Follow the show

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

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

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

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

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

The four methods

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

The differences matter more than they appear in that table.

SMS OTP

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

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

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

Flash Call

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

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

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

Phone Call Verification

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

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

Data Verification

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

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

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

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

How to pick

The decision comes down to a few questions:

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

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

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

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

Fallback chains

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

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

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

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

Wrapping up

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

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

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

Additional Resources

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

Phone-Based User Verification in TypeScript and Python

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

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

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

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

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

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

Prerequisites

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

In the Sinch Dashboard:

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

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

How verification works

The flow is two steps:

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

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

The SDK approach (Node.js)

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

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

Install the SDK:

npm install @sinch/sdk-core

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

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

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

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

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

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

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

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

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

A successful start response:

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

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

A successful report response:

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

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

Raw HTTP

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

Python

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

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

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


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


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


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


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

Node.js (no SDK)

import { createHmac, createHash } from "crypto";

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

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

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

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

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

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

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

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

Things worth knowing

Verifications expire

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

Phone numbers must be E.164

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

FlashCall code format

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

Data Verification requires cellular data

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

Wrapping up

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

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

Additional Resources

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

Sending SMS from AWS Lambda with the Sinch SDK

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

Your payment just failed. The user needs to know before they try to check out again. Your deployment pipeline just finished. The engineer who kicked it off is waiting. A patient's appointment is in 24 hours and they haven't confirmed.

These are the moments where SMS works better than email. It's immediate, it doesn't get filtered, and it doesn't require the recipient to be looking at an app. Lambda is already where your event-driven logic lives. Connecting it to SMS is a few dozen lines of code.

This post uses the official Sinch SDKs. The examples cover Node.js and Python. Sinch also publishes SDKs for Java and .NET that follow the same pattern. If you'd rather manage the HTTP calls and OAuth token exchange yourself, there's a companion post that covers the raw HTTP approach using the same repo.

Prerequisites

The Sinch dashboard setup takes about 10 minutes. After that, sending is a single SDK call. You'll need a Sinch account (sign up here, a trial account is enough to test, see pricing for details), the AWS SAM CLI, and Node.js 22+ or Python 3.13+.

When you first sign up, Sinch shows an onboarding wizard. If you completed it and selected SMS, you likely already have an app configured with a sender number. In that case, skip to step 4 below. If you dismissed the wizard or are not sure, follow all steps.

Before writing any code, configure the following in the Sinch Build Dashboard:

Get access to Conversation API. Click Conversation API in the left menu, accept the terms, and click GET ACCESS.
Create a Conversation API app. Go to Conversation API > Apps and click Create app. Record the app ID.
Enable the SMS channel on your app. Open the app, find SMS in the channel list, click Set up channel, and connect your service plan.
Find your sender number. Go to SMS > SMS Channel > Numbers. The assigned number is your SMS_SENDER value.
Note your project ID. Click the project name in the top bar and go to Project Settings.
Create an access key. Go to Settings > Access Keys. Record the access key ID and secret. The secret is only shown once.

Note: on a trial account, you can only send to verified numbers and the message content is fixed. To send to any number with custom content, upgrade your account.

One thing that trips people up: the Conversation API is regional. Your app must be created in the same region as your SMS service plan. If they're in different regions, messages will fail with no obvious error. The most common regions are us and eu. A Brazil region (br) also exists.

Storing credentials in SSM Parameter Store

The Lambda function reads your Sinch access key and secret from SSM Parameter Store at cold start. Storing them there as SecureString keeps them out of CloudFormation state and encrypted at rest using KMS.

Create the two parameters before deploying. Run these in the same AWS region where you'll deploy the Lambda:

aws ssm put-parameter \
  --name /sinch/access-key \
  --value "YOUR_ACCESS_KEY" \
  --type SecureString

aws ssm put-parameter \
  --name /sinch/access-key-secret \
  --value "YOUR_ACCESS_KEY_SECRET" \
  --type SecureString

The Lambda function

The SDK handles OAuth 2.0 token exchange internally, so there's no token caching code in the handler. What you do cache is the SinchClient instance itself. Initializing it fetches credentials from SSM, so you want that to happen once at cold start, not on every invocation.

TypeScript

import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";
import { SinchClient } from "@sinch/sdk-core";
import { SQSEvent, SQSBatchResponse, EventBridgeEvent, SNSEvent } from "aws-lambda";

const ssm = new SSMClient({});
const SINCH_REGION = process.env.SINCH_REGION || "us";
const SINCH_PROJECT_ID = process.env.SINCH_PROJECT_ID!;
const SINCH_APP_ID = process.env.SINCH_APP_ID!;
const SINCH_SMS_SENDER = process.env.SINCH_SMS_SENDER!;
const SINCH_ACCESS_KEY_PARAM = process.env.SINCH_ACCESS_KEY_PARAM!;
const SINCH_ACCESS_KEY_SECRET_PARAM = process.env.SINCH_ACCESS_KEY_SECRET_PARAM!;

let sinchClient: SinchClient | null = null;

async function getClient(): Promise<SinchClient> {
  if (sinchClient) return sinchClient;
  const [keyRes, secretRes] = await Promise.all([
    ssm.send(new GetParameterCommand({ Name: SINCH_ACCESS_KEY_PARAM, WithDecryption: true })),
    ssm.send(new GetParameterCommand({ Name: SINCH_ACCESS_KEY_SECRET_PARAM, WithDecryption: true })),
  ]);
  sinchClient = new SinchClient({
    projectId: SINCH_PROJECT_ID,
    keyId: keyRes.Parameter!.Value!,
    keySecret: secretRes.Parameter!.Value!,
    conversationRegion: SINCH_REGION as "us" | "eu",
  });
  return sinchClient;
}

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

async function sendSms(to: string, message: string) {
  if (!E164_REGEX.test(to)) {
    throw new Error(`Invalid phone number format. Use E.164 (e.g. +15551234567), got: ${to}`);
  }
  const client = await getClient();
  return client.conversation.messages.send({
    sendMessageRequestBody: {
      app_id: SINCH_APP_ID,
      recipient: { identified_by: { channel_identities: [{ channel: "SMS", identity: to }] } },
      message: { text_message: { text: message } },
      channel_properties: { SMS_SENDER: SINCH_SMS_SENDER },
    },
  });
}

// --- Direct invocation (default) ---
export const handler = async (event: { to: string; message: string }) => {
  if (!event.to || !event.message) return { statusCode: 400, body: "Missing to or message" };
  try {
    return { statusCode: 200, body: await sendSms(event.to, event.message) };
  } catch (err) {
    console.error(err);
    return { statusCode: 500, body: String(err) };
  }
};

// --- SQS (uncomment to use) ---
// Message body format: { "to": "+15551234567", "message": "Hello!" }
// Returns batchItemFailures so only failed records are retried, preventing duplicate sends.
//
// export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
//   const failures: { itemIdentifier: string }[] = [];
//   for (const record of event.Records) {
//     try {
//       const payload = JSON.parse(record.body);
//       await sendSms(payload.to, payload.message);
//     } catch (err) {
//       console.error(`Failed record ${record.messageId}:`, err);
//       failures.push({ itemIdentifier: record.messageId });
//     }
//   }
//   return { batchItemFailures: failures };
// };

// --- EventBridge (uncomment to use) ---
// Event detail format: { "to": "+15551234567", "message": "Hello!" }
//
// export const handler = async (
//   event: EventBridgeEvent<"SendSms", { to: string; message: string }>
// ) => {
//   await sendSms(event.detail.to, event.detail.message);
// };

// --- SNS (uncomment to use) ---
// SNS message body format: { "to": "+15551234567", "message": "Hello!" }
//
// export const handler = async (event: SNSEvent) => {
//   for (const record of event.Records) {
//     const payload = JSON.parse(record.Sns.Message);
//     await sendSms(payload.to, payload.message);
//   }
// };

Python

import json
import os
import re
import boto3
from sinch import SinchClient
from sinch.core.exceptions import SinchException

ssm = boto3.client("ssm")

SINCH_REGION = os.environ.get("SINCH_REGION", "us")
SINCH_PROJECT_ID = os.environ["SINCH_PROJECT_ID"]
SINCH_APP_ID = os.environ["SINCH_APP_ID"]
SINCH_SMS_SENDER = os.environ["SINCH_SMS_SENDER"]
SINCH_ACCESS_KEY_PARAM = os.environ["SINCH_ACCESS_KEY_PARAM"]
SINCH_ACCESS_KEY_SECRET_PARAM = os.environ["SINCH_ACCESS_KEY_SECRET_PARAM"]

E164_REGEX = re.compile(r"^\+[1-9]\d{1,14}$")

_sinch_client = None


def get_client():
    global _sinch_client
    if _sinch_client:
        return _sinch_client
    key = ssm.get_parameter(Name=SINCH_ACCESS_KEY_PARAM, WithDecryption=True)["Parameter"]["Value"]
    secret = ssm.get_parameter(Name=SINCH_ACCESS_KEY_SECRET_PARAM, WithDecryption=True)["Parameter"]["Value"]
    _sinch_client = SinchClient(
        project_id=SINCH_PROJECT_ID,
        key_id=key,
        key_secret=secret,
        conversation_region=SINCH_REGION,
    )
    return _sinch_client


def send_sms(to, message):
    if not E164_REGEX.match(to):
        raise ValueError(f"Invalid phone number format. Use E.164 (e.g. +15551234567), got: {to}")
    client = get_client()
    return client.conversation.messages.send_text_message(
        app_id=SINCH_APP_ID,
        text=message,
        recipient_identities=[{"channel": "SMS", "identity": to}],
        channel_properties={"SMS_SENDER": SINCH_SMS_SENDER},
    )


# --- Direct invocation (default) ---
def handler(event, context):
    to = event.get("to")
    message = event.get("message")
    if not to or not message:
        return {"statusCode": 400, "body": "Missing to or message"}
    try:
        result = send_sms(to, message)
        return {"statusCode": 200, "body": {"message_id": result.message_id, "accepted_time": str(result.accepted_time)}}
    except Exception as e:
        if isinstance(e, SinchException):
            print(f"Sinch API error {e.response_status_code}: {e}")
            return {"statusCode": e.response_status_code or 500, "body": str(e)}
        print(f"Error: {e}")
        return {"statusCode": 500, "body": str(e)}


# --- SQS (uncomment to use) ---
# Message body format: {"to": "+15551234567", "message": "Hello!"}
# Returns batchItemFailures so only failed records are retried, preventing duplicate sends.
#
# def handler(event, context):
#     failures = []
#     for record in event["Records"]:
#         try:
#             payload = json.loads(record["body"])
#             send_sms(payload["to"], payload["message"])
#         except Exception as e:
#             print(f"Failed record {record['messageId']}: {e}")
#             failures.append({"itemIdentifier": record["messageId"]})
#     return {"batchItemFailures": failures}


# --- EventBridge (uncomment to use) ---
# Event detail format: {"to": "+15551234567", "message": "Hello!"}
#
# def handler(event, context):
#     detail = event["detail"]
#     send_sms(detail["to"], detail["message"])


# --- SNS (uncomment to use) ---
# SNS message body format: {"to": "+15551234567", "message": "Hello!"}
#
# def handler(event, context):
#     for record in event["Records"]:
#         payload = json.loads(record["Sns"]["Message"])
#         send_sms(payload["to"], payload["message"])

Compared to the raw HTTP version, there's no getAccessToken() function and no token cache. The SDK handles the OAuth 2.0 exchange internally and refreshes tokens as needed. The tradeoff: you add @sinch/sdk-core (Node.js) or sinch (Python) as a runtime dependency. The Java and .NET SDKs work the same way if those are your languages.

The SAM template

The repo uses a single template.yaml at the root that deploys all four functions together. Here's the relevant section for the Node.js SDK function:

AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31

Globals:
  Function:
    Timeout: 10
    MemorySize: 256
    Environment:
      Variables:
        SINCH_REGION: !Ref SinchRegion
        SINCH_PROJECT_ID: !Ref SinchProjectId
        SINCH_APP_ID: !Ref SinchAppId
        SINCH_SMS_SENDER: !Ref SinchSmsSender
        SINCH_ACCESS_KEY_PARAM: !Ref SinchAccessKeyParam
        SINCH_ACCESS_KEY_SECRET_PARAM: !Ref SinchAccessKeySecretParam

Parameters:
  SinchRegion:
    Type: String
    Default: us
    AllowedValues: [us, eu]
  # ... SinchProjectId, SinchAppId, SinchSmsSender,
  #     SinchAccessKeyParam, SinchAccessKeySecretParam

Resources:
  NodeSdkFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: nodejs22.x
      Handler: src/handler.handler
      CodeUri: node-sdk/
      Policies:
        - Statement:
            - Effect: Allow
              Action: ssm:GetParameter
              Resource:
                - !Sub "arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter${SinchAccessKeyParam}"
                - !Sub "arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter${SinchAccessKeySecretParam}"
    Metadata:
      BuildMethod: esbuild
      BuildProperties:
        Minify: false
        Target: es2022
        EntryPoints:
          - node-sdk/src/handler.ts

Deploy from the repo root:

sam build
sam deploy --guided

SAM handles all dependencies automatically during sam build: Node.js packages via npm install, Python packages via requirements.txt.

Invoking the function

With no event source attached, you invoke the function directly with a JSON payload. The simplest way is the AWS CLI:

# Get the function name from the stack outputs after sam deploy --guided,
# then invoke it:
aws lambda invoke \
  --function-name <NodeSdkFunctionName from outputs> \
  --payload '{"to": "+15559876543", "message": "Hello from Lambda!"}' \
  --cli-binary-format raw-in-base64-out \
  response.json

cat response.json

A successful response looks like:

{
  "statusCode": 200,
  "body": {
    "accepted_time": "2026-05-27T18:00:00.000Z",
    "message_id": "01ABC123DEF456GHI789JKL012"
  }
}

message_id is what you'd use to correlate delivery receipts if you set up a webhook.

If something goes wrong:

{
  "statusCode": 400,
  "body": "{\"error\":{\"code\":400,\"message\":\"recipient identity is not a valid MSISDN\",\"status\":\"INVALID_ARGUMENT\"}}"
}

Common causes: malformed phone number, wrong app_id, region mismatch between your app and service plan, or missing SMS_SENDER without a default originator configured.

When you're ready to wire it up to something, change only the handler function. sendSms() / send_sms() doesn't change. The SAM template has commented event source blocks for SQS, EventBridge, SNS, and API Gateway ready to uncomment:

SQS for queued, rate-controlled sending
EventBridge for event-driven notifications (order placed, alarm fired, job completed)
SNS for fan-out scenarios
API Gateway if you need an HTTP endpoint

Testing locally

echo '{"to": "+15559876543", "message": "Test"}' > event.json
sam local invoke NodeSdkFunction --event event.json
# or
sam local invoke PythonSdkFunction --event event.json

Note: sam local invoke won't be able to reach SSM or the Sinch API unless your local environment has AWS credentials with the right permissions. For local testing without live credentials, stub the SSM calls or use environment variables directly.

Things worth knowing

Phone numbers must be E.164

The to value must be in E.164 format: +15551234567, not 5551234567 or (555) 123-4567. The handler validates this before calling the SDK. The Sinch API won't normalize it for you.

Long messages get split

SMS has a 160-character limit for standard GSM encoding. Longer messages get split into multiple parts. You can cap this with SMS_MAX_NUMBER_OF_MESSAGE_PARTS in channel_properties:

"channel_properties": {
  "SMS_SENDER": "+15551231234",
  "SMS_MAX_NUMBER_OF_MESSAGE_PARTS": "2"
}

If the message would require more parts than the cap, the API rejects it. It won't truncate or silently drop it. You'll get an error back, so you can handle it in your application.

Error handling and delivery status

When sendSms() throws, the handler logs the error and returns a 500. For SQS triggers, implement partial batch failure reporting to avoid retrying already-sent messages: catch errors per record and return { batchItemFailures: [{ itemIdentifier: record.messageId }] }.

For true end-to-end idempotency, you need deduplication before the Sinch call since the Conversation API doesn't support idempotency keys. Use an SQS FIFO queue with a MessageDeduplicationId derived from your business event, or the Powertools for AWS Lambda idempotency utility which handles a DynamoDB check-before-send with a decorator.

For delivery status, the Conversation API sends a DELIVERED or FAILED callback to a webhook URL you configure on your app. Register one in the Sinch Build Dashboard or via the Webhooks API.

Wrapping up

The SDK version is shorter than the raw HTTP version: no token management, no fetch calls, just client.conversation.messages.send(). The cost is a runtime dependency. Whether that tradeoff is worth it depends on your project.

Sinch also publishes SDKs for Java and .NET. The same pattern applies.

The natural next step is delivery receipts: configuring a webhook so your app knows whether each message actually reached the recipient's device. After that, if you need to send to many recipients, wiring an SQS queue in front of the function gives you rate control and automatic retries without changing the handler.

The source code for this post is available on GitHub: gunnargrosch/sinch-sms-lambda

What are you building that needs SMS notifications? Let me know in the comments.

Additional Resources

Two-Way SMS Conversations on AWS

Gunnar Grosch — Mon, 01 Jun 2026 19:39:17 +0000

A customer gets your appointment reminder and texts back "Confirmed" or "Can we reschedule?" Someone texts your support number asking about their order. A user responds to your verification flow with a question. Something needs to receive each of these, understand the context, and respond. That's the gap between broadcasting SMS and actually having a conversation.

Two scenarios matter here. The customer texts you first: a question, a support request, a reply to a notification from a different channel. Or your application sends the opening message: an appointment reminder, a verification code, an order update. Either way, the customer can reply. Both flows use the same webhook. What changes is whether your application fires the first shot.

This post builds that on AWS serverless using the Sinch Conversation API. If you've read the previous posts in this series, you'll recognize the SSM credential pattern. This post stands on its own if you're coming in fresh.

The architecture

DLQs not shown. Both queues have a dead-letter queue that captures messages that fail after three attempts.

SenderFunction: reads from the outbound queue, sends an SMS via the Conversation API, calls storeConversation with the messageId. All outbound messages flow through here, whether they come from your application, a human agent, or the processor.

WebhookFunction: validates the HMAC signature, extracts the sender, text, and conversationId, puts them on the inbound queue, returns 200. Fast, never fails because of slow downstream logic.

ProcessorFunction: reads from the inbound queue, calls handleInboundMessage to decide what to reply, puts the reply on the outbound queue. Has 60 seconds to work. No Sinch credentials needed here. If it fails, SQS retries automatically.

This means your processor never touches the Sinch API directly. A human agent, a support tool, or any other system can send messages through the same outbound queue.

The webhook function

Validates the signature, rejects stale requests, and enqueues. Nothing else.

The Function URL uses AuthType: NONE because Sinch needs to reach it without an AWS auth header. The HMAC signature check covers two things: the payload hasn't been tampered with, and the request was sent recently. The timestamp header is signed alongside the body, so an attacker can't replay a captured request after the 5-minute window closes. Without these checks, anyone who knows the URL can send arbitrary payloads.

import { createHmac, timingSafeEqual } from "crypto";
import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";

const ssm = new SSMClient({});
const sqs = new SQSClient({});
const SINCH_WEBHOOK_SECRET_PARAM = process.env.SINCH_WEBHOOK_SECRET_PARAM!;
const QUEUE_URL = process.env.QUEUE_URL!;
const TIMESTAMP_TOLERANCE_SECONDS = 300; // 5 minutes

let webhookSecret: string | null = null;

async function getWebhookSecret(): Promise<string> {
  if (webhookSecret) return webhookSecret;
  const res = await ssm.send(
    new GetParameterCommand({ Name: SINCH_WEBHOOK_SECRET_PARAM, WithDecryption: true })
  );
  webhookSecret = res.Parameter!.Value!;
  return webhookSecret;
}

function validateTimestamp(timestamp: string): boolean {
  const ts = parseInt(timestamp, 10);
  if (isNaN(ts)) return false;
  return Math.abs(Math.floor(Date.now() / 1000) - ts) <= TIMESTAMP_TOLERANCE_SECONDS;
}

function validateSignature(
  body: string, signature: string, nonce: string, timestamp: string, secret: string
): boolean {
  const signedData = body + "." + nonce + "." + timestamp;
  const expected = createHmac("sha256", secret).update(signedData).digest("base64");
  return signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

export const handler = async (event: { headers: Record<string, string>; body: string }) => {
  const body = event.body;
  const signature = event.headers["x-sinch-webhook-signature"];
  const nonce = event.headers["x-sinch-webhook-signature-nonce"];
  const timestamp = event.headers["x-sinch-webhook-signature-timestamp"];

  if (!signature || !nonce || !timestamp) {
    return { statusCode: 401, body: "Missing signature headers" };
  }

  if (!validateTimestamp(timestamp)) {
    console.error("Webhook timestamp outside acceptable window");
    return { statusCode: 401, body: "Request expired" };
  }

  const secret = await getWebhookSecret();

  if (!validateSignature(body, signature, nonce, timestamp, secret)) {
    console.error("Invalid webhook signature");
    return { statusCode: 401, body: "Invalid signature" };
  }

  const payload = JSON.parse(body);

  if (payload.message && payload.message.direction === "TO_APP") {
    const rawFrom = payload.message.channel_identity?.identity;
    const from = rawFrom && !rawFrom.startsWith('+') ? `+${rawFrom}` : rawFrom;
    const text = payload.message.contact_message?.text_message?.text;

    if (from && text) {
      await sqs.send(new SendMessageCommand({
        QueueUrl: QUEUE_URL,
        MessageBody: JSON.stringify({
          from,
          text,
          messageId: payload.message.id,
          conversationId: payload.message.conversation_id,
        }),
      }));
    }
  }

  return { statusCode: 200, body: "OK" };
};

The processor function

Reads from the inbound queue, runs your logic, and enqueues the reply. This is where your application lives.

import { SQSEvent } from "aws-lambda";
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";

const sqs = new SQSClient({});
const OUTBOUND_QUEUE_URL = process.env.OUTBOUND_QUEUE_URL!;

async function getConversation(from: string): Promise<Record<string, string> | null> {
  // Add your retrieval logic here, e.g. read from DynamoDB by 'from' (phone number)
  // to find what your application last sent to this customer.
  console.log("getConversation", { from });
  return null;
}

// Add your application logic here. The function signature and SQS wiring are done.
async function handleInboundMessage(from: string, text: string, conversationId: string): Promise<string> {
  const context = await getConversation(from);
  // context contains what your application originally sent, if you stored it in storeConversation.
  // For customer-initiated messages, context will be null. Treat them as fresh inquiries.
  return `Thanks for your message! You said: "${text}"`;
}

export const handler = async (event: SQSEvent) => {
  for (const record of event.Records) {
    const { from, text, conversationId } = JSON.parse(record.body);
    try {
      const reply = await handleInboundMessage(from, text, conversationId);
      await sqs.send(new SendMessageCommand({
        QueueUrl: OUTBOUND_QUEUE_URL,
        MessageBody: JSON.stringify({ to: from, message: reply }),
      }));
    } catch (err) {
      console.error(`Failed to process message from ${from}:`, err);
      throw err; // Let SQS retry
    }
  }
};

handleInboundMessage is where your logic goes. It calls getConversation first: a stub that looks up by the sender's phone number. If your application sent the first message and stored it in storeConversation, that's how you retrieve what was originally sent. For customer-initiated messages, getConversation returns null and you handle it as a fresh inquiry.

The sender function

SenderFunction is triggered by the outbound queue. Any message put on that queue gets sent to the recipient via Sinch. The processor puts replies there. Your application puts company-initiated messages there. A human agent's tool puts messages there. One function handles all of it.

Sinch credentials and auth logic live in exactly one place. Anything that needs to send a message puts { to, message } on the queue. No knowledge of the Sinch API required.

export const handler = async (event: SQSEvent): Promise<void> => {
  for (const record of event.Records) {
    const { to, message } = JSON.parse(record.body);
    // ... E164 validation, auth, Sinch API call ...
    const data = await response.json() as { message_id: string; accepted_time: string };
    await storeConversation(data.message_id, to, message);
  }
};

The messageId comes back from Sinch after every send. storeConversation is a stub: add your DynamoDB write there, keyed by the recipient's phone number, so you can look up what was sent when they reply.

To kick off a conversation from your application, put a message on the outbound queue:

aws sqs send-message \
  --queue-url YOUR_OUTBOUND_QUEUE_URL \
  --message-body '{"to": "+15559876543", "message": "Your appointment is tomorrow at 2pm. Reply to confirm."}'

YOUR_OUTBOUND_QUEUE_URL is in the deploy outputs as OutboundQueueUrl.

What an inbound message looks like

The webhook receives this from Sinch:

{
  "message": {
    "id": "01EXAMPLE8235TD19N21XQTH12B",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "What's my order status?"
      }
    },
    "channel_identity": {
      "channel": "SMS",
      "identity": "+15559876543"
    },
    "conversation_id": "01EXAMPLECONV172WMDB8008EFT"
  }
}

The webhook extracts from, text, and conversationId and puts them on the queue. The processor picks them up.

Deploying

If you followed the sending SMS post, your Sinch app is already configured. Skip to the SSM parameter setup below.

If you're starting here, configure the following in the Sinch Build Dashboard first:

Get access to the Conversation API. Click Conversation API in the left menu, accept the terms, and click Get Access.
Create a Conversation API app. Go to Conversation API > Apps and click Create app. Record the app ID.
Switch the app to Conversation mode. New apps default to Dispatch mode. Open your app, go to Settings, and change the processing mode to Conversation. This enables the conversation_id field in webhook payloads, which Sinch uses to track threads on their side. The conversationId is available in your processor if you want to use it as a thread key. This example keys on phone number instead, since that's available in both directions: Sinch returns it on inbound webhooks, and you already know the recipient when sending outbound. If you expect one active thread per number, phone number is the simpler choice.
Enable the SMS channel on your app. Open the app, find SMS in the channel list, click Set up channel, and connect your service plan.
Find your sender number. Go to SMS > Numbers. The assigned number is your SMS sender.
Note your project ID. Click the project name in the top bar and go to Project Settings.
Create an access key. Go to Settings > Access Keys. Record the key ID and secret. The secret is only shown once.

You'll need three things in SSM Parameter Store before deploying. If you followed the sending SMS post, your access key and secret are already there. The webhook secret is new to this post.

# Skip these two if you already have them from the sending SMS post
aws ssm put-parameter --name /sinch/access-key --value "YOUR_ACCESS_KEY" --type SecureString
aws ssm put-parameter --name /sinch/access-key-secret --value "YOUR_ACCESS_KEY_SECRET" --type SecureString

# New: a dedicated secret for this webhook's HMAC signature validation.
# Use a different value from any secret you set for the delivery receipts webhook.
aws ssm put-parameter \
  --name /sinch/conversation-webhook-secret \
  --value "your-webhook-secret-here" \
  --type SecureString

Then build and deploy from your preferred language directory:

cd typescript   # or: cd python
sam build
sam deploy --guided

sam deploy --guided will prompt for SinchRegion, SinchProjectId, SinchAppId, and SinchSmsSender. After the deploy completes, the outputs include WebhookUrl and OutboundQueueUrl.

Registering the webhook

Register the Function URL with Sinch so it starts receiving inbound message callbacks. You can do this in the Sinch Build Dashboard (Conversation API > Apps > your app > Webhooks) or via the API.

Get an OAuth 2.0 token:

curl https://auth.sinch.com/oauth2/token \
  -d grant_type=client_credentials \
  -u YOUR_ACCESS_KEY:YOUR_ACCESS_KEY_SECRET

Then register:

curl -X POST \
  "https://us.conversation.api.sinch.com/v1/projects/YOUR_PROJECT_ID/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "target": "YOUR_FUNCTION_URL",
    "target_type": "HTTP",
    "secret": "your-webhook-secret-here",
    "triggers": ["MESSAGE_INBOUND"]
  }'

The secret must match what you stored in SSM at /sinch/conversation-webhook-secret. Replace us with eu if your app is in the EU region.

Testing

Tail the logs first:

sam logs --stack-name YOUR_STACK_NAME --tail

Flow 1: Your application sends first

Put a message on the outbound queue using the URL from the deploy outputs:

aws sqs send-message \
  --queue-url YOUR_OUTBOUND_QUEUE_URL \
  --message-body '{"to": "+15559876543", "message": "Your appointment is tomorrow at 2pm. Reply to confirm."}'

The customer gets the SMS. When they reply, you'll see the webhook log the inbound enqueue, the processor log the outbound enqueue, and the sender log the Sinch call. Your phone gets the response.

Flow 2: Customer sends first

Text your Sinch number directly. The webhook logs the incoming message, the processor enqueues the reply, the sender logs the Sinch call, your phone gets the response.

Things worth knowing

Why three functions and two queues?

The webhook must return 200 quickly or Sinch retries. If your AI agent takes 10 seconds, the webhook would time out. The inbound queue decouples the two: the webhook always returns quickly and the processor gets its own 60-second window with automatic retries on failure.

The outbound queue does the same for sending. The processor doesn't need Sinch credentials or auth logic. It just enqueues { to, message }. The sender handles the Sinch API call in one place, which means your application backend and any human agent tools can send messages the same way without reimplementing credentials.

Retries are automatic

If the processor throws an error, SQS makes the message visible again after the visibility timeout. The visibility timeout is set to 360 seconds, six times the processor's 60-second Lambda function timeout. That gap is intentional: it prevents SQS from redelivering a message while the processor is still running it.

After three failures, the message moves to a dead-letter queue. Both the inbound and outbound queues have one. Monitor them for processing failures: messages there didn't make it through after three attempts.

Sinch stores conversation history too

In Conversation mode, Sinch keeps a copy of all messages for the retention period configured on your app (7 days by default, up to 180 days). You can query it via the Conversation API. That's useful for debugging and audit trails, but don't rely on it as your application's source of truth. Implement your own storage if you need conversation context beyond the retention window.

Duplicates are possible

SQS is at-least-once delivery. Your processor might see the same message twice. Use the messageId field as an idempotency key if your logic has side effects.

Non-text messages are ignored

The webhook extracts contact_message?.text_message?.text using optional chaining. If Sinch delivers a non-text message type (media, location, template), the text field is undefined and the message is silently dropped before it reaches the queue. That's the right default for a text conversation app. If your use case requires handling other types, add explicit branching in the webhook before the enqueue step.

This is the foundation for conversational AI

The processor function is where you plug in your agent. For multi-turn conversations that need to wait for replies and branch based on responses, Lambda Durable Functions let you write that as sequential code that suspends and resumes.

Wrapping up

You now have the full loop: user texts you, the webhook validates and enqueues, the processor generates a reply and sends it back. Clean separation, automatic retries, room for slow processing.

If you also need to know whether your outbound messages were delivered, see the delivery receipts post.

The source code for this post is available on GitHub: sinch-sms-conversation

The repo has a typescript/ and python/ directory, each fully self-contained with its own template.yaml. Pick your language and deploy from that directory.

What are you building with two-way SMS? An AI support agent? Appointment confirmations? Let me know in the comments.

Additional Resources

SMS Delivery Receipts on AWS Lambda

Gunnar Grosch — Fri, 29 May 2026 13:12:50 +0000

You sent an SMS. Did it arrive?

A password reset link that never reached the user. An appointment reminder that bounced because the number was disconnected. A fraud alert that failed silently while the transaction went through.

The previous post covered sending SMS from Lambda. But messages:send returning 200 only means Sinch accepted the message. It doesn't mean the recipient's phone received it. Delivery receipts close that gap. They tell you whether the message was delivered, and if not, why it failed. You can retry, fall back to email, alert an operator, or update a record. On the success side, you can mark a notification as confirmed, start a countdown timer for a response, or log proof of delivery for compliance.

The Sinch Conversation API delivers status updates as webhook callbacks. You register a URL, Sinch POSTs to it every time a message changes state, and your function logs or acts on the result. This post builds that webhook endpoint.

How delivery receipts work

After you send a message, it moves through a series of states:

QUEUED_ON_CHANNEL: Sinch accepted it and dispatched it to the SMS carrier
DELIVERED: the carrier confirmed it reached the recipient's device
FAILED: delivery failed (with a reason code explaining why)
READ: the recipient opened/read it (rare for SMS, more common on WhatsApp/RCS)

Each state change triggers a MESSAGE_DELIVERY callback to your webhook. A single sent message typically generates 2-3 callbacks as it moves through these states.

HMAC signature validation

When you create a webhook with a secret, Sinch signs every callback. Your function must verify the signature before processing anything. If it doesn't match, return 401 and ignore the payload.

The signature is: HMAC-SHA256(secret, body + "." + nonce + "." + timestamp), base64-encoded.

import { createHmac, timingSafeEqual } from "crypto";

function validateSignature(
  body: string, signature: string, nonce: string, timestamp: string, secret: string
): boolean {
  const signedData = body + "." + nonce + "." + timestamp;
  const expected = createHmac("sha256", secret).update(signedData).digest("base64");
  return signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

The Lambda handler

import { createHmac, timingSafeEqual } from "crypto";
import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";

const ssm = new SSMClient({});
const SINCH_WEBHOOK_SECRET_PARAM = process.env.SINCH_WEBHOOK_SECRET_PARAM!;

let webhookSecret: string | null = null;

async function getWebhookSecret(): Promise<string> {
  if (webhookSecret) return webhookSecret;
  const res = await ssm.send(
    new GetParameterCommand({ Name: SINCH_WEBHOOK_SECRET_PARAM, WithDecryption: true })
  );
  webhookSecret = res.Parameter!.Value!;
  return webhookSecret;
}

export const handler = async (event: { headers: Record<string, string>; body: string }) => {
  const body = event.body;
  const signature = event.headers["x-sinch-webhook-signature"];
  const nonce = event.headers["x-sinch-webhook-signature-nonce"];
  const timestamp = event.headers["x-sinch-webhook-signature-timestamp"];

  if (!signature || !nonce || !timestamp) {
    return { statusCode: 401, body: "Missing signature headers" };
  }

  const secret = await getWebhookSecret();

  if (!validateSignature(body, signature, nonce, timestamp, secret)) {
    console.error("Invalid webhook signature");
    return { statusCode: 401, body: "Invalid signature" };
  }

  const payload = JSON.parse(body);

  if (payload.message_delivery_report) {
    const report = payload.message_delivery_report;
    handleDeliveryReceipt(report.message_id, report.status, report.reason);
  }

  return { statusCode: 200, body: "OK" };
};

function validateSignature(
  body: string, signature: string, nonce: string, timestamp: string, secret: string
): boolean {
  const signedData = body + "." + nonce + "." + timestamp;
  const expected = createHmac("sha256", secret).update(signedData).digest("base64");
  return signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Replace this with your application logic
function handleDeliveryReceipt(messageId: string, status: string, reason?: any) {
  console.log(`Message ${messageId}: ${status}`);

  if (status === "FAILED") {
    // Alert, retry on a different channel, update a database record, etc.
    console.error(`Delivery failed:`, reason);
  }
}

handleDeliveryReceipt is where your logic goes. The demo logs the status. In production you might update a database record, trigger an alert on failure, or retry via a different channel.

What a delivery receipt looks like

Here's an actual callback payload for a successfully delivered message:

{
  "app_id": "01EXAMPLE1NFQ9H0N6HBWPTB10A",
  "accepted_time": "2026-05-28T09:34:19.812Z",
  "event_time": "2026-05-28T09:34:21.267Z",
  "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message_delivery_report": {
    "message_id": "01EXAMPLE54NBHBQZDHHHPYQ3FS",
    "conversation_id": "01EXAMPLEBTR4C1HJZS05PVTXZ8",
    "status": "DELIVERED",
    "channel_identity": {
      "channel": "SMS",
      "identity": "+15559876543",
      "app_id": ""
    },
    "contact_id": "01EXAMPLEN3NANZ05VM0FS80EHD",
    "metadata": "",
    "processing_mode": "CONVERSATION"
  }
}

And here's a failed delivery:

{
  "message_delivery_report": {
    "message_id": "01EQBF0BT63J7S1FEKJZ0Z08VD",
    "status": "FAILED",
    "reason": {
      "code": "RECIPIENT_NOT_REACHABLE",
      "description": "The channel reported: Unable to deliver message to recipient",
      "sub_code": "UNSPECIFIED_SUB_CODE",
      "channel_code": "150"
    }
  }
}

Common failure codes: RECIPIENT_NOT_REACHABLE, RECIPIENT_INVALID_CHANNEL_IDENTITY, OUTSIDE_ALLOWED_SENDING_WINDOW, CHANNEL_FAILURE.

Correlating receipts to your business logic

The delivery receipt includes the message_id from when you sent the message. If you set message_metadata in your original messages:send request, it's also included in the receipt. This is how you tie a delivery status back to a specific order, alert, or notification in your system.

The triggers array controls which callback types Sinch sends to this URL. MESSAGE_DELIVERY means "only delivery receipts." Other triggers you might use:

MESSAGE_INBOUND: a user sent you a message (covered in the companion post about two-way conversations)
EVENT_INBOUND: typing indicators and other events from users
CONVERSATION_START / CONVERSATION_STOP: conversation lifecycle events
CONTACT_CREATE: a new contact was created

You can subscribe to multiple triggers on the same webhook, or create separate webhooks for different triggers. Up to 5 webhooks per app.

Setting up the webhook endpoint

A Lambda Function URL is the simplest way to expose a Lambda as an HTTPS endpoint for Sinch to call. No API Gateway needed.

DeliveryReceiptFunction:
  Type: AWS::Serverless::Function
  Properties:
    Runtime: nodejs22.x
    Handler: src/delivery-receipt.handler
    CodeUri: webhook/
    FunctionUrlConfig:
      AuthType: NONE
    Environment:
      Variables:
        SINCH_WEBHOOK_SECRET_PARAM: !Ref SinchWebhookSecretParam

The complete template (with Parameters and Outputs) is in the repo. The snippet above shows the key parts.

AuthType: NONE makes the URL publicly accessible. That's why HMAC validation is required.

Deploying

Store the webhook secret in SSM (same region where you'll deploy):

aws ssm put-parameter \
  --name /sinch/webhook-secret \
  --value "your-webhook-secret-here" \
  --type SecureString

Then build and deploy:

sam build
sam deploy --guided

After the deploy completes, sam deploy prints the stack outputs including your Function URL. Copy it for the next step.

Registering the webhook

Register the Function URL with Sinch so it starts receiving delivery receipt callbacks. You can do this via the dashboard (Conversation API > Apps > your app > Webhooks) or via the API.

First, get an OAuth 2.0 token:

curl https://auth.sinch.com/oauth2/token \
  -d grant_type=client_credentials \
  -u YOUR_ACCESS_KEY:YOUR_ACCESS_KEY_SECRET

Then register the webhook using the access_token from the response:

curl -X POST \
  "https://us.conversation.api.sinch.com/v1/projects/YOUR_PROJECT_ID/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "target": "YOUR_FUNCTION_URL",
    "target_type": "HTTP",
    "secret": "your-webhook-secret-here",
    "triggers": ["MESSAGE_DELIVERY"]
  }'

You can also do this in the Sinch Build Dashboard under Conversation API > Apps > your app > Webhooks.

The secret value here must match what you stored in SSM at /sinch/webhook-secret.

Watching the logs

After registering the webhook, send an SMS through your Sinch Conversation app (using the Lambda function from the previous post, the Sinch dashboard, or the API directly) and tail the logs:

sam logs --stack-name sinch-sms-delivery-receipts --tail

You should see delivery receipt callbacks arriving within seconds of sending a message.

Things worth knowing

Multiple callbacks per message

Each sent message generates 2-3 callbacks. First QUEUED_ON_CHANNEL, then DELIVERED or FAILED. Don't treat the first callback as the final status. This means your function is invoked 2-3 times per message you send. If you're sending 1000 messages, expect 2000-3000 invocations for delivery receipts alone. At Lambda pricing this is negligible, but worth knowing when you look at your metrics.

Return 200 immediately

Sinch expects a quick response. For simple logging or a single database write, processing inline is fine. If your logic involves external API calls or complex processing, accept the callback immediately, write the payload to SQS, and return 200. A separate function processes the queue.

Callbacks can arrive out of order

A DELIVERED callback might arrive before QUEUED_ON_CHANNEL due to network timing. If your logic depends on ordering, track state per message ID rather than assuming sequential delivery.

Duplicates are possible

Network issues can cause the same callback to arrive more than once. Use message_delivery_report.message_id + status as a deduplication key.

Retries

Sinch retries on 5xx, 429, and network failures with exponential backoff. 4xx (except 429) is treated as a permanent failure and not retried. If your function is down, you'll miss callbacks permanently once retries are exhausted.

Wrapping up

You now know whether your messages are reaching recipients. The handler validates the webhook signature, parses the delivery report, and routes to a function you control.

The natural next step is receiving inbound messages: what happens when the user replies? That's covered in the companion post about two-way SMS conversations.

The source code for this post is available on GitHub: gunnargrosch/sinch-sms-delivery-receipts

The repo also includes a Python implementation of the same handler.

Have you built retry logic on top of delivery receipts, or are you using them differently? I'd like to hear about it in the comments.

Additional Resources

Sending SMS from AWS Lambda

Gunnar Grosch — Thu, 28 May 2026 16:53:37 +0000

A user places an order. Your backend processes it, updates the database, and fires an event. Somewhere in that chain, you want to send them a text message: "Your order is confirmed. It ships tomorrow."

Or maybe it's 2 AM and a CloudWatch alarm just fired. You need an on-call engineer to know about it right now, not when they next check their email.

Or a long-running job just finished processing a large file. The user who submitted it hours ago should know it's ready.

In all of these cases, the pattern is the same: something happens, and you need to send an SMS as part of the response. Lambda is the natural fit for event-driven logic, whether the trigger comes from within AWS or from an external system. You just need a way to get a text message out.

Sinch's Conversation API handles SMS, WhatsApp, RCS, and more through a single endpoint. Your Lambda function won't change if you add channels later.

The post walks through building a Lambda function in TypeScript and Python that sends an SMS using the Sinch Conversation API. Credentials are stored in SSM Parameter Store. The handler is structured so it can be wired to whatever triggers you need: direct invocation, SQS, EventBridge, SNS, or API Gateway.

Prerequisites

The Sinch dashboard setup takes about 10 minutes. After that, sending is a single API call. You'll need a Sinch account (sign up here, a trial account is enough to test, see pricing for details), the AWS SAM CLI, and Node.js 22+ or Python 3.13+.

Before writing any code, configure the following in the Sinch Build Dashboard:

Get access to Conversation API. Click Conversation API in the left menu, accept the terms, and click GET ACCESS.
Create a Conversation API app. Go to Conversation API > Apps and click Create app. Record the app ID.
Enable the SMS channel on your app. Open the app, find SMS in the channel list, click Set up channel, and connect your service plan.
Find your sender number. Go to SMS > SMS Channel > Numbers. The assigned number is your SMS_SENDER value.
Note your project ID. Click the project name in the top bar and go to Project Settings.
Create an access key. Go to Settings > Access Keys. Record the access key ID and secret. The secret is only shown once.

Note: on a trial account, you can only send to verified numbers and the message content is fixed. To send to any number with custom content, upgrade your account.

Storing credentials in SSM Parameter Store

Create the two parameters before deploying. Run these in the same AWS region where you'll deploy the Lambda:

aws ssm put-parameter \
  --name /sinch/access-key \
  --value "YOUR_ACCESS_KEY" \
  --type SecureString

aws ssm put-parameter \
  --name /sinch/access-key-secret \
  --value "YOUR_ACCESS_KEY_SECRET" \
  --type SecureString

The Lambda function

The structure is the same in both languages: module-level caches for credentials and the OAuth token, a send_sms / sendSms function that owns the validation and API call, and a thin handler that adapts the event.

TypeScript

import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";
import { SQSEvent, SQSBatchResponse, EventBridgeEvent, SNSEvent } from "aws-lambda";

const ssm = new SSMClient({});
const SINCH_REGION = process.env.SINCH_REGION || "us";
const SINCH_PROJECT_ID = process.env.SINCH_PROJECT_ID!;
const SINCH_APP_ID = process.env.SINCH_APP_ID!;
const SINCH_SMS_SENDER = process.env.SINCH_SMS_SENDER!;
const SINCH_ACCESS_KEY_PARAM = process.env.SINCH_ACCESS_KEY_PARAM!;
const SINCH_ACCESS_KEY_SECRET_PARAM = process.env.SINCH_ACCESS_KEY_SECRET_PARAM!;

// Cached at module level. Reused across warm invocations regardless of trigger type
let credentials: { accessKey: string; accessKeySecret: string } | null = null;
let cachedToken: { value: string; expiresAt: number } | null = null;

async function getCredentials() {
  if (credentials) return credentials;
  const [keyRes, secretRes] = await Promise.all([
    ssm.send(new GetParameterCommand({ Name: SINCH_ACCESS_KEY_PARAM, WithDecryption: true })),
    ssm.send(new GetParameterCommand({ Name: SINCH_ACCESS_KEY_SECRET_PARAM, WithDecryption: true })),
  ]);
  credentials = {
    accessKey: keyRes.Parameter!.Value!,
    accessKeySecret: secretRes.Parameter!.Value!,
  };
  return credentials;
}

async function getAccessToken(): Promise<string> {
  const now = Date.now();
  if (cachedToken && now < cachedToken.expiresAt) return cachedToken.value; // Refreshes automatically when expired

  const { accessKey, accessKeySecret } = await getCredentials();
  const encoded = Buffer.from(`${accessKey}:${accessKeySecret}`).toString("base64");

  // Exchange credentials for a short-lived OAuth 2.0 Bearer token (valid ~1 hour).
  // Basic auth is rate-limited and for testing only. Don't use it directly on the Sinch API.
  const response = await fetch("https://auth.sinch.com/oauth2/token", {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${encoded}`,
    },
    body: "grant_type=client_credentials",
  });

  if (!response.ok) throw new Error(`Token request failed: ${await response.text()}`);

  const data = await response.json() as { access_token: string; expires_in: number };
  cachedToken = { value: data.access_token, expiresAt: now + (data.expires_in - 60) * 1000 };
  return cachedToken.value;
}

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

async function sendSms(to: string, message: string) {
  if (!E164_REGEX.test(to)) {
    throw new Error(`Invalid phone number format. Use E.164 (e.g. +15551234567), got: ${to}`);
  }

  const token = await getAccessToken();

  const response = await fetch(
    `https://${SINCH_REGION}.conversation.api.sinch.com/v1/projects/${SINCH_PROJECT_ID}/messages:send`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
      body: JSON.stringify({
        app_id: SINCH_APP_ID,
        recipient: { identified_by: { channel_identities: [{ channel: "SMS", identity: to }] } },
        message: { text_message: { text: message } },
        channel_properties: { SMS_SENDER: SINCH_SMS_SENDER },
      }),
    }
  );

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Sinch API error ${response.status}: ${error}`);
  }

  return response.json();
}

// --- Direct invocation (default) ---
export const handler = async (event: { to: string; message: string }) => {
  if (!event.to || !event.message) {
    return { statusCode: 400, body: "Missing to or message" };
  }
  try {
    return { statusCode: 200, body: await sendSms(event.to, event.message) };
  } catch (err) {
    console.error(err);
    return { statusCode: 500, body: String(err) };
  }
};

// --- SQS (uncomment to use) ---
// Message body format: { "to": "+15551234567", "message": "Hello!" }
// Returns batchItemFailures so only failed records are retried, preventing duplicate sends.
//
// export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
//   const failures: { itemIdentifier: string }[] = [];
//   for (const record of event.Records) {
//     try {
//       const payload = JSON.parse(record.body);
//       await sendSms(payload.to, payload.message);
//     } catch (err) {
//       console.error(`Failed record ${record.messageId}:`, err);
//       failures.push({ itemIdentifier: record.messageId });
//     }
//   }
//   return { batchItemFailures: failures };
// };

// --- EventBridge (uncomment to use) ---
// Event detail format: { "to": "+15551234567", "message": "Hello!" }
//
// export const handler = async (
//   event: EventBridgeEvent<"SendSms", { to: string; message: string }>
// ) => {
//   await sendSms(event.detail.to, event.detail.message);
// };

// --- SNS (uncomment to use) ---
// SNS message body format: { "to": "+15551234567", "message": "Hello!" }
//
// export const handler = async (event: SNSEvent) => {
//   for (const record of event.Records) {
//     const payload = JSON.parse(record.Sns.Message);
//     await sendSms(payload.to, payload.message);
//   }
// };

Python

import json
import os
import re
import time
import urllib.request
import urllib.error
from base64 import b64encode
import boto3

ssm = boto3.client("ssm")

SINCH_REGION = os.environ.get("SINCH_REGION", "us")
SINCH_PROJECT_ID = os.environ["SINCH_PROJECT_ID"]
SINCH_APP_ID = os.environ["SINCH_APP_ID"]
SINCH_SMS_SENDER = os.environ["SINCH_SMS_SENDER"]
SINCH_ACCESS_KEY_PARAM = os.environ["SINCH_ACCESS_KEY_PARAM"]
SINCH_ACCESS_KEY_SECRET_PARAM = os.environ["SINCH_ACCESS_KEY_SECRET_PARAM"]

E164_REGEX = re.compile(r"^\+[1-9]\d{1,14}$")

# Module-level cache. Shared across warm invocations regardless of trigger type
_credentials = None
_token_cache = {"value": None, "expires_at": 0}


def get_credentials():
    global _credentials
    if _credentials:
        return _credentials
    key = ssm.get_parameter(Name=SINCH_ACCESS_KEY_PARAM, WithDecryption=True)["Parameter"]["Value"]
    secret = ssm.get_parameter(Name=SINCH_ACCESS_KEY_SECRET_PARAM, WithDecryption=True)["Parameter"]["Value"]
    _credentials = (key, secret)
    return _credentials


def get_access_token():
    now = time.time()
    if _token_cache["value"] and now < _token_cache["expires_at"]:
        return _token_cache["value"]

    access_key, access_key_secret = get_credentials()
    encoded = b64encode(f"{access_key}:{access_key_secret}".encode()).decode()

    req = urllib.request.Request(
        "https://auth.sinch.com/oauth2/token",
        data=b"grant_type=client_credentials",
        headers={
            "Content-Type": "application/x-www-form-urlencoded",
            "Authorization": f"Basic {encoded}",
        },
        method="POST",
    )
    try:
        with urllib.request.urlopen(req) as resp:
            data = json.loads(resp.read())
    except urllib.error.HTTPError as e:
        raise RuntimeError(f"Token request failed {e.code}: {e.read().decode()}")

    _token_cache["value"] = data["access_token"]
    _token_cache["expires_at"] = now + data["expires_in"] - 60
    return _token_cache["value"]


def send_sms(to, message):
    if not E164_REGEX.match(to):
        raise ValueError(f"Invalid phone number format. Use E.164 (e.g. +15551234567), got: {to}")

    token = get_access_token()
    payload = json.dumps({
        "app_id": SINCH_APP_ID,
        "recipient": {"identified_by": {"channel_identities": [{"channel": "SMS", "identity": to}]}},
        "message": {"text_message": {"text": message}},
        "channel_properties": {"SMS_SENDER": SINCH_SMS_SENDER},
    }).encode()

    url = f"https://{SINCH_REGION}.conversation.api.sinch.com/v1/projects/{SINCH_PROJECT_ID}/messages:send"
    req = urllib.request.Request(
        url, data=payload,
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req) as response:
            return json.loads(response.read())
    except urllib.error.HTTPError as e:
        error = e.read().decode()
        print(f"Sinch API error: {error}")
        raise RuntimeError(f"Sinch API error {e.code}: {error}")


# --- Direct invocation (default) ---
def handler(event, context):
    to = event.get("to")
    message = event.get("message")
    if not to or not message:
        return {"statusCode": 400, "body": "Missing to or message"}
    try:
        return {"statusCode": 200, "body": send_sms(to, message)}
    except Exception as e:
        print(f"Error: {e}")
        return {"statusCode": 500, "body": str(e)}


# --- SQS (uncomment to use) ---
# Message body format: {"to": "+15551234567", "message": "Hello!"}
# Returns batchItemFailures so only failed records are retried, preventing duplicate sends.
#
# def handler(event, context):
#     failures = []
#     for record in event["Records"]:
#         try:
#             payload = json.loads(record["body"])
#             send_sms(payload["to"], payload["message"])
#         except Exception as e:
#             print(f"Failed record {record['messageId']}: {e}")
#             failures.append({"itemIdentifier": record["messageId"]})
#     return {"batchItemFailures": failures}


# --- EventBridge (uncomment to use) ---
# Event detail format: {"to": "+15551234567", "message": "Hello!"}
#
# def handler(event, context):
#     detail = event["detail"]
#     send_sms(detail["to"], detail["message"])


# --- SNS (uncomment to use) ---
# SNS message body format: {"to": "+15551234567", "message": "Hello!"}
#
# def handler(event, context):
#     for record in event["Records"]:
#         payload = json.loads(record["Sns"]["Message"])
#         send_sms(payload["to"], payload["message"])

The SAM template

The repo uses a single template.yaml at the root that deploys all four functions together (Node.js and Python, raw HTTP and SDK). Here's the relevant section for the Node.js raw HTTP function:

AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31

Globals:
  Function:
    Timeout: 10
    MemorySize: 256
    Environment:
      Variables:
        SINCH_REGION: !Ref SinchRegion
        SINCH_PROJECT_ID: !Ref SinchProjectId
        SINCH_APP_ID: !Ref SinchAppId
        SINCH_SMS_SENDER: !Ref SinchSmsSender
        SINCH_ACCESS_KEY_PARAM: !Ref SinchAccessKeyParam
        SINCH_ACCESS_KEY_SECRET_PARAM: !Ref SinchAccessKeySecretParam

Parameters:
  SinchRegion:
    Type: String
    Default: us
    AllowedValues: [us, eu]
  # ... SinchProjectId, SinchAppId, SinchSmsSender,
  #     SinchAccessKeyParam, SinchAccessKeySecretParam

Resources:
  NodeHttpFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: nodejs22.x
      Handler: src/handler.handler
      CodeUri: node-http/
      Policies:
        - Statement:
            - Effect: Allow
              Action: ssm:GetParameter
              Resource:
                - !Sub "arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter${SinchAccessKeyParam}"
                - !Sub "arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter${SinchAccessKeySecretParam}"
    Metadata:
      BuildMethod: esbuild
      BuildProperties:
        Minify: false
        Target: es2022
        EntryPoints:
          - node-http/src/handler.ts

Deploy from the repo root:

sam build
sam deploy --guided

SAM handles all dependencies automatically during sam build: Node.js packages via npm install, Python packages via requirements.txt.

Invoking the function

With no event source attached, you invoke the function directly with a JSON payload. The simplest way is the AWS CLI:

# Get the function name from the stack outputs after sam deploy --guided,
# then invoke it:
aws lambda invoke \
  --function-name <NodeHttpFunctionName from outputs> \
  --payload '{"to": "+15559876543", "message": "Hello from Lambda!"}' \
  --cli-binary-format raw-in-base64-out \
  response.json

cat response.json

A successful response looks like:

{
  "statusCode": 200,
  "body": {
    "accepted_time": "2026-05-27T18:00:00.000Z",
    "message_id": "01ABC123DEF456GHI789JKL012"
  }
}

message_id is what you'd use to correlate delivery receipts if you set up a webhook.

If something goes wrong, the Sinch API returns a structured error:

{
  "statusCode": 400,
  "body": "{\"error\":{\"code\":400,\"message\":\"recipient identity is not a valid MSISDN\",\"status\":\"INVALID_ARGUMENT\"}}"
}

Common causes: malformed phone number, wrong app_id, region mismatch between your app and service plan, or missing SMS_SENDER without a default originator configured.

When you're ready to wire it up to something, change only the handler signature. sendSms() doesn't change. The SAM template has commented event source blocks for SQS, EventBridge, SNS, and API Gateway ready to uncomment:

SQS for queued, rate-controlled sending
EventBridge for event-driven notifications from other AWS services (order placed, alarm fired, job completed)
SNS for fan-out scenarios where multiple subscribers need to react
API Gateway if you need an HTTP endpoint for third-party webhooks or client-side triggers

Testing locally

Create an event file:

{
  "to": "+15559876543",
  "message": "Test from local"
}

Then invoke locally with SAM:

sam local invoke NodeHttpFunction --event event.json
# or
sam local invoke PythonHttpFunction --event event.json

Things worth knowing

Phone numbers must be E.164

The to value must be in E.164 format: +15551234567, not 5551234567 or (555) 123-4567. The handler validates this before calling the API. The Sinch API won't normalize it for you.

Long messages get split

SMS has a 160-character limit for standard GSM encoding. Longer messages get split into multiple parts. You can cap this with SMS_MAX_NUMBER_OF_MESSAGE_PARTS in channel_properties:

"channel_properties": {
  "SMS_SENDER": "+15551231234",
  "SMS_MAX_NUMBER_OF_MESSAGE_PARTS": "2"
}

If the message would require more parts than the cap, the API rejects it. It won't truncate or silently drop it. You'll get an error back, so you can handle it in your application.

Error handling and delivery status

When sendSms() throws, the handler logs the error and returns a 500. If the Lambda is invoked asynchronously (EventBridge, SNS), Lambda will retry up to two more times by default before sending the event to a dead-letter queue if one is configured. If you're sending high volumes, set up a DLQ on the function so failed sends don't disappear silently.

For SQS triggers, be aware of partial batch failures. If one message in a batch fails, the entire batch is retried by default, which means already-sent messages get sent again. To avoid duplicate SMS, implement partial batch failure reporting: catch errors per record and return { batchItemFailures: [{ itemIdentifier: record.messageId }] } so only the failed records are retried. The SQS handler variant in the code has a comment pointing to this.

For delivery status on the recipient's device, the Conversation API sends a callback to a webhook URL you configure on your app. The status will be either DELIVERED or FAILED. To receive these, register a webhook in the Sinch Build Dashboard under your app's webhook settings, or via the Webhooks API. That's a natural next step once this is working.

The SDK and other languages

This post uses raw HTTP. The tradeoff compared to the official Sinch SDKs (Node.js, Python, Java, .NET): raw HTTP has zero runtime dependencies and the auth flow is visible in the code. The SDKs remove the token caching code entirely (they handle OAuth 2.0 internally) but add a dependency. Both are valid. The repo includes node-sdk and python-sdk examples alongside the raw HTTP ones.

Wrapping up

The function is deployed, the credentials are in SSM, and you have a handler that works with whatever trigger makes sense for your use case.

The source code for this post is available on GitHub: gunnargrosch/sinch-sms-lambda

What are you building that needs SMS notifications? Let me know in the comments.

Additional Resources

Visualizing AWS Lambda Durable Function Workflows with durable-viz

Gunnar Grosch — Fri, 27 Mar 2026 15:20:58 +0000

If you're new to durable functions, start with the durable functions post for the core concepts. The short version: your handler re-runs from the beginning on every resume, but completed steps return cached results instantly instead of re-executing. The SDK handles this checkpointing and replay transparently.

Durable functions encourage you to write sequential code. But the execution flow isn't always sequential. You have parallel branches that fan out and converge. Conditionals that route to callbacks or skip to the end. Invocations that call other Lambda functions. The more primitives you use, the harder it gets to see the full picture just by reading the handler.

I hit this when building the purchasing coordinator. Five specialist agents dispatched in parallel, a conditional approval callback, plan and synthesis steps on either side. The code reads top to bottom, but the workflow branches and converges in ways that aren't obvious from the source. Two primitives in particular: context.invoke() calls another Lambda function with automatic checkpointing (unlike the AWS SDK's lambda.invoke(), the result is cached so the target function isn't called again on replay), and waitForCallback suspends the workflow until an external signal arrives. This is how the purchasing coordinator pauses for human approval.

So I built durable-viz: a static analysis tool that turns durable function handlers into flowcharts. No deployment, no execution, no AWS credentials. Point it at a source file and it extracts the workflow structure from the code.

It supports TypeScript, Python, and Java. You can run it as a CLI (Mermaid output, browser, or JSON), or as a VS Code extension with a live diagram panel next to your code.

What It Does

Run durable-viz against any file containing a durable function handler:

npx durable-viz handler.ts --open

It parses the file, extracts the durable primitives (step, parallel, invoke, waitForCallback, conditionals), builds a directed graph, and renders it as a Mermaid flowchart. The --open flag generates an interactive HTML page with zoom, pan, and PNG export.

Here's what the purchasing coordinator from the multi-agent post looks like:

npx durable-viz src/handlers/coordinator.ts

The four-phase flow is immediately visible: plan, five specialists fanning out from a parallel node, synthesize, and the conditional approval callback gated by a diamond. The "no" branch skips straight to End. Each node shape encodes the primitive type (the --open browser view and VS Code extension add color coding). These primitives (step, parallel, invoke, waitForCallback) are the SDK methods that automatically checkpoint their results. On replay, completed primitives return cached results without re-executing. That's what makes them "durable."

The tool didn't execute the code or read a deployment. It parsed the TypeScript AST, found withDurableExecution(), walked the handler body, and extracted every durable primitive with its name and structure. The five specialist branches came from resolving the SPECIALISTS registry object at module scope.

CLI

The default output is Mermaid flowchart syntax printed to stdout. Paste it into GitHub Markdown, Notion, Confluence, or any Mermaid-compatible renderer.

npx durable-viz handler.ts

You can change the graph direction from top-down to left-right:

npx durable-viz handler.ts --direction LR

The --open flag generates a self-contained HTML page and opens it in your browser. Dark theme, scroll-to-zoom, click-drag panning, and fit-to-view. You can save the diagram as a high-resolution PNG for documentation, pull requests, or presentations.

npx durable-viz handler.ts --open

For custom tooling, --json outputs the raw workflow graph (nodes, edges, source line numbers):

npx durable-viz handler.ts --json

VS Code Extension

The extension renders the diagram in a side panel next to your code. Install from the VS Code Marketplace, then open a durable function handler and run Durable Viz: Open Lambda Durable Function Workflow from the command palette.

Feature	Description
Click-to-navigate	Click any node to jump to that line in the source file
Auto-refresh	Diagram updates on file save
Save PNG	Export the diagram as a high-resolution transparent PNG
Source view	View the raw Mermaid syntax or JSON graph

The extension supports zoom, pan, direction toggle, and fit-to-view. See the Marketplace listing for the full feature list.

Multi-Language Support

The tool supports TypeScript/JavaScript, Python, and Java. Each language has its own parser, but the graph model, edge builder, and renderers are shared.

TypeScript / JavaScript

Uses ts-morph for full AST parsing. This is the most capable parser with two features the others don't have:

Function-reference following. If your handler calls a helper function that accepts DurableContext, the parser resolves the call and inlines the helper's durable primitives at the call site. Only works for functions defined in the same file.
Registry key resolution. For context.parallel() calls that use .map() over a module-scope registry object, the parser enumerates the registry keys to show all possible parallel branches. This is how the purchasing coordinator's five specialists appear in the diagram even though the code dispatches them dynamically.

Python

npx durable-viz examples/order_processor.py --direction LR

Finds @durable_execution decorated handlers and extracts context.<method>() calls. Uses indentation to determine block boundaries.

Java (preview)

npx durable-viz Handler.java --open

Finds classes extending DurableHandler and extracts ctx.<method>() calls from the handleRequest method. Some primitives (parallel, waitForCallback, waitForCondition) are still in development in the Java durable execution SDK.

Both the Python and Java parsers use regex rather than full AST parsing. This keeps the tool as a single Node.js package without requiring Python or Java parser dependencies. The trade-off: standard single-line call patterns work well, but method calls split across many lines or unusual argument formatting may not be detected. For most idiomatic durable function code, it works without issues.

Supported Primitives

Primitive	TypeScript	Python	Java (preview)
Step	`context.step()`	`context.step()`	`ctx.step()`
Invoke	`context.invoke()`	`context.invoke()`	`ctx.invoke()`
Parallel	`context.parallel()`	`context.parallel()`	in development
Map	`context.map()`	`context.map()`	in development
Wait	`context.wait()`	`context.wait()`	`ctx.wait()`
Wait for Callback	`context.waitForCallback()`	`context.wait_for_callback()`	in development
Create Callback	`context.createCallback()`	`context.create_callback()`	`ctx.createCallback()`
Wait for Condition	`context.waitForCondition()`	`context.wait_for_condition()`	in development
Child Context	`context.runInChildContext()`	`context.run_in_child_context()`	`ctx.runInChildContext()`

TypeScript also detects context.promise.all(), context.promise.any(), context.promise.race(), and context.promise.allSettled().

Visual encoding

Each primitive type has a distinct shape and color:

Node	Shape	Color
Start / End	Stadium	Blue
Step	Rectangle	Green
Invoke	Trapezoid	Amber
Parallel / Map	Hexagon	Purple
Wait / Callback	Circle	Red
Condition	Diamond	Indigo
Child Context	Subroutine	Teal

How It Works

The tool performs static analysis on your source file. It never imports, executes, or deploys your code.

The architecture is a three-stage pipeline:

[source file] → Parser → WorkflowGraph → Renderer → [output]
                  │                          │
          TypeScript / Python / Java    Mermaid / JSON

The parser interface

Adding a new language means implementing two methods:

export interface Parser {
  extensions: string[]
  parseFile(filePath: string, options?: ParseOptions): WorkflowGraph
}

extensions declares which file types the parser handles. parseFile takes a file path and returns a WorkflowGraph with nodes, edges, and source line numbers. The dispatcher selects the right parser by file extension.

The graph model

The parser produces a WorkflowGraph: an ordered list of nodes with branches (for parallel blocks) and metadata (for conditionals). Here's a simplified view of what each node looks like:

interface WorkflowNode {
  id: string
  kind: 'start' | 'end' | 'step' | 'invoke' | 'parallel' | 'map'
      | 'wait' | 'waitForCallback' | 'condition' | /* ... */  // maps to the primitives table above
  label: string
  branches?: WorkflowBranch[]   // for parallel/map nodes
  thenCount?: number            // for conditions: nodes in the then-branch
  thenReturns?: boolean         // for conditions: does then-branch return?
  sourceLine?: number           // 1-based line number for click-to-navigate
}

The edge builder constructs edges from the node list, handling sequential flow, parallel fan-out/fan-in, and conditional routing.

For conditionals, the parser tracks whether the if block ends with a return. If it does, the "yes" branch connects to End instead of falling through. The "no" branch skips the conditional block and continues to the next node.

Registry key resolution in practice

Here's a pattern from the purchasing coordinator. Don't worry about the specifics of the durable function code. The key thing is that the parallel branches are built dynamically at runtime from a registry object:

const SPECIALISTS: Record<string, { functionName: string; display: string }> = {
  'price-research': { functionName: process.env.PRICE_RESEARCH_FUNCTION!, display: 'Price Research' },
  'financing': { functionName: process.env.FINANCING_FUNCTION!, display: 'Financing' },
  // ... 3 more
}

const results = await context.parallel('specialists',
  plan.specialists.map((spec) => ({
    name: spec.name,
    func: async (ctx) => {
      const result = await ctx.invoke(spec.name, specialist.functionName, { prompt: spec.prompt })
      return { name: spec.name, response: result.response }
    },
  }))
)

The .map() call means the parallel branches are determined at runtime. The parser can't execute the code, but it can look at the SPECIALISTS object and enumerate its keys. It finds five keys, creates five invoke branches, and labels them with the key names. This is how the diagram shows all five specialists even though the code builds the branch list dynamically.

If the parser can't resolve the registry (the object is imported from another file, or the pattern doesn't match), it falls back to showing a single representative branch.

If you point the tool at a file that isn't a durable function handler, or a file with syntax errors, it exits with a clear error message. The VS Code extension shows the error in the webview panel instead of a diagram.

Design Decisions

Static analysis over runtime tracing

The main design choice: parse the code, don't execute it. Runtime tracing would give you the actual execution path for a specific input, but it requires deployment, credentials, and a real invocation. Static analysis gives you all possible paths from the source alone. You see every parallel branch, every conditional route, every callback. The trade-off is that dynamic branches (like the specialist .map()) require heuristics to resolve.

For documentation and code review, seeing all possible paths is usually more useful than seeing one specific execution. For debugging a specific run, the durable execution history API (get-durable-execution) is the right tool.

Language-agnostic graph model

The parsers are language-specific. The graph model, edge builder, and renderers are not. Adding a new language means writing a parser that produces WorkflowGraph nodes. Everything downstream is shared. The TypeScript parser uses ts-morph for full AST analysis. The Python and Java parsers use regex, which handles standard patterns well but can miss unusual formatting. The regex approach was a deliberate trade-off: full AST parsing for Python would require a Python parser dependency, and Java would need a Java parser. Regex keeps the tool as a single Node.js package.

Visual encoding for primitive types

Each primitive type gets a unique shape and color combination so you can identify the primitive at a glance without reading labels. Steps are green rectangles (the most common node). Invocations are amber trapezoids (they call out to external functions). Parallel blocks are purple hexagons (they branch). Callbacks are red circles (they suspend execution). Conditionals are indigo diamonds (standard flowchart convention). The color palette is optimized for dark backgrounds since most developer tools use dark themes.

Try It Out

You'll need:

Node.js 20+

Run against the examples

Clone the repo and run against the included examples:

git clone https://github.com/gunnargrosch/durable-viz.git
cd durable-viz

# TypeScript order workflow
npx durable-viz examples/order-workflow.ts --open

# Python order processor
npx durable-viz examples/order_processor.py --open

# Java order processor
npx durable-viz examples/OrderProcessor.java --open

Run against the purchasing coordinator

If you have the multi-agent purchasing demo cloned:

cd durable-multi-agent-purchasing
npx durable-viz src/handlers/coordinator.ts --open

Run against your own handler

For your own durable function handlers, npx downloads and runs the tool directly. No cloning needed:

npx durable-viz path/to/your-handler.ts --open

Install the VS Code extension

Search "Durable Viz" in the Extensions panel, or run:

ext install gunnargrosch.durable-viz

Open a durable function handler, open the command palette, and run Durable Viz: Open Lambda Durable Function Workflow.

Additional Resources

durable-viz on GitHub
durable-viz on npm
VS Code Marketplace
Multi-Agent Systems on AWS Lambda with Durable Functions: The purchasing coordinator used as the primary example
AWS Lambda Durable Functions: Building Long-Running Workflows in Code: Durable execution primitives and the support triage demo
AWS Lambda Durable Functions documentation

Run npx durable-viz against your handler and share the diagram. I'd love to see what your workflows look like!

Multi-Agent Systems on AWS Lambda with Durable Functions

Gunnar Grosch — Wed, 25 Mar 2026 13:27:42 +0000

In my previous post on multi-agent systems, I built a purchasing coordinator where a coordinator agent routes requests to specialist agents based on RISEN prompt contracts. RISEN structures system prompts into five components: Role, Instructions, Steps, Expectation, and Narrowing. In a multi-agent system, the Steps section encodes the routing logic and the Narrowing section prevents agents from doing each other's work. A laptop triggers Price Research and Delivery. A used car triggers all five specialists. The routing logic lives in the prompts, not in code. It works, but it runs in a single process. No fault isolation, no independent scaling, no durability. If the process crashes halfway through specialist consultations, you start over.

The durable functions post solved the durability problem for a support ticket triage workflow: checkpoint each step, suspend for human review, resume where you left off. But that was a single-agent workflow.

This post combines the two. The same purchasing coordinator, deployed to AWS Lambda, with each specialist as its own Lambda function. The coordinator is a durable function that checkpoints every specialist call. If it's interrupted after consulting three of five specialists, it resumes from the fourth. When a high-value purchase needs human approval, the function suspends, compute charges stop, and it picks up exactly where it left off when the approver responds.

The two SDKs have distinct roles. The Strands Agents SDK handles the AI reasoning: the planning agent decides which specialists to call, and the synthesis agent produces the recommendation. The durable execution SDK handles the infrastructure: checkpointing, parallel dispatch, suspension, and replay. The coordinator uses both. The specialists only use Strands.

The complete source code is on GitHub: github.com/gunnargrosch/durable-multi-agent-purchasing.

What Changes from the In-Process Demo

The multi-agent post used tool() callbacks for specialist dispatch: each specialist was defined as a Strands tool, and the coordinator agent called them as functions within the same process. That's the simplest possible architecture, and it's fine for development. Here's what changes when you deploy:

	In-Process (previous post)	Lambda + Durable (this post)
Specialist invocation	`tool()` callback, in-process	`context.invoke()`, separate Lambda function
Execution model	Sequential (one specialist at a time)	Parallel via `context.parallel()`
Fault tolerance	None. Process crash = restart	Checkpointed. Resume from last completed step
Scaling	Single process	Each specialist scales independently
Human-in-the-loop	Not supported	`waitForCallback()` with zero-cost suspension
IAM isolation	Shared process permissions	Per-specialist least-privilege policies
Routing visibility	Real-time hook as each tool is called	Checkpointed plan step with routing summary
Infrastructure	`npm start`	SAM template, 6 Lambda functions

The RISEN prompts carry over with only minor adjustments. The coordinator's prompt splits into two phases (plan and synthesis) instead of a single invocation, because the durable function needs to checkpoint the plan before dispatching specialists. The specialist prompts are unchanged.

How It Works

If you haven't read the durable functions post, here's the key mental model: durable functions use checkpoint and replay. Your handler re-executes from the top on every resume, but completed steps return their cached results instantly without re-executing. New work picks up from where it left off. The SDK manages this transparently. You write sequential code and the infrastructure handles the rest.

[CoordinatorFunction] — Lambda Durable Function (Sonnet, 1536MB)
  ├→ context.step('plan')            → Planning agent selects specialists
  ├→ context.parallel('specialists') → Runs selected specialists concurrently:
  │     ├─ context.invoke(PriceResearchFunction)  (Haiku)   ← always
  │     ├─ context.invoke(FinancingFunction)       (Haiku)   ← if value > $5K
  │     ├─ context.invoke(DeliveryFunction)        (Haiku)   ← if physical product
  │     ├─ context.invoke(RiskAssessmentFunction)  (Sonnet)  ← if value > $10K / used
  │     └─ context.invoke(ContractReviewFunction)  (Haiku)   ← if subscription/lease
  ├→ context.step('synthesize')      → Synthesis agent combines findings
  └→ context.waitForCallback()       → Human approval (when requireApproval=true)

Three things to notice:

context.invoke() is a new primitive not covered in the durable functions post. It's the SDK's built-in method for calling other Lambda functions. It checkpoints the result automatically and suspends the coordinator while waiting, so you don't pay for compute during specialist execution. Despite the SDK's API reference describing it as invoking "another durable function," context.invoke() works with any Lambda function. The specialists here are standard functions without DurableConfig.
context.step() wraps the planning and synthesis phases with retry strategies, just like the Bedrock calls in the support triage demo. Each step checkpoints its result. On replay, it returns the cached result without re-executing.
context.parallel() wraps the specialist invocations so they run concurrently, each independently checkpointed. If specialist 3 of 5 fails, the other four results are preserved.

The SAM Template

Here are the key parts of the coordinator's definition in the SAM template. The template defines 6 functions total: the coordinator plus 5 specialists that follow the same pattern.

CoordinatorFunction:
  Type: AWS::Serverless::Function
  Properties:
    Handler: coordinator.handler
    MemorySize: 1536
    Timeout: 300
    Environment:
      Variables:
        COORDINATOR_MODEL_ID: !Sub global.${CoordinatorModelId}
        PRICE_RESEARCH_FUNCTION: !Ref PriceResearchFunction
        # ... remaining specialist function references
    Policies:
      - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicDurableExecutionRolePolicy
      - Statement:
          - Effect: Allow
            Action:
              - bedrock:InvokeModel
              - bedrock:InvokeModelWithResponseStream
            Resource: # Bedrock model + inference profile ARNs
          - Effect: Allow
            Action: lambda:InvokeFunction
            Resource:
              - !GetAtt PriceResearchFunction.Arn
              - !GetAtt FinancingFunction.Arn
              - !GetAtt DeliveryFunction.Arn
              - !GetAtt RiskAssessmentFunction.Arn
              - !GetAtt ContractReviewFunction.Arn
    DurableConfig:
      ExecutionTimeout: 86400
      RetentionPeriodInDays: 7
    AutoPublishAlias: live

A few things to note:

No API Gateway, no function URLs, no public endpoints. The multi-agent post previewed two deployment options: Lambda with HTTP endpoints, or AgentCore containers. This implementation goes a simpler route. context.invoke() calls specialists directly via the Lambda API. The coordinator's IAM policy grants lambda:InvokeFunction on each specialist ARN. Specialists are unreachable from outside the coordinator's execution role.
Shared handler, different prompts. All five specialists use the same specialist.ts handler. The PROMPT_NAME environment variable selects which RISEN prompt to load. This keeps the template repetitive but predictable: each specialist block differs only in its name, PROMPT_NAME, and model ID.
Per-specialist model selection. Risk Assessment gets AdvancedSpecialistModelId (Sonnet) for stronger reasoning. The other four get SpecialistModelId (Haiku). Same pattern as the in-process demo, now enforced at the infrastructure level.
DurableConfig with 24-hour execution timeout. The used car scenario with human approval can sit overnight. Each individual invocation is bounded by Timeout: 300 (the coordinator's per-replay limit). ExecutionTimeout: 86400 is the outer wall-clock limit across all replays and suspensions.
InvokeModelWithResponseStream is included because the Strands SDK's BedrockModel may use streaming internally for token generation. Without it, the coordinator would get AccessDeniedException on agent invocations.
ESM build. The coordinator uses ESM (Format: esm) with esbuild. The full template includes a Banner that injects a createRequire shim because some dependencies expect CommonJS require. This is a known pattern for ESM Lambda functions with mixed dependencies. See the repo's template.yaml for the complete Metadata block.

The Coordinator Handler

The coordinator is the only durable function. Here's the handler skeleton showing the four durable phases. The full source includes types, the specialist registry, retry strategies, and routing summary logic.

export const handler = withDurableExecution(async (
  event: CoordinatorEvent,
  context: DurableContext
): Promise<Record<string, unknown>> => {

  // Phase 1: Plan — agent decides which specialists to consult
  const plan = await context.step<AnalysisPlan>('plan', async () => {
    let capturedPlan: AnalysisPlan | null = null
    const planTool = tool({
      name: 'create_analysis_plan',
      inputSchema: z.object({
        specialists: z.array(z.object({
          name: z.enum(['price-research', 'financing', 'delivery',
                        'risk-assessment', 'contract-review']),
          prompt: z.string(),
        })),
      }),
      callback: async (input) => { capturedPlan = input; return 'Plan created.' },
    })
    const agent = new Agent({ model, systemPrompt: planPrompt, tools: [planTool], printer: false })
    await agent.invoke(event.request)
    if (!capturedPlan) throw new Error('Planning agent did not call create_analysis_plan')
    return capturedPlan
  }, { retryStrategy: bedrockRetry })

  // Phase 2: Consult specialists in parallel via context.invoke()
  const results = await context.parallel<{ name: string; response: string }>('specialists',
    plan.specialists.map((spec) => ({
      name: spec.name,
      func: async (ctx) => {
        try {
          const specialist = SPECIALISTS[spec.name]
          if (!specialist) {
            throw new Error(`Unknown specialist: ${spec.name}`)
          }
          const result = await ctx.invoke<{ prompt: string }, { response: string }>(
            spec.name, specialist.functionName, { prompt: spec.prompt }
          )
          return { name: spec.name, response: result.response }
        } catch (err) {
          const display = SPECIALISTS[spec.name]?.display ?? spec.name
          return { name: spec.name, response: `[${display} unavailable: ${err instanceof Error ? err.message : 'unknown error'}]` }
        }
      },
    }))
  )

  // Phase 3: Synthesize specialist findings into a recommendation
  const response = await context.step('synthesize', async () => {
    // Build findings from checkpointed parallel results, invoke synthesis agent
    // (see full source for details)
  }, { retryStrategy: bedrockRetry })

  // Phase 4: Human approval (optional)
  if (event.requireApproval) {
    const approval = await context.waitForCallback<ApprovalPayload>(
      'approval',
      async (callbackId) => { context.logger.info('approval_callback_created', { callbackId }) },
      { timeout: { hours: 24 }, serdes: defaultSerdes }
    )
    if (!approval.approved) return { status: 'rejected', recommendation: response }
  }

  return { status: event.requireApproval ? 'approved' : 'completed', recommendation: response }
})

Let's walk through what's happening in each phase.

Phase 1: Plan

The planning phase is the biggest change from the in-process demo. In the previous post, the coordinator was a single agent that both decided which specialists to call and synthesized their findings. Here, planning and synthesis are separate agents wrapped in separate context.step() calls.

Why split them? Checkpointing. In the in-process demo, if the coordinator crashes after calling three specialists, you lose the routing decision and all three results. With durable functions, the plan is checkpointed as a single unit. If the function replays after the plan step, it returns the cached plan instantly without calling Bedrock again.

The planning agent uses tool() with a Zod schema to produce structured output. The create_analysis_plan tool captures the plan into a closure variable, and the step returns it as its checkpointed result. If the agent doesn't call the tool, the step throws an error. The retry strategy will attempt it three times, but this is a non-transient failure: if the model didn't call the tool on the first attempt, retries won't help. After retries are exhausted, the execution fails.

Phase 2: Parallel specialists

This is where context.invoke() replaces tool() callbacks. Each specialist invocation is a branch inside context.parallel():

const result = await ctx.invoke<{ prompt: string }, { response: string }>(
  spec.name,             // step name for checkpoint history
  specialist.functionName, // Lambda function name from environment
  { prompt: spec.prompt }  // payload
)

context.invoke() calls the specialist Lambda function directly, checkpoints the result, and suspends the coordinator while waiting. You don't pay for coordinator compute while specialists are executing. On replay, completed invocations return their cached results without re-invoking the specialist.

Each branch has a try/catch for graceful degradation. If the Delivery specialist times out, the coordinator still gets results from Price Research, Financing, Risk Assessment, and Contract Review. The synthesis agent notes the gap and advises the buyer to investigate delivery independently. This is a meaningful improvement over the in-process demo, where a failed specialist tool call could derail the entire coordinator.

Phase 3: Synthesize

The synthesis agent receives all specialist findings and produces a structured recommendation. Like the plan step, the entire synthesis is one checkpointed unit. The synthesis prompt's Narrowing section prevents it from overriding specialist findings or filling in gaps from failed specialists.

Phase 4: Human approval

When requireApproval is true (the used car scenario sets this), the function suspends at waitForCallback. Compute charges stop. The approver reviews the recommendation and sends a callback via the Lambda API or the demo's interactive prompt. The function resumes and returns the final status.

Note the serdes: defaultSerdes option on the callback. As covered in the durable functions post's gotchas, waitForCallback defaults to passthrough serialization (not JSON.parse). Without defaultSerdes, approval.approved would be undefined at runtime even though TypeScript thinks it's a boolean.

The Specialist Handler

All five specialists share one handler. The PROMPT_NAME environment variable selects the behavior:

const promptName = process.env.PROMPT_NAME!
const systemPrompt = loadPrompt(promptName)
const model = createModel(SPECIALIST_MODEL)

export const handler = async (
  event: SpecialistEvent,
  context: Context
): Promise<{ response: string }> => {
  const logger = makeLogger({ handler: promptName, requestId: context.awsRequestId })
  const tools = loadSpecialistTools(promptName, logger)
  const agent = new Agent({ model, systemPrompt, tools, printer: false })
  const result = await agent.invoke(event.prompt)
  return { response: result.toString() }
}

Specialists are standard Lambda functions, not durable. They don't need checkpointing because each one completes in a single invocation (a Bedrock call and response processing). The coordinator's context.invoke() handles the durability: if a specialist invocation times out, the coordinator can retry from the checkpoint without re-running specialists that already succeeded.

loadSpecialistTools returns specialist-specific tools (see src/lib/specialist-tools.ts). Most specialists are pure reasoning (no tools). The Price Research specialist has a save_price_snapshot tool that logs structured price data. In production, that tool could write to DynamoDB or call a pricing API. The coordinator never sees these tools. They're scoped to each specialist's domain.

The Prompt Split

The in-process demo had one coordinator prompt with routing in the Steps section. The durable version splits this into two prompts:

coordinator-plan handles routing. Here's the Steps and Expectation sections:

# Steps
1. Read the purchase request and identify what is being purchased, its likely category
   (vehicle, electronics, real estate, software, etc.), the approximate value range,
   and any special circumstances mentioned or implied (used/secondhand, financing needed,
   physical delivery, contract or subscription, high value).
2. Select specialists using these routing rules:
   - Always include price-research to compare options and assess market value.
   - Include financing if the estimated value exceeds $5,000, or if financing or a loan
     is mentioned or implied.
   - Include delivery if the item is a tangible physical product that must be physically
     received — electronics, appliances, vehicles, furniture, machinery. Vehicles always
     need delivery planning (transport, pickup, or test drive logistics). Do not include
     for purely digital purchases (software, SaaS subscriptions, downloadable content).
   - Include contract-review if the purchase involves a subscription, lease, warranty
     agreement, service contract, purchase agreement, or any multi-year financial
     commitment. Vehicle and real estate purchases always involve contracts.
   - Include risk-assessment if the estimated value exceeds $10,000, the item is used or
     secondhand, or the category carries known risk (vehicles, real estate, machinery).
     Do not include for new electronics, appliances, or standard retail under $10,000.
3. For each selected specialist, write a focused prompt describing what to analyze about
   this specific purchase. Include relevant details from the request (item, price,
   condition, location, urgency). The specialist's own system prompt defines its role —
   do not repeat the role description in your prompt.
4. Call create_analysis_plan exactly once with the selected specialists and their prompts.

# Expectation
A single call to create_analysis_plan containing:
- An array of specialists, each with a name (from the allowed set) and a prompt string.
- Only specialists whose routing criteria are met.
- Prompts that are specific to this purchase, not generic templates.

These are the same routing rules from the original coordinator prompt in the multi-agent post. The difference: instead of calling specialist tools directly (Steps 2-6 in the original said "invoke the research_prices tool," "invoke the evaluate_financing tool"), the plan agent calls create_analysis_plan once with all selected specialists. The actual dispatch happens via context.invoke() in Phase 2.

coordinator-synthesis handles the final recommendation. It receives specialist findings and produces the buyer-facing output. Its Narrowing prevents it from contradicting specialists or filling in missing analysis.

This split means the coordinator makes two agent invocations (plan + synthesize) instead of one. Each agent invocation may involve multiple Bedrock round-trips internally as the Strands SDK handles reasoning. The trade-off is worth it: the plan is checkpointed before any specialist is called, and the synthesis is checkpointed after all specialists complete. On replay, both return cached results instantly.

Testing with the Local Runner

The durable functions post showed LocalDurableTestRunner for the support triage workflow. The multi-agent demo adds a new pattern: registerFunction for mocking context.invoke() targets.

// Register mock handlers for each specialist Lambda function
runner = new LocalDurableTestRunner({ handlerFunction: handler });
runner
  .registerFunction("PriceResearchFunction", specialistHandler)
  .registerFunction("FinancingFunction", specialistHandler)
  .registerFunction("DeliveryFunction", specialistHandler)
  .registerFunction("RiskAssessmentFunction", specialistHandler)
  .registerFunction("ContractReviewFunction", specialistHandler);

// Run the full workflow and verify the result
const result = runner.run({ payload: laptopPayload });
const output = await result;
expect(output.getStatus()).toBe("SUCCEEDED");
expect(output.getResult().routing.called).toContain("Price Research");

registerFunction maps function names to local handlers. When the coordinator calls context.invoke("PriceResearchFunction", payload), the test runner routes it to the registered mock instead of calling Lambda. This lets you test the full checkpoint/replay lifecycle without deploying or calling Bedrock. The full test suite also tests callback suspension and resumption using runner.getOperation() and sendCallbackSuccess(), the same pattern from the durable functions post.

The test suite covers seven scenarios: standard flow, all-5-specialists flow, approval, rejection, specialist failure with graceful degradation, callback failure, and planning agent failure.

Try the Demo

The repo includes an interactive demo with three purchase scenarios:

Scenario	Value	Specialists	Approval
Laptop	$1,500	Price Research + Delivery	No
Used car	$18,000	All 5 specialists	Yes (`waitForCallback`)
SaaS subscription	$200/mo	Price Research + Contract Review	Yes (`waitForCallback`)

You'll need:

Node.js 24+ and npm
For cloud mode: AWS SAM CLI 1.153.1+ and Bedrock access to Claude Sonnet 4.6 and Claude Haiku 4.5

Local mode (no AWS credentials needed)

git clone https://github.com/gunnargrosch/durable-multi-agent-purchasing.git
cd durable-multi-agent-purchasing
npm install
npm run demo:local -- --ticket=used-car

Local mode uses mocked Bedrock responses. The used car scenario exercises all four durable primitives: step (plan and synthesis), invoke (specialist calls), parallel (concurrent dispatch), and waitForCallback (human approval where you play the purchase approver).

Cloud mode (real Bedrock responses)

sam build
sam deploy --guided
npm run demo:cloud -- --ticket=used-car --region=us-east-1

Cloud mode invokes the deployed coordinator with real Bedrock calls. You'll see actual AI-generated specialist analyses and a synthesized recommendation. The demo polls execution history and prompts you when the approval callback is created.

The demo uses direct aws lambda invoke with --invocation-type Event for simplicity. In production, the coordinator would typically sit behind an upstream service: an API Gateway endpoint receiving purchase requests, an EventBridge rule triggered by order events, or an SQS queue processing a backlog. The coordinator itself doesn't care how it's invoked. It receives the event payload and the durable SDK handles the rest.

Inspecting execution history

After a cloud run, you can inspect the execution in the Lambda console under the Durable executions tab, or via the CLI:

aws lambda list-durable-executions-by-function \
  --function-name durable-multi-agent-purchasing-CoordinatorFunction

aws lambda get-durable-execution \
  --durable-execution-arn "<arn-from-list>"

The execution history shows each step's status and timing: when the plan completed, how long each specialist took, and whether the callback is pending or resolved.

Design Decisions

context.invoke() over HTTP

The multi-agent post previewed two deployment approaches: Lambda with API Gateway/Function URLs (HTTP), or AgentCore containers. This demo takes a third path: context.invoke() for direct Lambda-to-Lambda invocation.

The result is simpler than either preview option. No API Gateway resources, no function URLs, no SigV4 signing, no HTTP client configuration. The coordinator calls specialists via the Lambda API, and the durable SDK handles checkpointing and retry. Specialists are unreachable from outside the coordinator's execution role, which is better isolation than an HTTP endpoint with IAM auth.

The trade-off: specialists are only callable from within a durable function. If you later need specialists accessible from other services (a REST API, a Step Functions state machine, another team's coordinator), you'd need to add API Gateway or function URLs at that point. For this use case, where one coordinator owns all specialist dispatch, direct invocation is the right call.

Splitting plan from synthesis

The in-process coordinator was a single agent invocation: read the request, call specialist tools, synthesize findings. With durable functions, that becomes two separate agents wrapped in separate context.step() calls.

This introduces an extra Bedrock call, but the checkpointing benefits are significant. The plan is preserved before any specialist runs. If the function replays after three of five specialists complete, the plan doesn't need to be regenerated. The synthesis is preserved after all specialists complete. If the function replays during the approval callback, the recommendation doesn't need to be regenerated.

The alternative would be wrapping the entire coordinator in a single step. That would mean one Bedrock conversation (cheaper) but no intermediate checkpoints. A failure during synthesis would replay from the beginning, including all specialist invocations. With the split, a synthesis failure only retries the synthesis.

Planning agent with tool capture

The planning agent uses tool() with a Zod schema to produce structured output. This is the same pattern from the in-process demo, but used differently. In the previous post, tools were the dispatch mechanism (calling tools = calling specialists). Here, the tool is purely for structured output capture. The plan step returns the captured plan as its checkpointed result, and context.invoke() handles the actual specialist dispatch.

Why not just have the planning agent return JSON directly? Tool calling with a schema gives you validation at the SDK level. If the agent returns a plan with an invalid specialist name, Zod catches it before the plan is checkpointed. Without the tool, you'd parse and validate the JSON yourself, and an invalid plan could be checkpointed and break on every subsequent replay.

Graceful degradation in parallel

Each specialist branch in context.parallel() has a try/catch that returns an error message instead of throwing:

catch (err) {
  return { name: spec.name, response: `[unavailable: ${err instanceof Error ? err.message : 'unknown error'}]` }
}

This means a failed specialist doesn't fail the entire parallel block. The synthesis agent receives partial results and notes the gap. Without the catch, a failed specialist would fail its branch. Whether that fails the entire parallel block depends on the completion config, but either way, synthesis would never run with partial results. With the catch, every branch succeeds (some with error messages), the parallel block always completes, and the synthesis agent can work with whatever it has.

Cost

The main cost is Bedrock token usage, not Lambda compute.

Scenario	Specialists	Agent invocations	Estimated cost
Laptop (2 specialists)	2	~4 (plan + 2 specialists + synthesize)	~$0.02-0.05
Used car (5 specialists)	5	~7 (plan + 5 specialists + synthesize)	~$0.05-0.15

The coordinator uses Sonnet (~$3/$15 per million input/output tokens). Most specialists use Haiku (~$1/$5 per million input/output tokens). Risk Assessment uses Sonnet. Lambda compute for the active execution periods (plan, specialist dispatch, synthesis, replay) totals ~$0.0001. During the waitForCallback suspension, compute charges are zero.

Things to Watch For

Checkpoint size. Each step result is serialized and stored as a checkpoint. The durable functions post covered the 256KB limit per checkpoint. With 5 specialists returning Bedrock responses, the parallel result could get large if the model is verbose. Monitor response sizes. If you hit the limit, truncate or summarize specialist responses before returning them from the branch, or store full responses in S3 and return a reference.

Debugging failures. If the plan step fails after exhausting retries, or a specialist consistently times out, the execution moves to FAILED status. Use get-durable-execution to see which step failed and the error message. The coordinator uses context.logger (replay-aware), so CloudWatch Logs show each phase's progress without duplicate lines from replays. Specialist failures are easier to debug since each specialist has its own log group (sam logs --name PriceResearchFunction --tail).

Replay safety. Durable functions re-execute your handler from the top on every resume. Completed context.step() and context.invoke() calls return cached results, but any code outside those primitives runs again on every replay. If you add a side effect (writing to DynamoDB, sending a notification, calling an external API), wrap it in a context.step() so it executes exactly once. The coordinator's comment on the save-recommendation step shows this pattern. Without the step wrapper, you'd send duplicate notifications every time the function replays.

Cold starts. The used car scenario invokes 5 specialist Lambda functions in parallel. If all 5 are cold, that's 5 concurrent cold starts: arm64 Node.js 24, the Strands SDK, and the Bedrock client. This can add several seconds to the first specialist round. The in-process demo had no cold start penalty for specialists since everything ran in one process. In practice, the cold start overhead is small relative to the Bedrock inference time that follows. For workflows that already include multi-second model calls and human approval, a few extra seconds on the first invocation is rarely the bottleneck.

Wrapping Up

This post showed how to take a multi-agent system from a single-process demo to a deployed, fault-tolerant system on Lambda with durable functions. The RISEN prompts carry over with minimal changes. The architectural shift is from in-process tool calls to checkpointed Lambda-to-Lambda invocations with independent scaling, failure isolation, and human-in-the-loop approval.

Additional Resources

Demo repository for this post
Building Multi-Agent Systems with RISEN Prompts and Strands Agents: The in-process multi-agent demo this builds on
AWS Lambda Durable Functions: Building Long-Running Workflows in Code: Durable execution primitives and the support triage demo
AWS Lambda Durable Functions documentation
Durable Execution SDK for JavaScript (GitHub)
Strands Agents SDK (TypeScript)

What multi-agent workflow would you deploy with durable functions? Let me know in the comments!

AWS Lambda Durable Functions: Building Long-Running Workflows in Code

Gunnar Grosch — Tue, 17 Mar 2026 22:06:16 +0000

If you've built anything non-trivial on AWS Lambda, you've hit the wall. The function runs for 15 minutes and it's stateless. Any multi-step workflow requires stitching together Step Functions, SQS queues, DynamoDB tables for state, and a whole lot of glue. It works, but it's a lot of infrastructure for what should be straightforward sequential logic.

AWS Lambda Durable Functions, launched at re:Invent 2025, change that. You write sequential code in a single Lambda function. The SDK handles checkpointing, failure recovery, and suspension. Your function can run for up to a year, and you only pay for active compute time. During waits (human approvals, timers, external callbacks), the function suspends and compute charges stop.

In this post, I'll walk through what problem durable functions solve, how the checkpoint/replay model works, and then dig into a complete AI-powered support ticket workflow in TypeScript that demonstrates every primitive in action.

What Problem This Solves

Here's a scenario most teams deal with: a support ticket arrives, someone needs to triage it, figure out who should handle it, wait for them to respond, and then close the loop with the customer. Before durable functions, you had a few options:

Step Functions: Define an ASL state machine with states for each step, configure IAM for each integration, manage the state machine as a separate resource. Great for cross-service orchestration, but heavyweight for application logic that naturally reads as sequential code.

SQS + multiple Lambda functions: Break the workflow into separate functions connected by queues. Now you're managing message formats, dead-letter queues, idempotency, and correlating state across function boundaries.

Polling loop with DynamoDB: One function writes state to DynamoDB, another polls for changes. Works, but you're paying for polling compute and managing your own state machine.

All three approaches take what should be straightforward sequential logic and spread it across multiple services, IAM policies, and configuration files.

With durable functions, that same workflow looks like this:

const handler = async (event: TicketEvent, context: DurableContext) => {
  const analysis = await context.step("analyze", async () => analyzeTicket(event));
  const response = await context.waitForCallback("agent-review",
    async (callbackId) => notifyAgent(callbackId, analysis)
  );
  if (analysis.needsEscalation) {
    await context.waitForCallback("specialist-review",
      async (callbackId) => notifySpecialist(callbackId, analysis)
    );
  }
  await context.parallel("close-ticket", [
    { name: "reply", func: async (ctx) => ctx.step("send-reply", async () => sendReply(response)) },
    { name: "survey", func: async (ctx) => ctx.step("send-survey", async () => sendSurvey(event)) },
  ]);
  return { status: "resolved", ticketId: event.ticketId };
};

One function. Sequential code. The SDK handles checkpointing each step, suspending during the human review waits, and resuming when the callbacks arrive.

How Checkpoint/Replay Works

This is the part that makes everything else make sense. Durable functions use a checkpoint and replay model. Here's how it works:

First invocation: Your handler runs from the beginning. Each context.step() executes your code and checkpoints the result.
Suspension: When context.wait() (fixed-duration pause) or context.waitForCallback() (external signal) is called, the function terminates. Compute charges stop.
Resumption: When the wait completes or a callback arrives, Lambda invokes your handler again from the beginning. But this time, completed steps return their cached results instantly without re-executing. Execution picks up from the first non-checkpointed operation.

First invocation:
  analyze     ->  [executes Bedrock call, checkpoints result]
  agent-review ->  [creates callback, function suspends]

Second invocation (agent responds):
  analyze     ->  [returns cached result, skips Bedrock call]
  agent-review ->  [returns callback result]
  close-ticket ->  [sends reply + survey in parallel]

There's one critical rule that falls out of this: code outside steps re-executes on every replay and must be deterministic. If you use Date.now(), Math.random(), or crypto.randomUUID() outside a step, you'll get different values on each replay. Wrap non-deterministic operations in steps.

// Wrong: different value on each replay
const id = crypto.randomUUID();

// Right: checkpointed, same value on every replay
const id = await context.step("gen-id", async () => crypto.randomUUID());

What You'll Build

A support ticket triage workflow where AI handles the first pass and humans make the final call. This is the pattern that makes durable functions click: the AI analysis takes seconds, but the human reviews take hours or days. Without durable functions, you'd need to persist state somewhere and wire up resumption logic. With them, you just write await context.waitForCallback() and the function suspends until the human responds.

Primitive	What It Does	Where You'll See It
`step()`	Execute and checkpoint an atomic operation	AI ticket analysis with Bedrock
`waitForCallback()`	Suspend until an external system responds	Agent review, specialist escalation
`parallel()`	Run multiple branches concurrently	Customer reply + satisfaction survey
Retry strategies	Automatic retry with exponential backoff	Bedrock API calls
`context.logger`	Replay-aware structured logging (suppresses duplicate output during replay)	Throughout

The complete source code is on GitHub: github.com/gunnargrosch/durable-support-triage. Clone the repo and run npm run demo to try the full workflow locally with mocked Bedrock responses, or deploy to AWS and run it with real Bedrock.

Getting Started

You'll need:

An AWS account with credentials configured
AWS SAM CLI 1.153.1 or later (minimum version with DurableConfig support)
Node.js 24 or later
Access to Amazon Bedrock with Claude Haiku 4.5 enabled in your region

Clone and install

git clone https://github.com/gunnargrosch/durable-support-triage.git
cd durable-support-triage
npm install

The SAM Template

Here's the template.yaml:

AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: AI-powered support ticket triage with durable functions

Parameters:
  BedrockModelId:
    Type: String
    Default: anthropic.claude-haiku-4-5-20251001-v1:0
    Description: Bedrock foundation model ID (uses global inference profile prefix automatically)

Globals:
  Function:
    Timeout: 120
    MemorySize: 256
    Runtime: nodejs24.x

Resources:
  SupportTriageFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: durable-support-triage
      Handler: index.handler
      CodeUri: src/
      DurableConfig:
        ExecutionTimeout: 604800
        RetentionPeriodInDays: 14
      Policies:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicDurableExecutionRolePolicy
        - Version: "2012-10-17"
          Statement:
            - Effect: Allow
              Action:
                - bedrock:InvokeModel
              Resource:
                - !Sub "arn:aws:bedrock:*::foundation-model/${BedrockModelId}"
                - !Sub "arn:aws:bedrock:${AWS::Region}:${AWS::AccountId}:inference-profile/global.${BedrockModelId}"
      AutoPublishAlias: live
      Environment:
        Variables:
          BEDROCK_MODEL_ID: !Sub "global.${BedrockModelId}"
    Metadata:
      BuildMethod: esbuild
      BuildProperties:
        Minify: false
        Target: es2022
        EntryPoints:
          - index.ts

Outputs:
  FunctionArn:
    Value: !GetAtt SupportTriageFunction.Arn
  AliasArn:
    Value: !Ref SupportTriageFunctionAliaslive

A few things to note about this template:

Globals.Timeout: 120 is the standard Lambda invocation timeout. It applies to each individual invocation (each replay round), not the overall workflow. Two minutes is plenty for each replay round. ExecutionTimeout in DurableConfig is the total wall-clock time for the entire durable execution.
DurableConfig is the only new property compared to a standard Lambda function. ExecutionTimeout is in seconds (604,800 = 7 days). The individual callback timeouts handle the per-step boundaries, but the execution timeout is your outer safety net. A ticket that needs specialist review might sit over a weekend, so 7 days gives headroom. RetentionPeriodInDays controls how long execution history is kept (1 to 90 days).
AutoPublishAlias: live automatically creates a Lambda version and alias on each deploy. This is important for two reasons: durable functions require a qualified ARN (with version or alias) for invocation, and Lambda pins each execution to the version that started it. If you deploy new code while an execution is suspended, replay still uses the original version. This prevents inconsistencies from code changes mid-workflow.
AWSLambdaBasicDurableExecutionRolePolicy is an AWS managed policy that grants the checkpoint and state permissions your function needs (lambda:CheckpointDurableExecutions, lambda:GetDurableExecutionState) plus the standard CloudWatch Logs permissions.
Bedrock IAM uses a cross-region inference profile (global. prefix on the model ID) so that Bedrock routes requests to whichever region has capacity. The policy needs two resource ARNs: the foundation model (wildcard region, no account ID) and the inference profile (your region and account). The BedrockModelId parameter defaults to Claude Haiku 4.5 but you can override it at deploy time with --parameter-overrides BedrockModelId=<model-id>. Check Bedrock model availability for what's enabled in your region.

The RISEN Prompt

The AI triage uses Amazon Bedrock with Claude Haiku 4.5 to analyze incoming tickets. I'm using the RISEN framework for the system prompt. RISEN structures prompts into five components: Role, Instructions, Steps, Expectation, and Narrowing. Each component serves a specific purpose, and together they produce consistent, structured output that your code can reliably parse.

Here's the system prompt for the triage agent:

const TRIAGE_SYSTEM_PROMPT = `
# Role
You are a senior technical support analyst with 10 years of experience
triaging customer support tickets for a SaaS platform. You specialize in
categorizing issues by severity, identifying root causes, and drafting
professional responses.

# Instructions
Analyze the incoming support ticket and produce a structured triage
assessment with category, priority, sentiment, a suggested response,
and an escalation recommendation.

# Steps
1. Read the ticket subject and body to identify the core issue.
2. Categorize the issue (billing, technical, account, feature-request, other).
3. Assess priority based on business impact and urgency (critical, high, medium, low).
4. Evaluate customer sentiment (frustrated, neutral, positive).
5. Draft a suggested response that acknowledges the issue and outlines next steps.
6. Determine whether the ticket needs specialist escalation.

# Expectation
Return a JSON object with this exact structure:
{
  "category": "billing" | "technical" | "account" | "feature-request" | "other",
  "priority": "critical" | "high" | "medium" | "low",
  "sentiment": "frustrated" | "neutral" | "positive",
  "suggestedResponse": "string",
  "needsEscalation": boolean,
  "escalationReason": "string or null",
  "summary": "One-sentence summary of the issue"
}

# Narrowing
- Return only raw JSON. Do not wrap it in markdown code fences, backticks,
  or any other formatting. No explanation, no preamble, no commentary.
- Do not fabricate account details or order numbers not present in the ticket.
- Do not promise refunds, credits, or policy exceptions in the suggested response.
- needsEscalation MUST be false unless one of these exact conditions is met:
  1. The ticket describes confirmed or suspected data loss.
  2. The ticket describes a security breach, unauthorized access, or credential compromise.
  3. The ticket involves a legal or compliance issue.
  4. The customer tier is "enterprise".
  For all other tickets (billing issues, bugs, feature requests, general questions),
  needsEscalation MUST be false regardless of priority or sentiment.
- Keep the suggested response under 200 words.
`;

The Narrowing section does the heavy lifting for reliability. The explicit numbered escalation conditions prevent the model from over-escalating standard tickets (without these, Haiku flagged a routine CSV bug for specialist review). The constraint against promising refunds keeps the AI from making commitments that only a human should make. The pipe syntax in the Expectation section ("billing" | "technical" | ...) is instructional for the model, not literal JSON. It tells the model which values are valid without requiring a separate schema document. Note that "return only raw JSON" doesn't guarantee it: some models still wrap output in markdown code fences despite the instruction. The handler strips them defensively before parsing.

The Handler

Here's the handler from src/index.ts, trimmed to show the durable execution primitives. The full source (input validation, response parsing, integration stubs) is in the repo. Types are defined in src/types.ts. The TRIAGE_SYSTEM_PROMPT shown in the RISEN section above is defined at module scope.

import {
  withDurableExecution, DurableContext,
  createRetryStrategy, JitterStrategy, defaultSerdes,
} from "@aws/durable-execution-sdk-js";
import { BedrockRuntimeClient, InvokeModelCommand } from "@aws-sdk/client-bedrock-runtime";
import type { TicketEvent, TriageResult, AgentReview, SpecialistReview, TicketResolution } from "./types";

const bedrock = new BedrockRuntimeClient();

async function closeTicket(
  context: DurableContext,
  name: string,
  email: string,
  ticketId: string,
  response: string
): Promise<void> {
  await context.parallel(name, [
    {
      name: "send-reply",
      func: async (ctx) =>
        ctx.step("reply", async () => {
          await sendCustomerReply(email, ticketId, response);
        }),
    },
    {
      name: "send-survey",
      func: async (ctx) =>
        ctx.step("survey", async () => {
          await sendSatisfactionSurvey(email, ticketId);
        }),
    },
  ]);
}

export const handler = withDurableExecution(
  async (event: TicketEvent, context: DurableContext): Promise<TicketResolution> => {
    validateEvent(event);

    context.logger.info("Ticket received", {
      ticketId: event.ticketId,
      customerTier: event.customerTier,
    });

    // Step 1: AI analyzes the ticket using Bedrock
    const analysis = await context.step(
      "analyze-ticket",
      async () => {
        const response = await bedrock.send(new InvokeModelCommand({
          modelId: process.env.BEDROCK_MODEL_ID,
          contentType: "application/json",
          accept: "application/json",
          body: JSON.stringify({
            anthropic_version: "bedrock-2023-05-31",
            max_tokens: 1024,
            system: TRIAGE_SYSTEM_PROMPT,
            messages: [
              {
                role: "user",
                content: `Ticket ID: ${event.ticketId}\nCustomer Tier: ${event.customerTier}\nSubject: ${event.subject}\n\n${event.body}`,
              },
            ],
          }),
        }));
        return parseBedrockResponse(response.body as Uint8Array);
      },
      {
        retryStrategy: createRetryStrategy({
          maxAttempts: 3,
          initialDelay: { seconds: 2 },
          maxDelay: { seconds: 30 },
          backoffRate: 2.0,
          jitter: JitterStrategy.FULL,
        }),
      }
    );

    // Step 2: Support agent reviews AI suggestion
    const agentReview = await context.waitForCallback<AgentReview>(
      "agent-review",
      async (callbackId) => {
        await notifyAgent({ callbackId, ticketId: event.ticketId, analysis, customerTier: event.customerTier });
      },
      { timeout: { hours: 8 }, serdes: defaultSerdes }
    );

    const finalResponse = agentReview.editedResponse || analysis.suggestedResponse;

    if (!agentReview.approved) {
      return { status: "rejected", ticketId: event.ticketId, category: analysis.category, priority: analysis.priority, finalResponse: "" };
    }

    // Step 3: If escalation needed, wait for specialist
    if (analysis.needsEscalation) {
      const specialistResponse = await context.waitForCallback<SpecialistReview>(
        "specialist-review",
        async (callbackId) => {
          await notifySpecialist({ callbackId, ticketId: event.ticketId, analysis, agentNotes: agentReview.agentNotes });
        },
        { timeout: { days: 3 }, serdes: defaultSerdes }
      );

      const resolvedResponse = specialistResponse.response || finalResponse;
      await closeTicket(context, "close-escalated-ticket", event.contactEmail, event.ticketId, resolvedResponse);
      return { status: "escalated", ticketId: event.ticketId, category: analysis.category, priority: analysis.priority, finalResponse: resolvedResponse };
    }

    // Step 4: Send reply and survey in parallel
    await closeTicket(context, "close-ticket", event.contactEmail, event.ticketId, finalResponse);
    return { status: "resolved", ticketId: event.ticketId, category: analysis.category, priority: analysis.priority, finalResponse };
  }
);

Let's walk through what's happening:

withDurableExecution wraps your async function and returns a standard Lambda handler. The runtime calls it like any other handler; the SDK intercepts the execution to manage checkpoints. The BedrockRuntimeClient is instantiated at module scope, which is standard Lambda practice for connection reuse across warm-start invocations. Each replay is a new Lambda invocation, but it may reuse a warm container just like any regular invocation.

validateEvent runs before the first context.step(). This is intentional: if the payload is malformed, the execution fails immediately instead of after the Bedrock step has already been checkpointed. Durable executions that fail after partial checkpointing are harder to reason about than ones that fail fast. Validation is deterministic and cheap, so re-running it on every replay is harmless.

context.step("analyze-ticket", ...) calls Amazon Bedrock with the RISEN prompt and checkpoints the result. The retry strategy handles transient Bedrock API errors (throttling, temporary unavailability) with exponential backoff. parseBedrockResponse handles the response parsing separately: it strips markdown code fences (some models wrap JSON output despite the prompt instruction), validates the response structure, and gives clear error messages on parse failures. If the function replays later, this step returns the cached analysis without calling Bedrock again. That matters for both cost and consistency: you don't want the AI to produce a different triage on replay.

context.waitForCallback("agent-review", ...) is where the function suspends. The SDK creates a callback ID and passes it to your submitter function (which sends it to Slack, email, or your ticketing UI). The submitter runs exactly once, on the invocation that creates the callback. On replay, the SDK skips the submitter entirely and returns the callback result directly. This is important: even though the submitter isn't wrapped in a context.step(), it won't re-execute on replay. The SDK then terminates the Lambda function. Compute charges stop. The agent might respond in minutes or hours. When they do, an external system calls SendDurableExecutionCallbackSuccess with their review. Lambda resumes the function from where it left off. The serdes: defaultSerdes option is required for typed callbacks. Without it, the SDK uses passthrough serialization (not JSON.parse) and agentReview.approved would be undefined at runtime even though TypeScript thinks it's a boolean. This isn't documented yet: step() defaults to JSON serdes, but waitForCallback defaults to passthrough. The SDK exports defaultSerdes for this purpose. If the callback times out (8 hours for the agent, 3 days for the specialist), the SDK throws a CallbackTimeoutError. In production, wrap the callback in a try/catch to handle the timeout (re-queue the ticket, notify a manager, or auto-escalate).

If the agent rejects the AI suggestion (approved: false), the workflow returns early with a rejected status without sending a customer reply. Your ticketing system handles the next step (re-queue, reassign, or manual response).

The escalation path adds a second waitForCallback. If the AI flagged the ticket for escalation (security concern, data loss, enterprise customer), the function suspends again waiting for a specialist. The specialist sends back a SpecialistReview with a response and notes. This callback has a 3-day timeout because specialist reviews can take time. Without durable functions, you'd need a separate state machine or database to track which tickets are waiting for specialists.

context.logger replaces console.log. During replay, completed steps don't re-execute, but code outside steps does. context.logger suppresses duplicate log output during replay so your CloudWatch Logs stay clean. With console.log, you'd see the same log lines repeated on every replay invocation.

closeTicket extracts the parallel close-out into a helper. Both the escalation and standard paths send a customer reply and satisfaction survey concurrently using context.parallel. Each branch gets its own child context with isolated state tracking. The helper takes a dynamic context name so the escalated and standard close-out steps are distinguishable in the execution history.

Testing Locally

The testing SDK (@aws/durable-execution-sdk-js-testing) lets you run durable functions locally without deploying. Here's the key pattern from src/index.test.ts, showing how to drive a callback-based workflow in a test:

import { LocalDurableTestRunner } from "@aws/durable-execution-sdk-js-testing";

// jest.mock replaces BedrockRuntimeClient so analyze-ticket returns controlled results
// (see full mock setup in the repo)
import { handler } from "./index";

describe("Support Triage", () => {
  let runner: LocalDurableTestRunner;

  beforeAll(async () => {
    await LocalDurableTestRunner.setupTestEnvironment({ skipTime: true });
  });

  afterAll(async () => {
    await LocalDurableTestRunner.teardownTestEnvironment();
  });

  beforeEach(() => {
    runner = new LocalDurableTestRunner({ handlerFunction: handler });
  });

  afterEach(async () => {
    await runner.reset();
  });

  it("should resolve a standard ticket after agent review", async () => {
    const result = runner.run({
      payload: {
        ticketId: "TKT-001",
        customerId: "CUST-123",
        customerTier: "pro",
        subject: "Cannot export CSV reports",
        body: "When I click the export button, nothing happens.",
        contactEmail: "customer@example.com",
      },
    });

    // The handler suspends at waitForCallback("agent-review").
    // getOperation blocks until the callback is created.
    const agentCallback = await runner.getOperation("agent-review");
    const agentDetails = await agentCallback.waitForData();
    await agentDetails.sendCallbackSuccess(JSON.stringify({
      approved: true,
      editedResponse: "We have identified the CSV export issue and a fix is rolling out today.",
      agentNotes: "Known bug, fix in deploy pipeline",
    }));

    const output = await result;
    expect(output.getStatus()).toBe("SUCCEEDED");
    expect(output.getResult()).toMatchObject({ status: "resolved", ticketId: "TKT-001" });
  });

  // Additional tests in the repo: escalation flow, agent rejection, callback failure
});

setupTestEnvironment and teardownTestEnvironment are static methods that start and stop the local checkpoint server. They run once per test file in beforeAll/afterAll. The runner instance is created per test in beforeEach and reset in afterEach. The skipTime: true option fast-forwards any context.wait() calls so tests run instantly.

The interesting part is the callback interaction: runner.getOperation("agent-review") blocks until the handler reaches waitForCallback("agent-review") and creates the callback. Then sendCallbackSuccess simulates the external system responding. This lets you test the full suspend/resume lifecycle without deploying. The repo includes tests for all three paths: standard resolution, escalation with specialist review, and agent rejection. There's also a test that uses sendCallbackFailure to verify error handling when an external system reports a failure.

Run the tests with npm test, or use the run-durable CLI to run the handler directly with a payload:

npx run-durable --skip-time --verbose --event '{"ticketId":"TKT-001","subject":"Test ticket"}' src/index.ts

Try the Demo

The repo includes an interactive demo that runs the entire workflow in your terminal, showing each stage: AI analysis, human review prompts, checkpoint history, and final resolution.

Run npm run demo to open the interactive menu, or skip it with a direct command:

Local mode (no AWS credentials needed)

npm run demo:local -- --ticket=standard

Local mode uses mocked Bedrock responses so you can see the full workflow without calling AWS. Here's what the first few steps look like:

  ──────────────────────────────────────────────
  Ticket TKT-001
  Customer:  CUST-123 (pro)
  Subject:   Cannot export CSV reports
  ──────────────────────────────────────────────

  ▶ step: analyze-ticket
    ✓ Checkpointed analyze-ticket (1204ms)

  ──────────────────────────────────────────────
  AI Triage Result
  Category:    technical
  Priority:    high
  Sentiment:   frustrated
  Escalation:  No
  ──────────────────────────────────────────────

  ⏸ waitForCallback: agent-review
    Function suspended. Compute charges stopped.

The demo pauses at each callback and prompts you to respond as the agent or specialist. It walks through three ticket scenarios:

Standard ticket (pro tier, CSV export bug): AI analyzes, agent approves with edits, reply sent.
Enterprise escalation (security concern): AI flags for escalation, agent approves, specialist reviews, reply sent.
Agent rejection (feature request): AI suggests a response, agent rejects, ticket returned for manual handling.

At each human review step, the demo pauses and lets you play the role of the support agent or specialist. You approve, reject, or edit the AI's suggestion. The demo shows the execution history after each step so you can see the checkpoint/replay model in action.

Cloud mode (real Bedrock responses)

npm run demo:cloud -- --ticket=standard --region=us-east-2

Cloud mode invokes the deployed Lambda function with real Bedrock calls. You'll see actual AI-generated triage analysis and can watch the durable execution checkpoints in the Lambda console. Add --profile=<name> if you're not using the default AWS profile.

Deploying and Invoking

Build and deploy:

sam build
sam deploy --guided

Once deployed, invoke the function asynchronously with a qualified ARN. The AutoPublishAlias in the template created a live alias:

aws lambda invoke \
  --function-name durable-support-triage:live \
  --invocation-type Event \
  --durable-execution-name "ticket-TKT-001" \
  --cli-binary-format raw-in-base64-out \
  --payload '{
    "ticketId": "TKT-001",
    "customerId": "CUST-123",
    "customerTier": "pro",
    "subject": "Cannot export CSV reports",
    "body": "When I click the export button, nothing happens.",
    "contactEmail": "customer@example.com"
  }' \
  response.json

A few things to note:

--invocation-type Event is required for long-running workflows. Synchronous invocation (RequestResponse) times out after 15 minutes.
--durable-execution-name provides built-in idempotency. If you invoke the function twice with the same execution name, the second invocation returns the existing execution instead of creating a duplicate. Using the ticket ID as the execution name is a natural fit. Note: execution names must be alphanumeric, hyphens, or underscores. If your ticket IDs contain dots, slashes, or other special characters, sanitize them first.
:live on the function name is the alias qualifier. Without it, you'll get InvalidParameterValueException: Durable execution requires qualified function identifier.

Monitoring execution progress

Check execution status in the Lambda console under the Durable executions tab. You'll see each step's status and timing, including when the function suspended waiting for the agent callback.

You can also check programmatically:

aws lambda get-durable-execution \
  --durable-execution-arn "arn:aws:lambda:us-east-2:123456789012:function:durable-support-triage:live/durable-execution/ticket-TKT-001/<run-id>"

Replace <run-id> with the run ID returned in the initial invoke response. You can also find it in the Lambda console under the Durable executions tab.

Completing the callbacks

When the support agent finishes their review, send the callback from your ticketing system:

aws lambda send-durable-execution-callback-success \
  --callback-id "your-callback-id-here" \
  --cli-binary-format raw-in-base64-out \
  --result '{
    "approved": true,
    "editedResponse": "Hi, thanks for reporting this. We have identified the issue and a fix is rolling out today.",
    "agentNotes": "Known bug in CSV export module"
  }'

The --result value is a JSON string. The CLI handles serialization, so you pass the JSON object directly (unlike the test SDK, where you explicitly call JSON.stringify()).

The function resumes, checks for escalation, and continues. If a specialist callback is pending, the same pattern applies: the specialist's system calls send-durable-execution-callback-success when their review is complete. There's also send-durable-execution-callback-failure for when an external system needs to report an error (e.g., agent rejects the ticket, or an integration fails).

You can also react to execution state changes via EventBridge. Lambda emits events to the default event bus when executions start, succeed, fail, or time out. Create an EventBridge rule with this event pattern:

{
  "source": ["aws.lambda"],
  "detail-type": ["Durable Execution Status Change"]
}

Gotchas and Hard-Won Lessons

Determinism is not optional

This is the rule that trips people up. Code outside steps re-executes on every replay. If it produces different results each time, your workflow breaks in subtle ways.

// This generates a different ID on each replay
const requestId = crypto.randomUUID();
await context.step("use-id", async () => saveToDb(requestId));

// This generates one ID, checkpoints it, and returns the same value on replay
const requestId = await context.step("gen-id", async () => crypto.randomUUID());
await context.step("use-id", async () => saveToDb(requestId));

The same applies to Date.now(), Math.random(), API calls, and database queries. If it can return different values, wrap it in a step.

The ESLint plugin (@aws/durable-execution-sdk-js-eslint-plugin) catches common violations. Set it up early.

Closure mutations are lost on replay

Variables you modify inside a step are not preserved across replays:

let total = 0;
await context.step("calculate", async () => {
  total = 42; // This mutation is lost on replay
});
console.log(total); // Always 0 on replay

// Instead, return values from steps
total = await context.step("calculate", async () => 42);
console.log(total); // Always 42

This is because the step function doesn't re-execute on replay. It returns the cached result. But the closure variable was modified by the function body, which never ran. Return values from steps instead of modifying outer variables.

The qualified ARN requirement is easy to miss

Durable functions require a qualified function identifier: a version number, alias, or $LATEST. Using an unqualified ARN silently fails or throws InvalidParameterValueException.

The AutoPublishAlias SAM property solves this. It creates a new version and updates the alias on every deploy. If you're using EventBridge Scheduler or other services to invoke your function, make sure they target the alias ARN, not the unqualified ARN.

More steps means slower replay

Every time your function resumes, the SDK replays from the beginning, returning cached results for completed steps. The more steps you have, the more replay overhead per resumption.

This is a trade-off. More granular steps give you better debuggability and more precise retry boundaries. Fewer steps give you faster replay. In practice, group related operations into a single step unless you need separate retry behavior or checkpoint boundaries.

context.wait() is the simplest superpower

The "How Checkpoint/Replay Works" section mentions context.wait() for fixed-duration pauses, but the handler only uses waitForCallback(). In practice, context.wait() is one of the most useful primitives. Need a 24-hour cooling-off period before sending a follow-up? One line:

await context.wait("cooling-off", { hours: 24 });

The function suspends, compute charges stop, and Lambda resumes it 24 hours later. No cron jobs, no EventBridge Scheduler, no polling.

You can't enable durable execution on existing functions

DurableConfig can only be set when creating a function. You can't toggle it on an existing function. If you need to migrate, you'll need to create a new function. Plan for this.

Changing DurableConfig in CloudFormation also requires resource replacement, not an in-place update.

Checkpoint payloads have a 256KB limit

Each step result is serialized and stored as a checkpoint. If a step returns an object larger than 256KB, you'll get a CheckpointUnrecoverableExecutionError.

The workaround: store large data in S3 or DynamoDB and return a reference from the step.

const dataRef = await context.step("store-large-data", async () => {
  const key = `tickets/${ticketId}/attachments.json`;
  await s3.putObject({ Bucket: bucket, Key: key, Body: JSON.stringify(largeData) });
  return { bucket, key };
});

Know your failure modes

If a step throws an unrecoverable error (after all retries are exhausted), the execution moves to a FAILED state. You can inspect the error in the Lambda console or via the get-durable-execution API. For cases where you want to fail immediately without retries, throw an UnrecoverableInvocationError:

import { UnrecoverableInvocationError } from "@aws/durable-execution-sdk-js";
throw new UnrecoverableInvocationError("Customer account not found");

Failed executions can't be resumed. You'd need to start a new execution. Design your workflows so that steps are idempotent in case you need to re-run from scratch.

Use Lambda versions for deploy safety

If you update your function code while an execution is suspended, replay uses the version that started the execution. This prevents inconsistencies from code changes mid-workflow. AutoPublishAlias handles this, but it's worth understanding why: if your new code changes a step's return shape or removes a step, replay on the old version still works because Lambda pins executions to their starting version.

Version pinning protects your function code, but it doesn't protect external schemas. If an execution suspends on Monday waiting for a callback, and on Wednesday your ticketing system starts sending a different JSON structure in the callback payload, the Monday execution will fail when it resumes. Keep callback payloads backwards compatible for as long as executions can be in flight.

Plan your observability early

For production workflows that can run for days, go beyond basic CloudWatch Logs. Set up CloudWatch alarms on stuck executions (no state change within expected timeframes), use the EventBridge integration to track execution lifecycle events, and consider CloudWatch Logs Insights queries for filtering by execution name across replays.

When to Use What

Durable functions and Step Functions are not competing. They solve different problems.

	Durable Functions	Step Functions
Workflow definition	Sequential code in your language	Amazon States Language (JSON/YAML)
Best for	Application logic, tightly coupled workflows	Cross-service orchestration
Service integrations	Via SDK in your code	220+ native integrations
Debugging	CloudWatch Logs, execution history	Visual console, step-by-step
Infrastructure	Single Lambda function	State machine + Lambda functions
Scaling	Lambda concurrency limits	Distributed Map for large-scale parallel processing
Mental model	Write code	Design state machines

On cost: durable functions use standard Lambda pricing for active compute time. During waits, compute charges stop. Step Functions charges per state transition, which adds up for high-volume workflows. See Lambda pricing and Step Functions pricing for current details.

Use durable functions when your workflow is application logic that reads naturally as sequential code. Support ticket triage, approval workflows, AI agent loops, saga patterns.

Use Step Functions when you're orchestrating across multiple AWS services, need visual debugging, or need the 220+ native integrations. ETL pipelines, media processing, infrastructure provisioning.

Use both together when you have a high-level orchestration (Step Functions) that delegates to individual workflows (durable functions) for complex application logic.

What's Next

This post covered the fundamentals: what durable functions are, how checkpoint/replay works, and how to build and test a complete AI-powered workflow with human-in-the-loop callbacks. In the next post, I'll use durable functions to build a multi-agent orchestration workflow where multiple AI agents collaborate on complex tasks with checkpointed reasoning.

Additional Resources

What workflows are you thinking about building with durable functions? Let me know in the comments!

DEV Community: Gunnar Grosch

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

Installing and authenticating

Getting a number

Making a call

Sending a message

Testing a webhook locally

Streaming logs

What else the CLI covers

Troubleshooting

What comes next

Additional Resources

Getting Started with Sinch Functions

You'll need

Installing the CLI

Creating your first function

Running locally

Adding a menu

Responding to input

Configuration and secrets

Deploying

Troubleshooting

Cleaning up

What else you can build

Additional Resources

Yells at Cloud, Episode 1: Generally Available

Summary

Timestamps

Links

Hosts

Follow the show

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

The four methods

SMS OTP

Flash Call

Phone Call Verification

Data Verification

How to pick

Fallback chains

Wrapping up

Additional Resources

Phone-Based User Verification in TypeScript and Python

Prerequisites

How verification works

The SDK approach (Node.js)

Raw HTTP

Python

Node.js (no SDK)

Things worth knowing

Verifications expire

Phone numbers must be E.164

FlashCall code format

Data Verification requires cellular data

Wrapping up

Additional Resources

Sending SMS from AWS Lambda with the Sinch SDK

Prerequisites

Storing credentials in SSM Parameter Store

The Lambda function

TypeScript

Python

The SAM template

Invoking the function

Testing locally

Things worth knowing

Phone numbers must be E.164

Long messages get split

Error handling and delivery status

Wrapping up

Additional Resources

Two-Way SMS Conversations on AWS

The architecture

The webhook function

The processor function

The sender function

What an inbound message looks like

Deploying

Registering the webhook

Testing

Things worth knowing