DEV Community: Sonam

Build a Stateful AI Agent for Event Sponsorships

Sonam — Thu, 10 Sep 2026 21:46:01 +0000

An event booth can generate hundreds of conversations in a day, but the useful context often disappears as soon as an attendee walks away.

Someone asks a detailed product question. Another person wants a demo but leaves before speaking to sales. A third enters a giveaway, then comes back later with a buying timeline. By the end of the event, the team has badge scans and scattered notes, but not a continuous record of what each person actually needed.

The event-sponsorship-agent example turns that fragmented workflow into one stateful application on Telnyx Edge Compute.

It serves a branded microsite, answers questions through browser chat and messaging, detects the attendee's language, collects qualification details, stores leads in SQLDB, routes high-intent prospects to sales by SMS, schedules follow-up, and produces an attribution report.

What runs inside the application?

The project is a TypeScript Edge function built around a SponsorAgent actor. Each attendee or browser session maps to its own actor instance, giving the conversation a durable home.

The application combines:

Agent SDK actors for per-attendee conversation state
Telnyx AI Inference for language detection, translation, product answers, and contextual replies
Programmable Messaging for SMS and WhatsApp conversations
SQLDB for lead capture and attribution data
KV for request-rate counters
Scheduled tasks for post-event follow-up
Email for follow-up when that is the attendee's preferred channel
Edge Compute for the microsite, APIs, and webhook handlers

The voice webhook is also included as an integration point for a future Call Control conversation flow. In the current sample it validates and routes the event, then logs the handoff rather than implementing a complete live voice exchange.

One attendee, one durable agent

Inbound SMS and WhatsApp messages are routed by phone number. Browser conversations are routed by session ID.

Conceptually, the handler does this:

const agent = env.SPONSOR_AGENT.idFromName(attendeeId);
return agent.handleChatMessage({ sessionId, text });

The resulting actor owns the attendee's channel, language, qualification step, collected details, giveaway status, demo request, and follow-up state.

That matters because event conversations rarely happen in one perfectly ordered exchange. An attendee might ask a product question first, request a demo ten minutes later, and only then provide their company and timeline. The agent can continue the same workflow instead of rebuilding context from every request.

The qualification flow

The agent guides an attendee through a short sequence:

Name
Company
Use case
Company size
Implementation timeline
Preferred follow-up channel

Each response updates the actor state and is upserted into SQLDB. The same processMessage() method also recognizes giveaway, demo-booking, and product-question intents.

For product questions, the actor calls Telnyx AI Inference through the native binding:

const response = await this.env.TELNYX.ai.openai.chat.createCompletion({
  model: "moonshotai/Kimi-K2.6",
  messages: [
    { role: "system", content: systemPrompt },
    { role: "user", content: question },
  ],
});

The sample first detects the attendee's language and stores the ISO language code in session state. Later answers and qualification prompts can then be returned in that language.

Routing a hot lead while they are still at the booth

A CRM record is useful, but timing is the interesting part of an event workflow.

When an attendee completes the qualification fields and requests a demo, the agent sends an SMS alert to the sales team immediately. The notification contains the captured context, including the company, use case, size, and timeline.

await this.env.TELNYX.messages.send({
  to: salesTeamNumber,
  from: eventNumber,
  text: hotLeadSummary,
});

This gives a sales representative the opportunity to start a relevant conversation while the attendee is still nearby, rather than discovering the lead in a report the following week.

Scheduling follow-up without a separate queue

After qualification, the attendee can choose SMS, WhatsApp, email, or a call as the preferred follow-up channel. The actor schedules the work with the Agent SDK:

await this.schedule(delaySeconds, "sendFollowUp", {
  phone,
  channel,
});

When the task runs, the agent retrieves the lead from SQLDB, falls back to its durable state if necessary, asks the inference model to create a concise message, and sends or logs the result for the selected channel.

Demo deployments use a short delay so the workflow is easy to observe. A live deployment can schedule the follow-up for the next day.

Measuring more than badge scans

The GET /api/report endpoint queries SQLDB and returns:

Total captured leads
Total qualified leads
Total converted or giveaway-entry leads
Lead counts by interaction channel
Lead counts by use case

This is intentionally a compact report, but the data model can be extended with campaign IDs, event locations, session attendance, meetings completed, or downstream CRM outcomes.

The API surface

The main routes are:

GET  /                  Branded event microsite
POST /api/chat          Browser chat
POST /api/followup      Schedule attendee follow-up
GET  /api/report        Lead attribution report
POST /webhook/sms       Inbound SMS
POST /webhook/whatsapp  Inbound WhatsApp
POST /webhook/voice     Voice integration scaffold
GET  /health            Health check

Messaging webhooks are verified with the Telnyx Ed25519 signature before their payloads are accepted. The interaction routes also use KV-backed limits: ten messaging requests, five voice events, or twenty browser-chat requests per identifier in a 60-second window.

Run it locally

Clone the examples repository and enter the project:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/event-sponsorship-agent
npm install
npm test

The project includes a local development adapter with in-memory KV, SQLite, and stubbed communications calls. This lets you open the microsite and exercise the chat, lead, rate-limit, and reporting flows without sending real messages.

For an Edge deployment, configure the actor, SQLDB, KV, Telnyx binding, and required secrets in telnyx.toml, then ship it:

telnyx-edge types
telnyx-edge ship

Keep DEMO_MODE=true while testing. Before enabling real communications, replace every placeholder, configure approved sending resources, verify webhook signatures, and review the applicable messaging requirements.

Where this pattern goes next

This example is framed around event sponsorship, but the architecture applies anywhere one real-world relationship needs persistent context across communications:

Conference attendee concierge
Trade-show lead qualification
Field marketing follow-up
Partner onboarding
Customer success events
Product-launch registration and support

The useful pattern is not simply "add a chatbot to a microsite." It is giving each attendee a durable agent that can remember the conversation, act across channels, and connect the interaction to measurable business outcomes.

Resources

What would you want an event agent to do next: sync with a CRM, coordinate meeting availability, or score leads using post-event behavior?

Build an SMS Two-Factor Authentication Agent at the Edge

Sonam — Wed, 09 Sep 2026 00:17:12 +0000

Sending an SMS verification code takes one API call. Managing everything around that call is the real engineering problem.

A two-factor authentication flow needs to generate a code, limit repeated requests, store the code safely, reject bad attempts, expire it on time, and make it unusable after successful verification. A traditional implementation often adds a web server, database, cache, cleanup worker, and secrets-management layer before the first message is sent.

I built sms-two-factor-agent to explore a smaller architecture. It runs as a TypeScript agent on Telnyx Edge Compute and uses four primitives:

One durable actor per phone number
Telnyx KV with a five-minute TTL
Scheduled cleanup through the Agent SDK
SMS delivery through the native Telnyx binding

The result is a complete verification-code lifecycle behind two HTTP endpoints.

The API surface

The application exposes two main routes:

POST /verify   Generate and send a six-digit code
POST /check    Validate a submitted code

A client starts verification with a placeholder E.164 number:

curl -X POST https://<your-function>.telnyxcompute.com/verify \
  -H "Content-Type: application/json" \
  -d '{"phone":"+1555XXXXXXX"}'

After receiving the code, the client submits it:

curl -X POST https://<your-function>.telnyxcompute.com/check \
  -H "Content-Type: application/json" \
  -d '{"phone":"+1555XXXXXXX","code":"123456"}'

Successful verification deletes the stored code immediately, making it single-use.

Why use one actor per phone number?

The request handler derives an actor identity from the phone number and routes both operations to that same actor:

const id = env.AGENT.idFromName(actorNameFromPhone(phone));
const agent = env.AGENT.get(id);

Each actor owns the verification state for one phone number, including request attempts, failed checks, and the current rate-limit window. Calls for that actor are serialized, which makes per-number state easier to reason about when requests arrive at nearly the same time.

Different phone numbers map to different actors, so their state remains isolated and they can be processed independently.

Expiring codes without a cleanup worker

The primary code store is Telnyx KV. Each generated code is written with a 300-second TTL:

await this.env.KV.put(key, code, {
  expirationTtl: 300,
});

The key expires automatically after five minutes, so there is no table to sweep and no periodic cleanup job to maintain.

The agent also schedules an expiry task:

await this.schedule(300, "expireCode", { phone });

That task provides a deterministic place to remove any remaining code data and reset the actor's counters. The current sample also falls back to durable actor storage if a KV write fails, recording an explicit expiration timestamp so the fallback copy cannot remain valid indefinitely.

Sending SMS through the Telnyx binding

In live mode, the actor sends the verification message through the Edge runtime's Telnyx binding:

await this.env.TELNYX.messages.send({
  from: fromNumber,
  to: phone,
  text: `Your verification code is ${code}. It expires in 5 minutes.`,
});

The binding gives the deployed function a pre-authenticated Telnyx client. The application does not need to hardcode an API key or construct an authorization header for every message.

The sample starts in DEMO_MODE, where generated codes are written to the actor logs instead of being sent. That lets you test routing, expiry, verification, and rate limiting before connecting a real SMS-capable number.

Rate limiting belongs with the verification state

The actor allows five send attempts in a five-minute window. Because the counter is stored with the phone number's durable state, the limit survives ordinary process restarts and does not require a separate rate-limiting service.

Failed verification attempts are tracked separately. A correct code clears the code and resets the counters; an incorrect code decrements the remaining attempts returned to the client.

This is a useful property of the actor model: the behavior and the state it protects live together.

Running the example

Clone the code and install its dependencies:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/sms-two-factor-agent
npm install
npm run typecheck
npm test

Create the actor function and KV namespace with the Telnyx Edge CLI, place the returned identifiers in telnyx.toml, and deploy:

telnyx-edge new-func --actor -l ts -n sms-two-factor-agent
telnyx-edge storage kv create --name sms-two-factor-agent-2fa
telnyx-edge ship

Keep demo mode enabled for the first run. When you are ready to send real messages, configure an SMS-capable Telnyx number, set DEMO_MODE to false, and deploy again. If you send application-to-person traffic to US numbers, make sure the sender and use case satisfy the applicable 10DLC requirements.

Where to take it next

This sample deliberately focuses on the verification lifecycle rather than a complete identity system. Before using the pattern in production, consider adding hashed codes, stronger abuse controls, audit events, delivery-status handling, idempotency, tenant isolation, and a recovery path.

The broader pattern also applies beyond 2FA. Per-recipient actors, expiring state, scheduled work, and native communications bindings are useful for passwordless login, account recovery, consent confirmation, time-sensitive alerts, and other workflows where state and messaging must move together.

Resources

How would you extend this pattern: stricter risk scoring, multiple delivery channels, or a full passwordless sign-in flow?

Build an AI Event Microsite on Telnyx Edge Compute

Sonam — Fri, 04 Sep 2026 21:18:42 +0000

Most event apps quietly become several apps.

You start with a landing page. Then someone asks for SMS updates. Then attendees want a way to ask questions. Sponsors want lead capture. Organizers want feedback. Someone wants a daily report.

Suddenly your "event site" is a static frontend, a webhook server, a chatbot, a voice app, a database, an email job, and a few scripts holding it together.

The edge-event-microsite example compresses that into one deploy.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/edge-event-microsite

What it builds

This is a TypeScript app running on Telnyx Edge Compute.

It includes:

a server-rendered event microsite
event schedule and sponsor data stored in Telnyx KV
an SMS/WhatsApp AI concierge
in-browser voice AI with WebRTC
lead qualification with Telnyx AI Inference
voice feedback transcription
sponsor reporting
webhook signature verification

The important part is that all of these surfaces read from the same source of truth: one Telnyx KV namespace.

The architecture

At a high level:

Attendee browser
  -> Edge function
  -> Telnyx KV

SMS / WhatsApp message
  -> Edge function
  -> Telnyx AI Inference
  -> Telnyx Messaging
  -> Telnyx KV

Browser voice agent
  -> WebRTC
  -> AI assistant tool callback
  -> Edge function
  -> Telnyx KV

The site, the text concierge, and the voice assistant all use the same event data.

Change the schedule once, and every surface can answer from the same updated state.

No sync jobs. No duplicated config. No stale FAQ hiding in a separate bot.

Why Edge Compute fits

An event experience has a lot of small, latency-sensitive interactions:

render the schedule
answer "where is the keynote?"
capture a lead
route a hot lead to sales
transcribe attendee feedback
generate a sponsor report

None of those need a giant backend.

They need a fast place to run close to the communications layer.

That is the useful pattern in this sample: the Edge function becomes the backend for the website, the messaging workflows, and the voice assistant tool calls.

KV as the shared event brain

The sample uses Telnyx KV for event state:

event details
schedule items
sponsor information
attendees
leads
feedback
assistant configuration

The microsite reads from KV when rendering pages and APIs.

The SMS/WhatsApp concierge reads from KV when answering attendee questions.

The voice assistant can call back into the same Edge function to look up event information.

That shared state is what keeps the experience coherent.

AI concierge for SMS and WhatsApp

Attendees can ask questions like:

Where is the keynote?
What time is the workshop?
Who is sponsoring the afterparty?

The Edge function uses Telnyx AI Inference to generate a useful answer from the event context, then sends the response back with Telnyx Messaging.

The same flow can also qualify leads.

If a message suggests strong buying intent, the app can extract company, role, and interest level, store that lead in KV, and route the hot lead to a sales rep.

Voice AI in the browser

The sample also includes an in-browser voice path.

Instead of forcing attendees to call a phone number, the microsite can connect them to a Telnyx AI Assistant through WebRTC using @telnyx/ai-agent-lib.

The assistant is provisioned server-side and can use a webhook tool that queries the same KV data as the site and SMS concierge.

That gives attendees three ways to interact with the same event backend:

browse the site
text the concierge
talk to the assistant

Feedback transcription and sponsor reports

After a session, attendees can leave spoken feedback.

The app transcribes the audio, summarizes it with AI, and stores the result.

From there, the organizer can generate a sponsor report with lead counts, feedback summaries, and engagement metrics.

This is where the example starts to feel less like a website and more like an event operating system.

Run it

Clone the repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/edge-event-microsite
npm install

Authenticate and create a KV namespace:

telnyx-edge auth api-key set <YOUR_TELNYX_API_KEY>
telnyx-edge storage kv create --name edge-event-microsite-data

Add webhook verification:

PUBLIC_KEY=$(curl -s -H "Authorization: Bearer $TELNYX_API_KEY" \
  https://api.telnyx.com/v2/public_key | jq -r '.data.public')

telnyx-edge secrets add TELNYX_PUBLIC_KEY "$PUBLIC_KEY"

Deploy:

telnyx-edge ship

The function deploys to a *.telnyxcompute.com URL.

Production notes

Before using this for a real event, I would add:

authentication for organizer/admin routes
stricter permissions around lead exports
rate limits for public messaging and voice flows
moderation for attendee-submitted feedback
consent language for transcription
retries for sponsor report delivery
analytics around which channel attendees prefer

The sample is intentionally compact, but the architecture is the interesting part.

One Edge function can serve the event website, answer attendee questions, power a voice assistant, capture feedback, and report back to sponsors.

Resources:

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/edge-event-microsite
Edge Compute docs: https://developers.telnyx.com/docs/edge-compute
Telnyx AI Inference docs: https://developers.telnyx.com/docs/inference
Messaging docs: https://developers.telnyx.com/docs/messaging
Telnyx AI Assistants docs: https://developers.telnyx.com/docs/inference/ai-assistants
Telnyx AI skills and toolkits: https://github.com/team-telnyx/ai

Build an AI Meeting Facilitator on Telnyx Edge Compute

Sonam — Fri, 04 Sep 2026 03:27:37 +0000

Most meeting tools wait until the call is over.

They record, transcribe, summarize, and then hand you notes after the damage is already done.

That is useful, but it misses the live part of the meeting: who got interrupted, who has not spoken yet, and whether the group is actually making decisions.

The conference-agent-mediator example takes a different approach. It puts an AI participant directly into a Telnyx conference bridge.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/conference-agent-mediator

What it builds

This is a TypeScript app running on Telnyx Edge Compute with the Telnyx Agent SDK.

The agent:

joins a Telnyx conference as a participant
starts live transcription for each speaker
stores transcript turns in durable actor state
checks the conversation every 30 seconds
asks an LLM whether the room needs a facilitation nudge
speaks that nudge into the conference
summarizes the meeting when it ends
sends the summary by SMS
streams live state to observers over WebSocket

The result is a meeting facilitator that is not just a post-call summary bot. It is in the room while the conversation is happening.

The flow

At a high level:

Caller joins conference
  -> ConferenceAgent actor is created
  -> participant audio is transcribed
  -> transcript turns are stored
  -> mediation loop checks who has spoken
  -> AI generates a short facilitator prompt
  -> Telnyx speaks the prompt into the bridge
  -> meeting ends
  -> AI summary is generated
  -> SMS summary is sent

The main idea is one actor per conference.

That actor owns the state for the meeting: participants, transcript, prompts, phase, and final summary.

Why actors fit this problem

A conference is stateful.

Events arrive over time:

a participant joins
transcription starts
a speaker says something
another speaker joins
the mediator decides whether to intervene
the conference ends

If this were split across a stateless webhook handler, a worker, a database, and a scheduler, you would spend a lot of time rebuilding context.

With the Agent SDK, the conference itself can become the unit of state.

The sample keeps the transcript and participant state on the ConferenceAgent, so every webhook and timer callback has the context it needs.

The mediation loop

The app uses a crash-safe timer that runs every 30 seconds.

Each pass checks whether the conference is live, looks at recent transcript turns, finds quiet participants, and asks Telnyx AI Inference for a short facilitator line.

The prompt is intentionally conservative. The agent should not constantly interrupt. It should only step in when there is a useful reason, like bringing a quiet person into the conversation or helping the group return to a decision.

Example mediator output:

Before we move on, I would like to hear from Dana, who has not had a chance to weigh in yet.

In live mode, the agent speaks that line into the conference bridge.

API and runtime pieces

The example includes:

POST /webhooks/voice for Telnyx Call Control events
an Agent SDK actor for conference state
live transcription events from Telnyx
Telnyx AI Inference for mediation and summary generation
Telnyx Messaging for the post-call SMS summary
an observer socket for live transcript and state updates
demo mode so you can test the pipeline without real phone calls

The important part is that these are not stitched together across several vendors.

Voice, transcription, LLM inference, stateful agents, and SMS all sit behind the same Telnyx platform.

Running the example

Clone the repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/conference-agent-mediator
npm install

Set your runtime values with placeholders first:

telnyx-edge secrets add TELNYX_API_KEY <YOUR_TELNYX_API_KEY>
telnyx-edge secrets add SMS_FROM <YOUR_TELNYX_SMS_NUMBER>
telnyx-edge secrets add SMS_TO <SUMMARY_RECIPIENT_NUMBER>

Deploy:

telnyx-edge ship

Then point your Telnyx Call Control application webhook at:

https://conference-agent-mediator-<id>.telnyxcompute.com/webhooks/voice

The sample also supports demo mode, which is useful when you want to exercise the actor, transcript, mediation, and summary flow before wiring up live calls.

What I like about this pattern

The interesting part is not only that AI can summarize a meeting.

The interesting part is that the agent can participate while the meeting is still happening.

Because the agent runs close to the communications path, it can react to the live transcript quickly enough for a mediation prompt to still feel relevant.

That opens up a broader pattern:

meeting facilitators
sales-call coaches
support-call supervisors
interview note takers
training assistants
live compliance monitors

Any workflow where the assistant needs to observe a conversation, keep state, and act during the call can use the same foundation.

Production notes

Before using this with real meetings, I would add:

authentication for observer sockets
participant consent flows
retention controls for transcripts
redaction for sensitive data
stronger speaker identity mapping
prompt tuning for different meeting cultures
monitoring for transcription, inference, and SMS delivery
explicit controls for when the agent is allowed to speak

The sample keeps the moving parts small on purpose, but the architecture is the useful thing: one durable agent owns one live conversation.

Resources:

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/conference-agent-mediator
Telnyx Agent SDK docs: https://developers.telnyx.com/docs/agent-sdk
Edge Compute docs: https://developers.telnyx.com/docs/edge-compute
Call Control API reference: https://developers.telnyx.com/api-reference/call-control
Telnyx AI Inference docs: https://developers.telnyx.com/docs/inference
Telnyx Messaging docs: https://developers.telnyx.com/docs/messaging
Telnyx AI skills and toolkits: https://github.com/team-telnyx/ai

Build an Agent That Turns Voicemails Into SMS Summaries

Sonam — Thu, 03 Sep 2026 02:30:46 +0000

Voicemail is one of those workflows that still feels weirdly stuck.

Someone leaves a message. You get a badge. Then you have to listen through a minute of audio just to find the ten seconds that matter: who called, what they need, whether there is a deadline, and whether you need to call back.

The voicemail-to-sms-agent example turns that into an event-driven AI workflow.

When a voicemail is left, the agent transcribes the recording, summarizes it with an LLM, sends the summary over SMS, and archives the original audio. The result is closer to voicemail triage than voicemail playback.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/voicemail-to-sms-agent

What the app does

This is a TypeScript example built for Telnyx Edge.

The flow is:

Caller leaves voicemail
  -> Call Control webhook fires
  -> Edge agent receives the task
  -> agent downloads the recording
  -> Speech-to-Text transcribes the audio
  -> AI Inference summarizes the transcript
  -> Messaging sends the SMS summary
  -> Cloud Storage archives the audio

Instead of checking voicemail manually, the mailbox owner gets a concise text message with the important parts.

The trigger

The agent reacts to a Call Control webhook.

In the sample, the agent checks that the incoming task is a voicemail event before doing any work:

const payload = task.input as WebhookPayload;

if (
  !payload ||
  payload.event !== "call.status" ||
  payload.data?.payload?.call_status !== "voicemail"
) {
  return { status: "ignored" };
}

That keeps the agent focused. It does not process every call event. It only starts the pipeline when the call actually ends in voicemail.

The pipeline

Once the voicemail event is accepted, the agent pulls the key pieces out of the webhook payload:

const callControlId = payload.data.payload.call_control_id;
const recordingId = payload.data.payload.recording?.id;
const callerNumber = payload.data.payload.from;

Then it downloads the audio recording through the Telnyx binding:

const audioBuffer = await telnyx.calls.downloadRecording({
  call_control_id: callControlId,
  recording_id: recordingId,
});

From there, the recording becomes text:

const transcription = await telnyx.ai.stt.transcribe({
  audio: audioBuffer,
  language: "en-US",
});

That transcript is what the LLM sees.

Summarizing the voicemail

The summary step uses Telnyx AI through an OpenAI-compatible chat completion call:

const summaryResponse = await telnyx.ai.openai.chat.createCompletion({
  model: "gpt-4o-mini",
  messages: [
    {
      role: "system",
      content:
        "Summarize the following voicemail transcription into a concise SMS message.",
    },
    {
      role: "user",
      content: `Caller: ${callerNumber}\nTranscription: ${transcriptText}`,
    },
  ],
  max_tokens: 60,
});

The LLM is not being asked to run the whole workflow. It has one job: take a transcript and make it useful enough to read quickly on a phone.

That is the part I like about this pattern. The workflow stays explicit, but the language-heavy step gets handled by AI.

Demo mode vs live mode

The sample includes a LIVE_MODE flag.

When LIVE_MODE=false, the agent logs the SMS it would send:

log.info("Demo mode: SMS not sent. Would send:", {
  to: destinationNumber,
  text: `Voicemail from ${callerNumber}: ${summaryText}`,
});

When LIVE_MODE=true, it sends the message:

await telnyx.messages.send({
  from: this.env.config?.TELNYX_SMS_NUMBER,
  to: destinationNumber,
  text: `Voicemail from ${callerNumber}: ${summaryText}`,
});

That makes the example easier to test safely. You can run the whole pipeline first, inspect the generated SMS payload, and only flip to live mode once you are ready.

Archiving the original audio

The agent also stores the voicemail recording in Telnyx Cloud Storage:

await telnyx.storage.put({
  bucket: this.env.config?.STORAGE_BUCKET || "voicemail-archives",
  key: `voicemails/${recordingId}.mp3`,
  body: audioBuffer,
  contentType: "audio/mpeg",
});

That gives you a lightweight audit trail. The SMS summary is the fast path, but the original audio is still available if the owner needs to review it later.

Why this is useful

This example is small, but the pattern is production-shaped:

react to a communications event
pull the relevant media
run AI on it
notify someone through the right channel
store the source artifact

You could adapt the same shape for customer support inboxes, missed sales calls, appointment reminders, after-hours service lines, or any workflow where voice messages need to become structured follow-up.

Running it

Clone the examples repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/voicemail-to-sms-agent

Install dependencies:

npm install

Create your environment file:

cp .env.example .env

Configure values like:

TELNYX_API_KEY=<your_telnyx_api_key>
TELNYX_SMS_NUMBER=<your_telnyx_sms_number>
MAILBOX_OWNER_NUMBER=<summary_recipient_number>
STORAGE_BUCKET=voicemail-archives
LIVE_MODE=false

Then typecheck, test, and deploy:

npx tsc --noEmit
npm test
npm run deploy

After deployment, point your Call Control voicemail webhook at the deployed Edge URL.

Resources

Code example: https://github.com/team-telnyx/telnyx-code-examples/tree/main/voicemail-to-sms-agent
Telnyx AI toolkit: https://github.com/team-telnyx/ai
Telnyx Call Control docs: https://developers.telnyx.com/docs/voice/programmable-voice/call-control-overview
Telnyx AI Inference docs: https://developers.telnyx.com/docs/inference
Telnyx Messaging docs: https://developers.telnyx.com/docs/messaging
Telnyx Portal: https://portal.telnyx.com

I Built an AI Call Router That Actually Understands Intent

Sonam — Mon, 31 Aug 2026 23:13:54 +0000

I’ve always hated phone menus. "Press 1 for sales, 2 for support." By the time you reach the right department, you've listened to three minutes of hold music. I wanted to build something better: a call router that just asks you what you need and routes you instantly.

I built this using Telnyx. Not just their voice API, but their new Edge Runtime. Here’s why that matters.

The Problem with Voice AI

Building voice AI is usually a glue-code nightmare. You need a telephony provider, a speech-to-text service, an LLM provider, and a database to store your routing logic. That’s four different API keys, four different SDKs, and four points of failure.

When latency spikes on the LLM, the caller waits. When the database connection drops, the call fails.

The Telnyx Edge Runtime

Telnyx is AI Communications Infrastructure. They own the telephony network, the AI inference layer, and now, an edge compute runtime.

For this project, I used a StatefulActor on the Edge Runtime. When a call comes in, the runtime spins up an actor dedicated to that call leg. This actor holds the call state in memory. No external session database is required.

To classify the caller's intent, I used the built-in AI Inference binding. It looks like this:

const completion = await this.env.TELNYX.ai.openai.chat.createCompletion({
  model: 'meta-llama/Llama-3.3-70B-Instruct',
  messages: [...]
});

Notice anything missing? API keys. The binding is pre-authenticated. The runtime handles the credentials. I just call the model.

Routing with Telnyx KV

Once the LLM tells me the caller wants "billing," I need to know where to transfer them. I stored the route table in Telnyx KV, a globally distributed key-value store.

const destination = await this.env.ROUTES.get('route:billing');

If the key is missing, it falls back to a default destination.

The Flow

Caller dials in.
The actor answers and speaks a greeting.
gather_using_ai captures the caller's request.
The AI Inference binding classifies the intent.
KV looks up the destination.
The call is transferred.

All of this happens in one edge function. No external servers. No glue code.

Why This Matters

When you build on AI Communications Infrastructure, you stop stitching together disparate services. You start composing capabilities. The telephony, the AI, and the compute live in the same place. The latency is lower. The code is cleaner.

If you want to see the code, I’ve open-sourced it. You can deploy it right now with the Telnyx CLI.

Check out the code here.

Build an AI Call Router That Sends Callers to the Right Team

Sonam — Mon, 31 Aug 2026 21:43:03 +0000

Traditional IVRs make callers do the routing work.

You call a business, listen to a menu, remember the options, press a number, and hope you picked the right path. That works, but it is not how people naturally ask for help.

Most callers already know what they want:

"I need to pay my bill."
"I want to upgrade my plan."
"I need help with support."

The ai-powered-call-router example turns that sentence into the routing decision.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-powered-call-router

What the app builds

This is a Python Flask app that handles inbound calls with Telnyx Call Control and classifies caller intent with Telnyx AI Inference.

The flow looks like this:

Inbound call
  -> Telnyx sends a Call Control webhook
  -> Flask verifies the webhook
  -> app answers the call
  -> app speaks a greeting
  -> app gathers caller speech
  -> AI classifies intent
  -> app announces the transfer
  -> Call Control transfers the caller

Instead of asking the caller to press buttons, the app asks what they need and routes based on their answer.

The core pieces

The example uses:

Telnyx Call Control for answering, speaking, gathering, and transferring calls
Telnyx AI Inference for intent classification
Telnyx webhook verification for signed inbound events
a simple route table for mapping intents to destinations

The source keeps the route table intentionally small:

ROUTE_TABLE = {
    "billing": "+1XXXXXXXXXX",
    "sales": "+1XXXXXXXXXX",
    "support": "+1XXXXXXXXXX",
}

In a real app, those destinations might be queues, agents, contact center flows, or PBX extensions.

Gathering caller speech

Once the inbound call is answered, the app plays a greeting. After the greeting finishes, it starts speech capture using Call Control's AI gather action.

The important detail is that the app waits for the call.speak.ended event before starting the gather. That avoids the greeting and the caller's first response overlapping.

The gather step produces a call.ai_gather.ended event with the caller's utterance.

That text becomes the input to the intent classifier.

Classifying intent with AI

The app sends the caller's transcribed request to Telnyx AI Inference and asks the model to classify it into one of the supported routes.

The default model in the sample is:

meta-llama/Llama-3.3-70B-Instruct

The model does not need to write a long answer. It only needs to return a routing label such as:

billing
sales
support

That keeps the AI part narrow and practical. The LLM is not running the whole call center. It is doing one job: mapping natural language to a route.

Transferring the call

After intent classification, the app speaks a short announcement:

Transferring you to billing. Please hold.

Then it waits for that announcement to finish before calling the transfer action.

That makes the caller experience cleaner. They hear what is happening before the bridge is created.

The example uses a blind transfer: Telnyx dials the destination and connects the original caller once the destination answers.

Webhook verification

Voice automation should not trust random HTTP requests.

The app verifies inbound Telnyx webhooks with Ed25519 signature verification before processing the event:

event = unwrap_with_ed25519(
    request.get_data(),
    request.headers,
    key=TELNYX_PUBLIC_KEY,
)

That means call actions like answer, gather, and transfer only run after the app verifies the webhook came from Telnyx.

Running it locally

Clone the examples repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/ai-powered-call-router

Create a virtual environment and install dependencies:

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

Create your .env file:

cp .env.example .env

Set the required values:

TELNYX_API_KEY=<your_telnyx_api_key>
TELNYX_PUBLIC_KEY=<your_telnyx_public_key>
TELNYX_CONNECTION_ID=<your_call_control_application_id>
AI_MODEL=meta-llama/Llama-3.3-70B-Instruct
PORT=5000

Then run:

python app.py

Expose your local server with a tunnel and point your Telnyx Call Control Application webhook to:

https://<your-tunnel-domain>/webhook

Why I like this pattern

This is a good example of where AI is useful without making the system vague.

The caller still moves through a deterministic telephony flow:

answer the call
gather speech
classify intent
look up a destination
transfer the call

The model only handles the messy human-language part.

That is the sweet spot for a lot of production AI apps: use the LLM where language is ambiguous, but keep the workflow itself explicit and observable.

Production notes

Before using this with real callers, I would add:

retries and fallback routing
latency tracking for gather and classification
route-level analytics
auth around any admin/config endpoints
call recording/transcript retention policy
escalation rules for uncertain classifications
monitoring for failed transfers

But the core idea is simple: callers should be able to say what they need, and your app should route them without forcing them through a rigid menu.

Resources

Code example: https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-powered-call-router
Telnyx AI toolkit: https://github.com/team-telnyx/ai
Telnyx Call Control docs: https://developers.telnyx.com/docs/voice/programmable-voice/call-control-overview
Telnyx AI Inference docs: https://developers.telnyx.com/docs/inference
Webhook signing: https://developers.telnyx.com/development/api-fundamentals/webhooks/receiving-webhooks#webhook-signing
Telnyx Portal: https://portal.telnyx.com

Build a Natural Language IVR with Telnyx Call Control and AI Inference

Sonam — Fri, 28 Aug 2026 21:36:08 +0000

Nobody likes phone trees. "Press 1 for billing, press 2 for support." Miss an option? Start over. It is friction at its worst.

The voice-ivr-with-agent-backend example replaces that with a natural language conversation. Callers just say what they need, and the app routes them to the right department.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/voice-ivr-with-agent-backend

What it builds

A Python/Flask app that handles inbound calls with a conversational IVR:

Inbound Call
    -> answer with Call Control
    -> look up menu config from KV
    -> LLM generates a dynamic greeting
    -> gather(speech) — caller says what they need
    -> LLM routes intent to a department
    -> transfer call

The core primitives

The app combines four Telnyx primitives:

Call Control: answer(), speak(), gather_using_speech(), transfer()
AI Inference: telnyx.ai.openai.chat.completions.create() for greetings and intent routing
KV store: menu config per phone number (business name, departments, transfer numbers, keywords)
Agent state machine: an IVRAgent class that tracks call state, turn count, and retry logic

Dynamic greeting via LLM

Instead of a hardcoded "Press 1 for billing," the app generates a conversational greeting from the KV config:

def generate_dynamic_menu_prompt(menu_config: dict) -> str:
    departments = menu_config.get("departments", [])
    dept_list = "\n".join(
        f"- {d['name']}: {d['description']}" for d in departments
    )
    return (
        f"You are an IVR assistant for {menu_config['business_name']}. "
        f"Available departments:\n{dept_list}\n\n"
        f"Greet the caller briefly and ask how you can help. "
        f"Keep it conversational and under 2 sentences."
    )

The LLM generates the greeting through the OpenAI-compatible Telnyx Inference binding. If it fails, the app falls back to a static greeting from the KV config.

Intent routing via LLM

When the caller speaks, the transcription is passed to route_intent_with_llm. The LLM is instructed to respond with only the department name for reliable parsing:

completion = telnyx.ai.openai.chat.completions.create(
    model="telnyx-llm",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_input},
    ],
    max_tokens=20,
    temperature=0.1,
)
intent = completion.choices[0].message.content.strip().lower()

If the LLM fails or returns "unknown," the app falls back to keyword matching. After max_turns (3 by default), the call transfers to a default operator.

Speech gather with Call Control

The gather_using_speech primitive plays a prompt and captures the caller's speech in one call:

telnyx.Call.gather_using_speech(
    call_control_id,
    payload=prompt,
    voice="female-en-US",
    language="en-US",
    max_duration=15,
)

Webhook verification

Every webhook request is verified with Ed25519 signature verification:

telnyx.Webhook.construct_event(
    payload, signature, timestamp, TELNYX_PUBLIC_KEY
)

This prevents spoofed requests from triggering call actions.

The agent state machine

The IVRAgent class manages each call:

on_connect(): fetch menu config, generate LLM greeting, speak, gather
on_gather_ended(speech): route intent via LLM, transfer or retry
Tracks turn_count and max_turns before falling back to a default transfer

Management API

PUT /api/menu-config/<phone_number>: update KV menu config dynamically
GET /api/menu-config/<phone_number>: retrieve current config
GET /api/agents: list active IVR agents (debugging)
GET /health: health check

Try it

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/voice-ivr-with-agent-backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Fill in your Telnyx API Key, Public Key, Connection ID, and default transfer number. Then:

python app.py
ngrok http 5000

Point your Call Control Application webhook to https://<your-ngrok-url>.ngrok-free.app/webhooks/voice.

Production notes

Before using with real callers, add:

persistent KV store (Redis or database instead of in-memory dict)
caller ID personalization for greetings
call queues for hold instead of blind transfer
auth on management endpoints
monitoring for LLM latency and fallback rates

Resources:

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/voice-ivr-with-agent-backend
Call Control docs: https://developers.telnyx.com/docs/voice/programmable-voice/call-control-overview
AI Inference docs: https://developers.telnyx.com/docs/ai/ai-overview
Webhooks docs: https://developers.telnyx.com/docs/develop/webhooks
Telnyx Python SDK: https://github.com/team-telnyx/telnyx-python
Telnyx AI on GitHub: https://github.com/team-telnyx/ai

Build a Natural Language IVR with Telnyx Call Control and AI Inference

Sonam — Fri, 28 Aug 2026 21:12:30 +0000

Nobody likes phone trees. "Press 1 for billing, press 2 for support." Miss an option? Start over. It is friction at its worst.

The voice-ivr-with-agent-backend example replaces that with a natural language conversation. Callers just say what they need, and the app routes them to the right department.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/voice-ivr-with-agent-backend

What it builds

A Python/Flask app that handles inbound calls with a conversational IVR:

Inbound Call
    -> answer with Call Control
    -> look up menu config from KV
    -> LLM generates a dynamic greeting
    -> gather(speech) — caller says what they need
    -> LLM routes intent to a department
    -> transfer call

The core primitives

The app combines four Telnyx primitives:

Call Control: answer(), speak(), gather_using_speech(), transfer()
AI Inference: telnyx.ai.openai.chat.completions.create() for greetings and intent routing
KV store: menu config per phone number (business name, departments, transfer numbers, keywords)
Agent state machine: an IVRAgent class that tracks call state, turn count, and retry logic

Dynamic greeting via LLM

Instead of a hardcoded "Press 1 for billing," the app generates a conversational greeting from the KV config:

def generate_dynamic_menu_prompt(menu_config: dict) -> str:
    departments = menu_config.get("departments", [])
    dept_list = "\n".join(
        f"- {d['name']}: {d['description']}" for d in departments
    )
    return (
        f"You are an IVR assistant for {menu_config['business_name']}. "
        f"Available departments:\n{dept_list}\n\n"
        f"Greet the caller briefly and ask how you can help. "
        f"Keep it conversational and under 2 sentences."
    )

The LLM generates the greeting through the OpenAI-compatible Telnyx Inference binding. If it fails, the app falls back to a static greeting from the KV config.

Intent routing via LLM

When the caller speaks, the transcription is passed to route_intent_with_llm. The LLM is instructed to respond with only the department name for reliable parsing:

completion = telnyx.ai.openai.chat.completions.create(
    model="telnyx-llm",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_input},
    ],
    max_tokens=20,
    temperature=0.1,
)
intent = completion.choices[0].message.content.strip().lower()

If the LLM fails or returns "unknown," the app falls back to keyword matching. After max_turns (3 by default), the call transfers to a default operator.

Speech gather with Call Control

The gather_using_speech primitive plays a prompt and captures the caller's speech in one call:

telnyx.Call.gather_using_speech(
    call_control_id,
    payload=prompt,
    voice="female-en-US",
    language="en-US",
    max_duration=15,
)

Webhook verification

Every webhook request is verified with Ed25519 signature verification:

telnyx.Webhook.construct_event(
    payload, signature, timestamp, TELNYX_PUBLIC_KEY
)

This prevents spoofed requests from triggering call actions.

The agent state machine

The IVRAgent class manages each call:

on_connect(): fetch menu config, generate LLM greeting, speak, gather
on_gather_ended(speech): route intent via LLM, transfer or retry
Tracks turn_count and max_turns before falling back to a default transfer

Management API

PUT /api/menu-config/<phone_number>: update KV menu config dynamically
GET /api/menu-config/<phone_number>: retrieve current config
GET /api/agents: list active IVR agents (debugging)
GET /health: health check

Try it

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/voice-ivr-with-agent-backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Fill in your Telnyx API Key, Public Key, Connection ID, and default transfer number. Then:

python app.py
ngrok http 5000

Point your Call Control Application webhook to https://<your-ngrok-url>.ngrok-free.app/webhooks/voice.

Production notes

Before using with real callers, add:

persistent KV store (Redis or database instead of in-memory dict)
caller ID personalization for greetings
call queues for hold instead of blind transfer
auth on management endpoints
monitoring for LLM latency and fallback rates

Resources:

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/voice-ivr-with-agent-backend
Call Control docs: https://developers.telnyx.com/docs/voice/programmable-voice/call-control-overview
AI Inference docs: https://developers.telnyx.com/docs/ai/ai-overview
Webhooks docs: https://developers.telnyx.com/docs/develop/webhooks
Telnyx Python SDK: https://github.com/team-telnyx/telnyx-python
Telnyx AI on GitHub: https://github.com/team-telnyx/ai

Build a Shipment Agent That Texts Customers When Packages Move

Sonam — Thu, 27 Aug 2026 19:17:45 +0000

Package tracking usually feels backwards.

The customer gets a tracking number, opens a page, refreshes it, waits, refreshes again, and tries to decode carrier status updates. Even when a business sends SMS updates, those messages are usually one-way.

I wanted to build the opposite pattern: a shipment that can talk.

This example turns each shipment into a small agent. It receives carrier updates, remembers package state, sends proactive SMS messages, handles customer replies, and exposes a voice/call path for the same shipment context.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/shipment-agent

What the app does

The app is a Python Flask service built around a ShipmentAgent class.

Each agent owns the state for one shipment:

shipment ID
current carrier status
ETA
customer contact
event history
scheduled follow-ups

When something changes, the agent wakes up and decides what to do next.

Carrier status update
  -> POST /webhooks/carrier
  -> ShipmentAgent updates package state
  -> Telnyx Messaging sends the customer an SMS

Customer SMS reply
  -> POST /webhooks/telnyx
  -> verified Telnyx webhook
  -> ShipmentAgent responds with shipment context

Customer call
  -> POST /api/agents/<shipment_id>/call
  -> ShipmentAgent returns the current shipment summary

The interesting idea is not just "send a text when a package moves." The interesting idea is that the package has a durable communication object behind it.

Why this pattern matters

Most support automations are built around sessions.

A chat session starts, a user asks a question, the bot responds, and then the session disappears.

Shipments do not work that way. A package may be created today, delayed tomorrow, delivered three days from now, and followed up on next week. The agent needs to survive across events, channels, and time.

That is why this example treats the agent as the package.

Instead of asking "what should this webhook do?" the app asks "what happened to this shipment, and what should its agent do now?"

Carrier updates become customer messages

The carrier webhook accepts statuses like:

PICKED_UP
IN_TRANSIT
DELAYED
OUT_FOR_DELIVERY
DELIVERED

The app maps those carrier statuses into agent events.

For example, when a shipment is picked up, the agent sets its status to IN_TRANSIT, calculates an ETA, and sends the customer an SMS through Telnyx Messaging.

When the package is delivered, the agent sends a delivery message and schedules a follow-up request.

For this demo, state is stored in memory and scheduling uses a background thread. In production, you would move that state into Postgres, Redis, or another durable store, and use a real job runner for future wakes.

The webhook fix that matters

The latest update to this example tightened the inbound SMS path.

That matters because customer replies only work if the Telnyx webhook is verified and parsed correctly.

The app now:

sets the Telnyx public key on the SDK module at startup
reads the correct Telnyx-Timestamp header
verifies incoming webhooks with telnyx.Webhook.construct_event
handles the Telnyx v2 message payload shape
supports from_ when the SDK maps the JSON from field
pins the Telnyx Python SDK to telnyx>=2.0,<3.0

That last point is easy to overlook. The example uses the v2 SDK API shape, including telnyx.Message.create and telnyx.Webhook.construct_event, so the dependency is pinned to avoid accidentally installing a newer incompatible SDK.

Small fix, big difference: inbound SMS replies can now verify correctly and route back to the right shipment agent.

Local setup

Clone the repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/shipment-agent

Create a virtual environment and install dependencies:

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

Create your environment file:

cp .env.example .env

Fill in:

TELNYX_API_KEY=<your_telnyx_api_key>
TELNYX_PUBLIC_KEY=<your_telnyx_public_key>
TELNYX_MESSAGING_PROFILE_ID=<your_messaging_profile_id>
TELNYX_FROM_NUMBER=<your_telnyx_number>
TELNYX_TO_NUMBER=<customer_test_number>

Then run:

python app.py

The app starts on port 5000.

Example carrier event

You can simulate a package delay with:

curl -X POST http://localhost:5000/webhooks/carrier \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_id": "SHP-DEMO-001",
    "status": "DELAYED",
    "event_data": {
      "new_eta": "2026-09-04"
    }
  }'

The app finds or creates the shipment agent, updates the package status, and sends the customer an SMS update.

You can inspect the agent state with:

curl http://localhost:5000/api/agents/SHP-DEMO-001

Where AI fits in

When a customer replies by SMS, the app builds a prompt from the shipment context and the customer's message.

That is the right place to use Telnyx AI Inference for natural language shipment Q&A: "Can I change the delivery instructions?", "Why is this delayed?", or "What happens if I am not home?"

The important part is that the AI response is grounded in the shipment state the agent already owns.

It is not a generic chatbot. It is answering as the communication layer for a specific package.

Production notes

Before turning this into a real logistics workflow, I would add:

persistent storage for shipment agents
idempotency for duplicate carrier webhooks
retry handling for SMS delivery
customer authentication before changing delivery preferences
audit logs for agent decisions
a real background job queue
escalation to a human support workflow

But as a developer example, the core pattern is useful: model real-world objects as durable agents, then give those agents communication channels.

Resources

Code example: https://github.com/team-telnyx/telnyx-code-examples/tree/main/shipment-agent
Telnyx AI toolkit: https://github.com/team-telnyx/ai
Telnyx Messaging docs: https://developers.telnyx.com/docs/messaging
Telnyx Call Control docs: https://developers.telnyx.com/docs/voice/programmable-voice
Webhook signing: https://developers.telnyx.com/development/api-fundamentals/webhooks/receiving-webhooks#webhook-signing
Telnyx Portal: https://portal.telnyx.com

Build an AI Shipment Agent with SMS, Voice, and Telnyx Inference

Sonam — Thu, 27 Aug 2026 18:02:12 +0000

Most package tracking flows make the customer do the work.

You get a tracking number. You open a page. You refresh it. Maybe you get a generic text that says the package is out for delivery. If you need to ask a real question, you usually end up somewhere else entirely.

I wanted to build the opposite shape: what if the package itself had an agent?

The shipment-agent example is a Python and Flask app that treats a shipment as a durable AI entity. It can send proactive SMS updates, understand customer replies with Telnyx AI Inference, and answer inbound calls with shipment context.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/shipment-agent

What it builds

The app centers around a ShipmentAgent.

The agent owns:

shipment status
carrier and tracking context
customer phone number
interaction history
messaging and voice behavior

Instead of a stateless chatbot waiting in a web page, the agent lives alongside the shipment lifecycle.

Carrier update
  -> Flask webhook
  -> ShipmentAgent updates state
  -> SMS customer

Customer SMS reply
  -> Telnyx Messaging webhook
  -> AI Inference response
  -> SMS reply

Customer phone call
  -> Telnyx Call Control
  -> ShipmentAgent answers with context

Why this is useful

Shipment status is not just data. It is a customer communication problem.

People want to know:

Is my package delayed?
Can I leave delivery instructions?
Did it already arrive?
Who do I call if something looks wrong?

Traditional tracking pages are good at showing status, but not at handling conversation. This example shows how to turn the shipment into a small communications agent that can respond across SMS and voice.

The main flow

When a carrier status changes, the app receives a webhook.

For example:

out_for_delivery
delayed
delivered

The ShipmentAgent updates its internal state and sends a message to the customer through Telnyx Messaging.

If the customer replies, the app passes the message and shipment context to Telnyx AI Inference. That lets the response include the current shipment state instead of acting like a generic support bot.

If the customer calls the Telnyx number, the Call Control flow can answer with the same context.

That is the key idea: SMS and voice are not separate experiences. They are two ways to talk to the same shipment agent.

Telnyx pieces used

The example uses:

Telnyx Messaging for proactive SMS updates and customer replies
Telnyx Call Control for inbound voice interactions
Telnyx AI Inference for natural language processing
Telnyx webhook signing to verify inbound events

Webhook verification matters here because the agent updates customer-facing shipment state based on incoming events. You want to know those events are authentic before they change what the agent does.

Running the example

Clone the examples repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/shipment-agent

Create a virtual environment:

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

Copy the environment file:

cp .env.example .env

Fill in the required Telnyx values:

TELNYX_API_KEY
TELNYX_FROM_NUMBER
TELNYX_MESSAGING_PROFILE_ID
TELNYX_PUBLIC_KEY
TELNYX_TO_NUMBER

Then run:

python app.py

The app starts a Flask server locally, and you can connect the webhook URLs to your Telnyx messaging and voice configuration.

What I would add for production

The sample is intentionally small. For a real logistics workflow, I would add:

persistent database storage
idempotency for carrier events
richer delivery instruction handling
customer authentication
escalation to a human support team
retries for SMS and webhook processing
observability around missed or delayed events

But the architecture is the useful part. A shipment can become a durable communications object, not just a tracking number on a page.

Resources

Code example: https://github.com/team-telnyx/telnyx-code-examples/tree/main/shipment-agent
Telnyx AI toolkit: https://github.com/team-telnyx/ai
Telnyx docs: https://developers.telnyx.com
Telnyx Portal: https://portal.telnyx.com

Build an AI Outbound Call Campaign with Python and Telnyx

Sonam — Wed, 26 Aug 2026 21:58:10 +0000

Outbound call campaigns look simple until you need them to behave like real software.

Calling one number is easy. Calling a list of numbers means you suddenly care about queueing, rate limits, call state, webhook verification, result tracking, and summaries for the team.

I built a small example for that pattern: an AI Call Campaign Orchestrator using Python, Flask, Telnyx Call Control, the Telnyx Agent SDK, SQLite, and SMS.

Code: https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-call-campaign-orchestrator

What the app does

The app exposes a simple API:

POST /campaign starts a campaign from a list of phone numbers
GET /campaign/<campaign_id> returns campaign status and call results
POST /webhooks/call receives Telnyx Call Control events
GET /health confirms the service is running

The interesting part is what happens after you submit the campaign.

The CampaignAgent queues the calls, applies a rate limit, places outbound calls through Call Control, stores results in SQLite, and sends an SMS summary when the campaign is complete.

POST /campaign
  -> queue calls
  -> rate-limit delivery
  -> place calls with Call Control
  -> receive signed webhooks
  -> store results in SQLite
  -> send SMS summary

Starting a campaign

You send a list of E.164 phone numbers to POST /campaign:

curl -X POST http://localhost:5000/campaign \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": [
      "+15551234567",
      "+15557654321",
      "+15559876543"
    ]
  }'

The API returns a campaign ID:

{
  "campaign_id": "3f2c1a5e-8b7d-4e6f-9a0c-1d2e3f4a5b6c",
  "status": "started"
}

From there, the agent owns the campaign lifecycle.

Why rate limiting matters

Outbound communication workflows need pacing.

If you fire too many calls at once, you can create a bad user experience and run into carrier or operational limits. This sample uses CALL_RATE_LIMIT_PER_MINUTE so campaign delivery is controlled from configuration instead of buried inside the call loop.

That makes the campaign behavior easier to tune without rewriting the app.

Placing calls with Call Control

For each queued number, the app places an outbound Call Control call with the Telnyx Python SDK.

The app needs:

TELNYX_API_KEY
TELNYX_CONNECTION_ID
TELNYX_PHONE_NUMBER
TELNYX_WEBHOOK_URL

The webhook URL points back to the app, so call lifecycle events can update campaign state as calls are answered, completed, or fail.

Verifying webhooks

The webhook endpoint uses telnyx.webhooks.unwrap() with the Telnyx Ed25519 public key.

That matters because webhook handlers should not blindly trust incoming HTTP requests. The app verifies that the event really came from Telnyx before it updates call state.

Telnyx Call Control event
  -> POST /webhooks/call
  -> verify signature
  -> update campaign result

Tracking status

At any point, you can poll:

curl http://localhost:5000/campaign/<campaign_id>

The response includes total calls, completion status, and per-number results.

That gives you a simple campaign dashboard API without adding another database service just for the sample.

Closing the loop with SMS

When the campaign finishes, the app sends a summary SMS using Telnyx Messaging.

You configure:

TELNYX_SMS_FROM
TELNYX_SMS_TO

For a demo, this is a clean way to prove the workflow completed. In a production version, the same step could also notify Slack, update a CRM, or send a report to another internal system.

What I like about this pattern

The app is not trying to be a full campaign product.

It is showing the backend shape you need for one:

one API to start the work
an agent to manage queueing and pacing
Call Control for the voice workflow
signed webhooks for lifecycle updates
SQL for campaign state
SMS for completion notification

That is the useful part. It gives you the skeleton for a durable communications workflow without starting from a pile of disconnected services.

Run it yourself

Clone the repo:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/ai-call-campaign-orchestrator

Create a virtual environment and install dependencies:

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

Configure your environment:

cp .env.example .env

Then fill in your Telnyx API key, connection ID, phone number, webhook URL, public key, SMS settings, and call rate limit.

Run the app:

python app.py

Resources:

Code example: https://github.com/team-telnyx/telnyx-code-examples/tree/main/ai-call-campaign-orchestrator
Telnyx AI toolkit: https://github.com/team-telnyx/ai
Telnyx docs: https://developers.telnyx.com
Telnyx Portal: https://portal.telnyx.com