Build a Group MMS Delivery Tracker with TypeScript
A group message is sent once, but its outcome arrives one recipient at a time.
That distinction matters when a dispatcher sends job instructions to a field crew. The initial API response only confirms that the message was queued. Later, separate delivery webhooks report whether each recipient received it, failed, or still has an unknown status. Replies arrive through another webhook path.
Crew Cast turns those events into one durable delivery board. It sends a Group MMS, tracks every recipient, records replies as acknowledgements, and keeps the board available across worker restarts and deployments.
This tutorial walks through the architecture and the reliability patterns behind it.
What the sample builds
The application exposes four routes:
| Route | Purpose |
|---|---|
| POST /cast | Create or reopen a job actor and send the Group MMS |
| POST /webhooks/messaging | Verify and process Telnyx messaging webhooks |
| GET /board/:cast_id | Return the current delivery board |
| GET /board?cast_id=... | Query the same board by parameter |
The result is a per-recipient view of:
- delivery status
- carrier and line type, when returned by the API
- the time of the latest finalized event
- whether the recipient replied
- the reply history for the group
Telnyx Group Messaging supports up to eight recipients per conversation, uses MMS, and is limited to US and Canadian destinations. Inbound group messages require v2 webhooks on the Messaging Profile. The Group Messaging guide documents those constraints.
One Stateful Actor per job
Every cast is identified by a job_id. The router turns that stable identifier into the name of a CrewCast Stateful Actor:
const actorId = env.CREW_CAST.idFromName(jobId)
const actor = env.CREW_CAST.get(actorId)
This is the central design choice. Every webhook for that job is routed back to the same durable entity, so the roster, delivery states, and replies do not depend on one particular function process staying alive.
The actor owns state such as:
type CrewState = {
cast_id: string
group_message_id: string | null
recipients: RecipientState[]
replies: Reply[]
repolls: number
notified_signature: string | null
}
The process may restart. The actor identity and persisted state remain tied to the job.
Persist the roster before sending
The sample writes the recipient roster before it calls the Messaging API. That ordering protects the system from a failure between "message accepted" and "roster recorded."
The live send uses the pre-authenticated Telnyx binding:
const response = await this.env.TELNYX.messages.send({
from: crewFrom,
to: recipients,
text,
media_urls: mediaUrl ? [mediaUrl] : undefined,
})
The API response contains a message id and a to[] array. Crew Cast stores the id as group_message_id and uses the recipient objects to seed carrier, line type, and initial delivery status.
That ID is the correlation key for the asynchronous delivery events described in the Group MMS API reference.
Route webhooks with KV
The application needs to find the correct actor without scanning every active job. It writes two small routing records to KV:
group:<group_message_id> -> cast_id
thread:<crew_number> -> cast_id
When a message.finalized webhook arrives, the router looks up the cast by group_message_id. For an inbound message.received event, it can route the thread through the Telnyx number that received the reply.
KV is only the routing index. The full conversation state remains inside the actor, while SQL stores the reportable recipient rows.
Make delivery updates replay-safe
Messaging webhooks can be retried. Crew Cast treats each finalized event as an update to one logical record identified by:
(group_message_id, recipient_phone_number)
The actor checks the stored state before applying an update:
- If the incoming status matches the stored status, it is a duplicate.
- If the stored status is already hard-terminal, a stale update cannot move it backward.
- If the recipient is not on the roster, the event is acknowledged without changing the board.
- Valid later events can move a provisional unknown status to a final result.
No-op events still return HTTP 200. This prevents a harmless replay from becoming an endless retry loop.
unknown is also kept separate from delivery_failed. Unknown means the system does not yet have a definitive delivery result; it should not be presented as a confirmed failure.
Let replies acknowledge the job
Inbound group replies contain the sender plus a cc[] list of the other participants. Crew Cast folds the reply into the actor, deduplicates it by webhook ID, and marks the sender with an acked_at timestamp.
On the first reply, the actor can also use cc[] to backfill participants missing from its roster while excluding the thread owner number. This makes the group conversation itself an additional source of membership context.
Use SQL for the delivery summary
Actor state is ideal for owning one job, but the delivery board also needs aggregate answers. Crew Cast mirrors each recipient into a SQL table with a composite primary key:
PRIMARY KEY (cast_id, phone_number)
The report then uses a real aggregate query:
SELECT status, COUNT(*) AS count
FROM crew_delivery
WHERE cast_id = ?
GROUP BY status
This division of responsibility stays simple:
- Stateful Actor: authoritative lifecycle for one job
- KV: fast webhook-to-actor routing
- SQL: recipient rows and grouped reporting
Schedule a bounded follow-up
If recipients remain queued or unknown, the actor schedules a follow-up after 30 minutes:
await this.schedule(1800, "repollUnknown")
The scheduled method reviews the durable state and can schedule one more bounded check. It does not invent a delivery result or replace the carrier webhook. A later message.finalized event remains the source of truth.
Once no recipient remains queued, the actor sends a summary SMS to the configured dispatch number. A signature derived from the totals prevents the same summary from being sent repeatedly.
Run the sample in demo mode
Clone the repository and enter the example:
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/crew-cast
npm install
Create the local environment file and generate binding types:
cp .env.example .env
npx telnyx-edge types
Keep DEMO_MODE=true for the first run. Demo mode simulates the Group MMS send and accepts the included unsigned webhook fixtures, so you can exercise the state machine without sending a real message.
Run the smoke test:
npm run smoke
Deploy when the bindings and placeholder resources in telnyx.toml are configured for your account:
npm run deploy
Create a cast with your own authorized test destinations:
curl -X POST "$PUBLIC_BASE_URL/cast" \
-H "Content-Type: application/json" \
-d '{
"job_id": "job-demo",
"recipients": [
"<CREW_MEMBER_1_E164>",
"<CREW_MEMBER_2_E164>"
],
"text": "Job details are ready. Reply ACK when received.",
"media_url": "https://example.com/job-photo.jpg"
}'
Then inspect the board:
curl "$PUBLIC_BASE_URL/board/job-demo"
The repository includes demo webhook fixtures for testing finalized delivery events and replies without real phone numbers.
Switch to live messaging carefully
For live operation, configure:
- an MMS-capable Telnyx number for CREW_FROM
- a Messaging Profile with v2 webhooks for CREW_PROFILE_ID
- PUBLIC_BASE_URL/webhooks/messaging as the public webhook endpoint
- TELNYX_PUBLIC_KEY as a secret
- a valid dispatch destination
- DEMO_MODE=false
In live mode, the router verifies the Ed25519 signature against the raw request body and rejects timestamps outside a five-minute window. Unsigned webhooks are accepted only in demo mode.
Before using the sample in production, add authentication and authorization to /cast and /board, define data-retention rules, restrict who can view recipient information, and monitor webhook failures. A job_id is an actor identifier, not an access-control mechanism.
The reusable pattern
Crew Cast is a messaging example, but the pattern applies to any workflow where one command produces many asynchronous participant results:
1. Persist intent before triggering the external action.
2. Use the provider's correlation ID as the event join key.
3. Route every event to one durable entity.
4. Fold retries idempotently.
5. Keep provisional states distinct from confirmed failures.
6. Store aggregate-friendly rows separately from lifecycle state.
The complete TypeScript sample, fixtures, and deployment configuration are available in the Telnyx code examples repository.
Long SMS chunking and delivery tracking with Node.js
I built a small Node.js and Express example for sending long SMS messages through Telnyx:
github.com/team-telnyx/telnyx-code-examples/tree/…
Demo video: youtu.be
The use case is an appointment reminder that may need to include the appointment time, location, preparation instructions, accessibility details, and rescheduling options.
The sample sends one logical message longer than 1,530 characters. Telnyx handles the carrier-level chunking, while the application stores the parent message ID and correlates message.sent and message.finalized webhook events with the child message segments.
The code includes:
- Express endpoints for profile configuration and message sending
- Ed25519 webhook signature verification
- parent/child delivery correlation
- an in-memory delivery lookup endpoint
- a realistic appointment demo
- a separate --sequence mode that sends four readable appointment messages for a clean phone demo
Run it with:
git clone team-telnyx/telnyx-code-examples
cd telnyx-code-examples/long-sms-chunking-and-tracking-nodejs
npm install
npm start
Then use npm run demo for the long-message path or npm run demo -- --sequence for four independent messages.
The interesting design question is not whether several texts can be sent. It is whether the business workflow should treat them as one notification or four separate updates. This example shows both choices and makes the delivery model explicit.
1 point
I Built a Long SMS Demo That Keeps the Message Together
An appointment reminder looks simple until you write the complete version.
The time, address, check-in instructions, preparation checklist, accessibility details, and rescheduling instructions quickly become longer than one SMS segment. The obvious fallback is to send several separate texts. That works mechanically, but it makes the notification feel fragmented and gives the application several independent deliveries to reason about.
I built a small Node.js Telnyx example to explore the other option.
I recorded a short demo of the flow here: <youtu.be>
The application sends one logical long message. Telnyx handles the carrier-level chunking, and the application keeps a parent record that can collect the statuses of the child message segments.
What the code does
The server is an Express application using the Telnyx Node.js SDK. Its main send path is intentionally small:
- validate the destination number
- require a message longer than 1,530 characters for the long-message demo
- call the Telnyx Messages API once
- store the returned parent message ID
The webhook path handles the delivery side. It verifies the signed request, reads the child message ID and parent message ID, and updates the delivery record.
That parent-child relationship is the part I would reuse in a real application. An appointment system, logistics platform, or incident-notification service can keep one workflow ID while still retaining the underlying messaging events.
The demo has two honest modes
The long-message mode demonstrates automatic chunking. The phone may render the resulting segments as one combined message, depending on the carrier and device.
The recording uses a separate sequence mode. It sends four medium-length appointment messages so each paragraph appears as a distinct, readable bubble. Those are four independent SMS sends, not one carrier-chunked message.
Keeping those modes separate makes the example easier to understand. One shows infrastructure behavior; the other shows a practical notification design that may be better for a human recipient.
Where I would use it
This pattern fits appointment reminders, delivery instructions, outage notices, customer-support updates, billing notifications, and field-service dispatches. The decision is simple: if the content is one indivisible notification, use the long-message path; if each update should stand on its own, send a sequence.
The complete code and API reference are in the Telnyx code examples repository.
I Built a Bot That Attends Meetings I Can't Make, and I Control It by Text
Every calendar has a collision in it somewhere. Two meetings at the same time, a dentist appointment that ran long, a train with no signal for the first ten minutes of a standup.
The usual fix is an apology message and a request for notes afterward. I wanted something better: text a link, and a bot goes in my place.
I built a Node.js Telnyx code example that does exactly that. You send a meeting link to a Telnyx number. A bot joins the meeting, posts a note in the chat explaining who it is, takes notes, and texts you a TL;DR when the meeting ends.
The code example:
github.com/team-telnyx/telnyx-code-examples/tree/…
The video walkthrough:
youtu.be
The Use Case
The interaction is a single text:
I can't join this meeting: https://meet.google.com/abc-defg-hij.
Join as my bot, and send me a TL;DR when it ends.
A moment later a reply arrives:
On it. Your bot is joining now. I will text you when it is in
and send a TL;DR after the meeting.
In the meeting, a new participant appears with the bot's name and posts a chat message telling everyone it is taking notes on someone's behalf. When the meeting ends, a second text arrives with the summary.
The phone is the interface because it is the one thing you have when you cannot get to a laptop.
What The Example Uses
The example runs as a small Express server and uses two Telnyx products with one API key:
- Telnyx Messaging to receive the inbound text and send the replies
- Telnyx Meeting Bot to join the call, capture the transcript, and generate a summary
- Telnyx webhooks with Ed25519 signatures to authenticate inbound messages
There is no separate transcription service and no separate summarization step in the code. The session is created with summarize_on_end: true, and Telnyx produces a summary artifact when the meeting is over.
Keeping It Safe
A bot you can summon by text is also a bot someone else might try to summon, so the example has two guards.
First, the webhook verifies the Telnyx signature over the raw request body. A request that does not carry a valid signature gets a 401 and nothing else happens.
Second, the handler only acts on texts from one configured number, the owner's mobile. Messages from anyone else are ignored.
if (from !== OWNER_PHONE_NUMBER) {
return;
}
That is enough for a personal tool. It is not an access-control system, and a team version would need real per-user rules.
Sending The Bot In
The core of the example is one API call:
await client.meetingSessions.create({
meeting_url: meetingUrl,
bot_name: BOT_NAME,
chat_on_enter: CHAT_ON_ENTER,
summarize_on_end: true,
idempotency_key: `join-meeting-by-sms:${messageId}`,
});
The idempotency_key solves a quiet problem. Telnyx retries webhooks that do not get a quick success response, and a retry must not put a second bot in the meeting. Because the key comes from the inbound message ID, a replayed message resolves to the session that already exists.
The chat_on_enter message matters for a human reason. A silent unknown participant is unsettling. A bot that introduces itself is a much better guest.
Telling You What Is Happening
Joining a meeting is not instant. A host may need to admit the bot from a waiting room, and a host may decline. The server polls the session every few seconds and texts you on each change:
waiting_for_admission -> a host needs to admit your bot
active -> your bot is in and taking notes
admission_denied -> the host did not admit your bot
failed -> your bot could not join
Each status is texted once, so you are not flooded while waiting.
Getting The TL;DR
When the session ends, the server asks for the session's artifacts and picks out the one with type summary. Summary generation is asynchronous, so the server waits for it to complete, up to ninety seconds, then texts it to you.
If the summary is not available, you get a clear fallback message. A silent failure would be worse than an honest one.
Optional Extras
Two environment variables make the bot feel more like a participant:
- ASSISTANT_ID attaches a Telnyx AI Assistant so the bot can speak and answer questions in the meeting
- CAMERA_IMAGE_URL sets a static image as the bot's camera tile
Running The Example
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/join-meeting-by-sms-nodejs
cp .env.example .env
npm install
npm start
Add your API key, public key, Telnyx number, and your own mobile number to .env. Expose the server with a tunnel, point your Messaging Profile's inbound webhook at /webhooks/sms, and text your number a link.
This puts a real bot in a real meeting and sends real SMS, so try it on a meeting you control first.
What I Would Change For Production
This is a pattern, not a product. Before using it for real I would:
- Store watched session IDs in a database so a restart does not drop the status texts
- Always disclose the bot in chat, because people deserve to know when a meeting is being summarized
- Register the sending number for US SMS with 10DLC or toll-free verification
- Replace the single owner number with per-user rules
- Plan for meeting platforms where chat is not supported
Frequently Asked Questions
Which meeting platforms work?
The example recognizes Google Meet, Zoom, Microsoft Teams, and Webex links.
Can the bot talk?
Yes, if you attach a Telnyx AI Assistant with ASSISTANT_ID.
What if the host never admits the bot?
You get a text saying the bot is at the waiting room, and another if the host denies admission.
Can someone else text the bot into a meeting?
No. Only the configured owner number is accepted, and webhooks without a valid Telnyx signature are rejected.
First comment
Demo video: youtu.be
Code: github.com/team-telnyx/telnyx-code-examples/tree/…
I Built a Voice Fraud Step-Up Workflow with Telnyx
A caller can know the right account details, tell a convincing story, and sound exactly like the person they are pretending to be.
That makes voice a useful interaction channel, but a weak standalone identity factor for sensitive actions.
I built a TypeScript Telnyx code example that treats voice authenticity as one risk signal in a larger fraud workflow. The example protects a high-risk support request, such as a wire transfer, and chooses between proceeding, requiring a flashcall step-up, or routing the request to manual review.
The code example:
github.com/team-telnyx/telnyx-code-examples/tree/…
The video walkthrough:
youtu.be
The Use Case
Imagine a customer calls a support line and asks to send $2,500 to an external account.
A simple voice workflow might ask the caller a question, accept a positive answer, and continue. That is not enough for a high-risk action. A fraudster can use a cloned voice, and a human-sounding voice still does not prove account ownership.
The safer workflow starts by opening a risk gate:
support request
-> blocked pending
-> voice-authenticity check
-> policy decision
-> proceed, step up, or human review
The gate is intentionally separate from the final business action. It determines what verification should happen next. It does not claim that the caller has been fully authenticated.
That separation also makes the demo easier to reason about. The caller experiences a normal phone interaction, while the application keeps the security decision in structured state. Support teams can see whether the request passed the voice screen, required a challenge, or needs a person to review it.
What The Example Uses
The sample runs on Telnyx Edge Compute and uses:
- Telnyx Call Control to place the outbound call
- Telnyx Deepfake Detection to classify the remote-party audio
- Telnyx webhooks to deliver the result
- Embedded SQL storage for the per-account audit ledger
- Telnyx Verify flashcall as an optional step-up
- Call Control speech for deterministic prompts and verdicts
The live path does not start an autonomous AI Assistant after detection. That choice is deliberate. The policy result should come from code and stored state, not from a model improvising a message to the caller.
Opening The Risk Gate
The actor receives a sensitive action such as a wire transfer request and records the initial state:
blocked_pending — request opened
That state is intentional. The request does not begin in an approved state while the phone call is still waiting for a result.
Enabling Deepfake Detection
The outbound Call Control request includes Deepfake Detection:
deepfake_detection: {
enabled: true,
timeout: 30,
}
The request also carries client state containing the account ID. When the webhook arrives, the Edge function decodes that state and routes the result to the correct account actor.
The call continues while the detection service evaluates the remote-party audio. The caller hears a short verification prompt through Call Control speech:
This call includes a voice-authenticity screen, not identity verification.
Please state your name and confirm whether you requested the two thousand five
hundred dollar wire transfer on this account.
The wording is intentionally explicit. The caller is told that the call is checking voice authenticity, not proving account ownership.
Applying The Result
Telnyx sends a result such as:
real
fake
silence_timeout
The policy combines that result with recent ledger history.
A clean real result returns:
proceed
That means the voice-authenticity policy passed and the workflow can continue to an independent identity factor.
A fake result returns a flashcall step-up when the Verify profile is configured. A recent risky ledger event can also force the step-up even if the latest audio appears human.
A silence_timeout or provider error returns manual review. The workflow fails closed when the signal is missing or inconclusive.
The resulting ledger is easy to inspect:
blocked_pending — request opened
proceed — human-sounding voice result and clean recent ledger
The word proceed is not the same as identity verified. It means the policy has allowed the next stage.
Why The Ledger Matters
A fraud decision should be explainable after the call ends.
The actor stores request and outcome rows in embedded SQL. That provides a durable audit trail for questions such as:
- Which account opened the request?
- Which call produced the result?
- Was the result real, fake, or inconclusive?
- Was there a recent risky event?
- Did the workflow proceed, step up, or go to review?
This also gives the application memory across restarts. A later request can see that the account had a recent risky event and require another factor instead of evaluating the newest call in isolation.
Deterministic Call Messages
The sample originally used an assistant to deliver the post-detection result. The live path now uses Call Control speech instead.
That is a small but important reliability decision. The code chooses the exact message from the policy outcome:
proceed
-> the voice passed the synthetic-voice screen
step_up_flashcall
-> additional verification is required
manual_review
-> a specialist will review the request
The caller hears the same outcome that appears in the ledger. There is no second autonomous decision layer between the policy and the message.
Running The Example
Start with local validation:
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/voice-fraud-step-up-agent
npm install
cp .env.example .env
npm run typecheck
npm run smoke
The smoke test exercises the policy locally and does not place a call or send a verification message.
For a live run, configure the Edge secrets and target a phone you control:
npm run demo:live
The local monitor prints the Call Control payload with the target number masked. The API key remains in the deployed Edge function.
Production Boundaries
This sample is a policy pattern, not a complete identity system.
A production implementation should:
- Add an independent identity factor before completing a sensitive action
- Limit repeated attempts and step-up retries
- Retain ledger data according to the organization’s security policy
- Avoid putting secrets or full phone numbers in logs
- Route uncertain detection results to trained reviewers
- Add account-level velocity and transaction-risk signals
- Keep the voice-authenticity result separate from authorization
The most important boundary is simple: a human-sounding voice is not proof of account ownership.
Frequently Asked Questions
Does a real Deepfake Detection result verify the caller?
No. It means the audio appeared human to the detector. The application still needs an independent identity factor.
What happens when the result is fake?
The policy can trigger a Telnyx Verify flashcall step-up when a Verify profile is configured.
What happens when detection times out?
The sample fails closed to manual review instead of allowing the sensitive action.
Why use a durable Edge actor?
The actor gives each account a place to store its pending action, recent risk history, and audit ledger so the next request can use that context.
Does the live call use an AI Assistant?
No. The live path uses deterministic Call Control speech for the prompt and final verdict.
Resources
- Code example: github.com/team-telnyx/telnyx-code-examples/tree/…
- Video walkthrough: youtu.be
- Deepfake Detection: telnyx.com
- Verify API: telnyx.com
- Stateful Edge Functions: telnyx.com
- Embedded SQL for Edge Functions: telnyx.com
2 comments
Pipecat agents now run on Telnyx Edge.
telnyx-edge ship, connect a number, call it.
Phone number, call audio, Flux STT, LLM inference and TTS on one platform, with one API key. Runs anywhere Edge runs.
team-telnyx/pipecat-edge t.co
2 likes · 1 repost · 141 views
built a Python workflow for provisioning and warming up a dedicated email IP
I have been working on a Python/Flask sample that turns dedicated email infrastructure into a reproducible API workflow instead of a sequence of portal steps.
The application:
- Purchases a dedicated sending IP with an idempotency key
- Starts the IP warm-up lifecycle
- Polls until warm-up is active and DNS is confirmed
- Creates a default IP pool
- Adds the dedicated IP to that pool
- Queues a test email to verify the configured sending path
A few implementation details were more interesting than I expected.
The provisioning state lives on the API, so if the application restarts during warm-up, it can query the IP and continue from the real server-side state. Starting warm-up twice is rejected, and unavailable regional inventory is surfaced instead of being retried indefinitely.
The current Python SDK does not expose dedicated-IP or IP-pool resources, so the provisioning calls use `requests`. The final email send uses the SDK.
The sample runs with `DEMO_MODE=true` by default. That simulates the complete sequence without purchasing an IP or sending an email. Live mode must be enabled explicitly.
Code: github.com/team-telnyx/telnyx-code-examples/tree/…
For anyone managing dedicated sending infrastructure: do you orchestrate IP warm-up with polling like this, scheduled jobs, or provider callbacks?
1 point
I built an AI gateway fallback demo that proves which model actually served the request
Most LLM fallback demos stop after receiving a successful response. That does not tell you whether the primary recovered, the fallback answered, or an SDK retry hid the original failure.
I built an open-source Python example that makes the entire failover path observable.
It:
- Provisions a Telnyx AI Gateway token group with Kimi K3 as the primary and GLM-5.3-Flash as the fallback
- Keeps retries and fallback policy in the gateway instead of duplicating them in application code
- Sets the OpenAI client to `max_retries=0`
- Uses a heavy streaming request and a one-second timeout to exercise the fallback path
- Reads `x-ltg-served-model` and `x-ltg-attempts` from the response
- Confirms the result independently through the spend ledger
- Tracks the requested model, serving model, attempts, status, and cache result
- Uses ETags and idempotency keys when changing or deleting gateway resources
The induced failure is intentionally treated as a latency race. The script retries the demonstration up to three times and reports honestly when the fallback does not fire.
Code: github.com/team-telnyx/telnyx-code-examples/tree/…
I would be interested to hear how others handle model failover today: inside the application, through a gateway, or through provider-specific routing?
2 points · 2 comments
AI Support Agent That Carries Context Between Email and WhatsApp (Python)
2 points
I built a self-refreshing company handbook assistant with durable state
I’ve been exploring what happens when a RAG demo has to keep working after the first successful query.
This TypeScript sample creates one durable Stateful Actor per company. Each actor:
- Embeds a handbook URL into Telnyx Storage
- Polls asynchronous indexing jobs and retries failures
- Searches the handbook before generating an answer
- Refuses to answer when the retrieval match is weak
- Records every Q&A in an embedded SQL audit log
- Reindexes the handbook automatically each night
The interesting part isn’t really the chatbot. It’s giving the entire retrieval lifecycle a durable owner: source state, indexing progress, retries, scheduled refreshes, and answer history all stay with the company’s actor.
The sample uses Telnyx Edge Compute, Stateful Actors, Embeddings, Storage, and AI Inference.
Code: github.com/team-telnyx/telnyx-code-examples/tree/…
The public routes are intentionally unauthenticated for the demo, so production use would need authorization, retention rules, evaluations for the similarity threshold, and better observability.
I’d be interested in feedback on the actor-per-tenant approach, especially from anyone maintaining frequently changing internal knowledge bases.
3 points · 4 comments
Mentions
Build a Group MMS Delivery Tracker with TypeScript A group message is sent once, but its outcome arrives one recipient at a time. That distinction matters when a dispatcher sends job instructions to a field crew. The initial API response only confirms that the message was queued. Later, separate delivery webhooks report whether each recipient received it, failed, or still has an unknown status. Replies arrive through another webhook path. Crew Cast turns those events into one durable delivery board. It sends a Group MMS, tracks every recipient, records replies as acknowledgements, and keeps the board available across worker restarts and deployments. This tutorial walks through the architecture and the reliability patterns behind it. What the sample builds The application exposes four routes: | Route | Purpose | |---|---| | POST /cast | Create or reopen a job actor and send the Group MMS | | POST /webhooks/messaging | Verify and process Telnyx messaging webhooks | | GET /board/:cast_id | Return the current delivery board | | GET /board?cast_id=... | Query the same board by parameter | The result is a per-recipient view of: - delivery status - carrier and line type, when returned by the API - the time of the latest finalized event - whether the recipient replied - the reply history for the group Telnyx Group Messaging supports up to eight recipients per conversation, uses MMS, and is limited to US and Canadian destinations. Inbound group messages require v2 webhooks on the Messaging Profile. The Group Messaging guide documents those constraints. One Stateful Actor per job Every cast is identified by a job_id. The router turns that stable identifier into the name of a CrewCast Stateful Actor: const actorId = env.CREW_CAST.idFromName(jobId) const actor = env.CREW_CAST.get(actorId) This is the central design choice. Every webhook for that job is routed back to the same durable entity, so the roster, delivery states, and replies do not depend on one particular function process staying alive. The actor owns state such as: type CrewState = { cast_id: string group_message_id: string | null recipients: RecipientState[] replies: Reply[] repolls: number notified_signature: string | null } The process may restart. The actor identity and persisted state remain tied to the job. Persist the roster before sending The sample writes the recipient roster before it calls the Messaging API. That ordering protects the system from a failure between "message accepted" and "roster recorded." The live send uses the pre-authenticated Telnyx binding: const response = await this.env.TELNYX.messages.send({ from: crewFrom, to: recipients, text, media_urls: mediaUrl ? [mediaUrl] : undefined, }) The API response contains a message id and a to[] array. Crew Cast stores the id as group_message_id and uses the recipient objects to seed carrier, line type, and initial delivery status. That ID is the correlation key for the asynchronous delivery events described in the Group MMS API reference. Route webhooks with KV The application needs to find the correct actor without scanning every active job. It writes two small routing records to KV: group:<group_message_id> -> cast_id thread:<crew_number> -> cast_id When a message.finalized webhook arrives, the router looks up the cast by group_message_id. For an inbound message.received event, it can route the thread through the Telnyx number that received the reply. KV is only the routing index. The full conversation state remains inside the actor, while SQL stores the reportable recipient rows. Make delivery updates replay-safe Messaging webhooks can be retried. Crew Cast treats each finalized event as an update to one logical record identified by: (group_message_id, recipient_phone_number) The actor checks the stored state before applying an update: - If the incoming status matches the stored status, it is a duplicate. - If the stored status is already hard-terminal, a stale update cannot move it backward. - If the recipient is not on the roster, the event is acknowledged without changing the board. - Valid later events can move a provisional unknown status to a final result. No-op events still return HTTP 200. This prevents a harmless replay from becoming an endless retry loop. unknown is also kept separate from delivery_failed. Unknown means the system does not yet have a definitive delivery result; it should not be presented as a confirmed failure. Let replies acknowledge the job Inbound group replies contain the sender plus a cc[] list of the other participants. Crew Cast folds the reply into the actor, deduplicates it by webhook ID, and marks the sender with an acked_at timestamp. On the first reply, the actor can also use cc[] to backfill participants missing from its roster while excluding the thread owner number. This makes the group conversation itself an additional source of membership context. Use SQL for the delivery summary Actor state is ideal for owning one job, but the delivery board also needs aggregate answers. Crew Cast mirrors each recipient into a SQL table with a composite primary key: PRIMARY KEY (cast_id, phone_number) The report then uses a real aggregate query: SELECT status, COUNT(*) AS count FROM crew_delivery WHERE cast_id = ? GROUP BY status This division of responsibility stays simple: - Stateful Actor: authoritative lifecycle for one job - KV: fast webhook-to-actor routing - SQL: recipient rows and grouped reporting Schedule a bounded follow-up If recipients remain queued or unknown, the actor schedules a follow-up after 30 minutes: await this.schedule(1800, "repollUnknown") The scheduled method reviews the durable state and can schedule one more bounded check. It does not invent a delivery result or replace the carrier webhook. A later message.finalized event remains the source of truth. Once no recipient remains queued, the actor sends a summary SMS to the configured dispatch number. A signature derived from the totals prevents the same summary from being sent repeatedly. Run the sample in demo mode Clone the repository and enter the example: git clone https://github.com/team-telnyx/telnyx-code-examples.git cd telnyx-code-examples/crew-cast npm install Create the local environment file and generate binding types: cp .env.example .env npx telnyx-edge types Keep DEMO_MODE=true for the first run. Demo mode simulates the Group MMS send and accepts the included unsigned webhook fixtures, so you can exercise the state machine without sending a real message. Run the smoke test: npm run smoke Deploy when the bindings and placeholder resources in telnyx.toml are configured for your account: npm run deploy Create a cast with your own authorized test destinations: curl -X POST "$PUBLIC_BASE_URL/cast" \ -H "Content-Type: application/json" \ -d '{ "job_id": "job-demo", "recipients": [ "<CREW_MEMBER_1_E164>", "<CREW_MEMBER_2_E164>" ], "text": "Job details are ready. Reply ACK when received.", "media_url": "https://example.com/job-photo.jpg" }' Then inspect the board: curl "$PUBLIC_BASE_URL/board/job-demo" The repository includes demo webhook fixtures for testing finalized delivery events and replies without real phone numbers. Switch to live messaging carefully For live operation, configure: - an MMS-capable Telnyx number for CREW_FROM - a Messaging Profile with v2 webhooks for CREW_PROFILE_ID - PUBLIC_BASE_URL/webhooks/messaging as the public webhook endpoint - TELNYX_PUBLIC_KEY as a secret - a valid dispatch destination - DEMO_MODE=false In live mode, the router verifies the Ed25519 signature against the raw request body and rejects timestamps outside a five-minute window. Unsigned webhooks are accepted only in demo mode. Before using the sample in production, add authentication and authorization to /cast and /board, define data-retention rules, restrict who can view recipient information, and monitor webhook failures. A job_id is an actor identifier, not an access-control mechanism. The reusable pattern Crew Cast is a messaging example, but the pattern applies to any workflow where one command produces many asynchronous participant results: 1. Persist intent before triggering the external action. 2. Use the provider's correlation ID as the event join key. 3. Route every event to one durable entity. 4. Fold retries idempotently. 5. Keep provisional states distinct from confirmed failures. 6. Store aggregate-friendly rows separately from lifecycle state. The complete TypeScript sample, fixtures, and deployment configuration are available in the Telnyx code examples repository.
Long SMS chunking and delivery tracking with Node.js I built a small Node.js and Express example for sending long SMS messages through Telnyx: github.com/team-telnyx/telnyx-code-examples/tree/… Demo video: youtu.be The use case is an appointment reminder that may need to include the appointment time, location, preparation instructions, accessibility details, and rescheduling options. The sample sends one logical message longer than 1,530 characters. Telnyx handles the carrier-level chunking, while the application stores the parent message ID and correlates message.sent and message.finalized webhook events with the child message segments. The code includes: - Express endpoints for profile configuration and message sending - Ed25519 webhook signature verification - parent/child delivery correlation - an in-memory delivery lookup endpoint - a realistic appointment demo - a separate --sequence mode that sends four readable appointment messages for a clean phone demo Run it with: git clone team-telnyx/telnyx-code-examples cd telnyx-code-examples/long-sms-chunking-and-tracking-nodejs npm install npm start Then use npm run demo for the long-message path or npm run demo -- --sequence for four independent messages. The interesting design question is not whether several texts can be sent. It is whether the business workflow should treat them as one notification or four separate updates. This example shows both choices and makes the delivery model explicit.
I Built a Long SMS Demo That Keeps the Message Together An appointment reminder looks simple until you write the complete version. The time, address, check-in instructions, preparation checklist, accessibility details, and rescheduling instructions quickly become longer than one SMS segment. The obvious fallback is to send several separate texts. That works mechanically, but it makes the notification feel fragmented and gives the application several independent deliveries to reason about. I built a small Node.js Telnyx example to explore the other option. I recorded a short demo of the flow here: <youtu.be> The application sends one logical long message. Telnyx handles the carrier-level chunking, and the application keeps a parent record that can collect the statuses of the child message segments. What the code does The server is an Express application using the Telnyx Node.js SDK. Its main send path is intentionally small: - validate the destination number - require a message longer than 1,530 characters for the long-message demo - call the Telnyx Messages API once - store the returned parent message ID The webhook path handles the delivery side. It verifies the signed request, reads the child message ID and parent message ID, and updates the delivery record. That parent-child relationship is the part I would reuse in a real application. An appointment system, logistics platform, or incident-notification service can keep one workflow ID while still retaining the underlying messaging events. The demo has two honest modes The long-message mode demonstrates automatic chunking. The phone may render the resulting segments as one combined message, depending on the carrier and device. The recording uses a separate sequence mode. It sends four medium-length appointment messages so each paragraph appears as a distinct, readable bubble. Those are four independent SMS sends, not one carrier-chunked message. Keeping those modes separate makes the example easier to understand. One shows infrastructure behavior; the other shows a practical notification design that may be better for a human recipient. Where I would use it This pattern fits appointment reminders, delivery instructions, outage notices, customer-support updates, billing notifications, and field-service dispatches. The decision is simple: if the content is one indivisible notification, use the long-message path; if each update should stand on its own, send a sequence. The complete code and API reference are in the Telnyx code examples repository.
I Built a Bot That Attends Meetings I Can't Make, and I Control It by Text Every calendar has a collision in it somewhere. Two meetings at the same time, a dentist appointment that ran long, a train with no signal for the first ten minutes of a standup. The usual fix is an apology message and a request for notes afterward. I wanted something better: text a link, and a bot goes in my place. I built a Node.js Telnyx code example that does exactly that. You send a meeting link to a Telnyx number. A bot joins the meeting, posts a note in the chat explaining who it is, takes notes, and texts you a TL;DR when the meeting ends. The code example: github.com/team-telnyx/telnyx-code-examples/tree/… The video walkthrough: youtu.be The Use Case The interaction is a single text: I can't join this meeting: https://meet.google.com/abc-defg-hij. Join as my bot, and send me a TL;DR when it ends. A moment later a reply arrives: On it. Your bot is joining now. I will text you when it is in and send a TL;DR after the meeting. In the meeting, a new participant appears with the bot's name and posts a chat message telling everyone it is taking notes on someone's behalf. When the meeting ends, a second text arrives with the summary. The phone is the interface because it is the one thing you have when you cannot get to a laptop. What The Example Uses The example runs as a small Express server and uses two Telnyx products with one API key: - Telnyx Messaging to receive the inbound text and send the replies - Telnyx Meeting Bot to join the call, capture the transcript, and generate a summary - Telnyx webhooks with Ed25519 signatures to authenticate inbound messages There is no separate transcription service and no separate summarization step in the code. The session is created with summarize_on_end: true, and Telnyx produces a summary artifact when the meeting is over. Keeping It Safe A bot you can summon by text is also a bot someone else might try to summon, so the example has two guards. First, the webhook verifies the Telnyx signature over the raw request body. A request that does not carry a valid signature gets a 401 and nothing else happens. Second, the handler only acts on texts from one configured number, the owner's mobile. Messages from anyone else are ignored. if (from !== OWNER_PHONE_NUMBER) { return; } That is enough for a personal tool. It is not an access-control system, and a team version would need real per-user rules. Sending The Bot In The core of the example is one API call: await client.meetingSessions.create({ meeting_url: meetingUrl, bot_name: BOT_NAME, chat_on_enter: CHAT_ON_ENTER, summarize_on_end: true, idempotency_key: `join-meeting-by-sms:${messageId}`, }); The idempotency_key solves a quiet problem. Telnyx retries webhooks that do not get a quick success response, and a retry must not put a second bot in the meeting. Because the key comes from the inbound message ID, a replayed message resolves to the session that already exists. The chat_on_enter message matters for a human reason. A silent unknown participant is unsettling. A bot that introduces itself is a much better guest. Telling You What Is Happening Joining a meeting is not instant. A host may need to admit the bot from a waiting room, and a host may decline. The server polls the session every few seconds and texts you on each change: waiting_for_admission -> a host needs to admit your bot active -> your bot is in and taking notes admission_denied -> the host did not admit your bot failed -> your bot could not join Each status is texted once, so you are not flooded while waiting. Getting The TL;DR When the session ends, the server asks for the session's artifacts and picks out the one with type summary. Summary generation is asynchronous, so the server waits for it to complete, up to ninety seconds, then texts it to you. If the summary is not available, you get a clear fallback message. A silent failure would be worse than an honest one. Optional Extras Two environment variables make the bot feel more like a participant: - ASSISTANT_ID attaches a Telnyx AI Assistant so the bot can speak and answer questions in the meeting - CAMERA_IMAGE_URL sets a static image as the bot's camera tile Running The Example git clone https://github.com/team-telnyx/telnyx-code-examples.git cd telnyx-code-examples/join-meeting-by-sms-nodejs cp .env.example .env npm install npm start Add your API key, public key, Telnyx number, and your own mobile number to .env. Expose the server with a tunnel, point your Messaging Profile's inbound webhook at /webhooks/sms, and text your number a link. This puts a real bot in a real meeting and sends real SMS, so try it on a meeting you control first. What I Would Change For Production This is a pattern, not a product. Before using it for real I would: - Store watched session IDs in a database so a restart does not drop the status texts - Always disclose the bot in chat, because people deserve to know when a meeting is being summarized - Register the sending number for US SMS with 10DLC or toll-free verification - Replace the single owner number with per-user rules - Plan for meeting platforms where chat is not supported Frequently Asked Questions Which meeting platforms work? The example recognizes Google Meet, Zoom, Microsoft Teams, and Webex links. Can the bot talk? Yes, if you attach a Telnyx AI Assistant with ASSISTANT_ID. What if the host never admits the bot? You get a text saying the bot is at the waiting room, and another if the host denies admission. Can someone else text the bot into a meeting? No. Only the configured owner number is accepted, and webhooks without a valid Telnyx signature are rejected. First comment Demo video: youtu.be Code: github.com/team-telnyx/telnyx-code-examples/tree/…
I Built a Voice Fraud Step-Up Workflow with Telnyx A caller can know the right account details, tell a convincing story, and sound exactly like the person they are pretending to be. That makes voice a useful interaction channel, but a weak standalone identity factor for sensitive actions. I built a TypeScript Telnyx code example that treats voice authenticity as one risk signal in a larger fraud workflow. The example protects a high-risk support request, such as a wire transfer, and chooses between proceeding, requiring a flashcall step-up, or routing the request to manual review. The code example: github.com/team-telnyx/telnyx-code-examples/tree/… The video walkthrough: youtu.be The Use Case Imagine a customer calls a support line and asks to send $2,500 to an external account. A simple voice workflow might ask the caller a question, accept a positive answer, and continue. That is not enough for a high-risk action. A fraudster can use a cloned voice, and a human-sounding voice still does not prove account ownership. The safer workflow starts by opening a risk gate: support request -> blocked pending -> voice-authenticity check -> policy decision -> proceed, step up, or human review The gate is intentionally separate from the final business action. It determines what verification should happen next. It does not claim that the caller has been fully authenticated. That separation also makes the demo easier to reason about. The caller experiences a normal phone interaction, while the application keeps the security decision in structured state. Support teams can see whether the request passed the voice screen, required a challenge, or needs a person to review it. What The Example Uses The sample runs on Telnyx Edge Compute and uses: - Telnyx Call Control to place the outbound call - Telnyx Deepfake Detection to classify the remote-party audio - Telnyx webhooks to deliver the result - Embedded SQL storage for the per-account audit ledger - Telnyx Verify flashcall as an optional step-up - Call Control speech for deterministic prompts and verdicts The live path does not start an autonomous AI Assistant after detection. That choice is deliberate. The policy result should come from code and stored state, not from a model improvising a message to the caller. Opening The Risk Gate The actor receives a sensitive action such as a wire transfer request and records the initial state: blocked_pending — request opened That state is intentional. The request does not begin in an approved state while the phone call is still waiting for a result. Enabling Deepfake Detection The outbound Call Control request includes Deepfake Detection: deepfake_detection: { enabled: true, timeout: 30, } The request also carries client state containing the account ID. When the webhook arrives, the Edge function decodes that state and routes the result to the correct account actor. The call continues while the detection service evaluates the remote-party audio. The caller hears a short verification prompt through Call Control speech: This call includes a voice-authenticity screen, not identity verification. Please state your name and confirm whether you requested the two thousand five hundred dollar wire transfer on this account. The wording is intentionally explicit. The caller is told that the call is checking voice authenticity, not proving account ownership. Applying The Result Telnyx sends a result such as: real fake silence_timeout The policy combines that result with recent ledger history. A clean real result returns: proceed That means the voice-authenticity policy passed and the workflow can continue to an independent identity factor. A fake result returns a flashcall step-up when the Verify profile is configured. A recent risky ledger event can also force the step-up even if the latest audio appears human. A silence_timeout or provider error returns manual review. The workflow fails closed when the signal is missing or inconclusive. The resulting ledger is easy to inspect: blocked_pending — request opened proceed — human-sounding voice result and clean recent ledger The word proceed is not the same as identity verified. It means the policy has allowed the next stage. Why The Ledger Matters A fraud decision should be explainable after the call ends. The actor stores request and outcome rows in embedded SQL. That provides a durable audit trail for questions such as: - Which account opened the request? - Which call produced the result? - Was the result real, fake, or inconclusive? - Was there a recent risky event? - Did the workflow proceed, step up, or go to review? This also gives the application memory across restarts. A later request can see that the account had a recent risky event and require another factor instead of evaluating the newest call in isolation. Deterministic Call Messages The sample originally used an assistant to deliver the post-detection result. The live path now uses Call Control speech instead. That is a small but important reliability decision. The code chooses the exact message from the policy outcome: proceed -> the voice passed the synthetic-voice screen step_up_flashcall -> additional verification is required manual_review -> a specialist will review the request The caller hears the same outcome that appears in the ledger. There is no second autonomous decision layer between the policy and the message. Running The Example Start with local validation: git clone https://github.com/team-telnyx/telnyx-code-examples.git cd telnyx-code-examples/voice-fraud-step-up-agent npm install cp .env.example .env npm run typecheck npm run smoke The smoke test exercises the policy locally and does not place a call or send a verification message. For a live run, configure the Edge secrets and target a phone you control: npm run demo:live The local monitor prints the Call Control payload with the target number masked. The API key remains in the deployed Edge function. Production Boundaries This sample is a policy pattern, not a complete identity system. A production implementation should: - Add an independent identity factor before completing a sensitive action - Limit repeated attempts and step-up retries - Retain ledger data according to the organization’s security policy - Avoid putting secrets or full phone numbers in logs - Route uncertain detection results to trained reviewers - Add account-level velocity and transaction-risk signals - Keep the voice-authenticity result separate from authorization The most important boundary is simple: a human-sounding voice is not proof of account ownership. Frequently Asked Questions Does a real Deepfake Detection result verify the caller? No. It means the audio appeared human to the detector. The application still needs an independent identity factor. What happens when the result is fake? The policy can trigger a Telnyx Verify flashcall step-up when a Verify profile is configured. What happens when detection times out? The sample fails closed to manual review instead of allowing the sensitive action. Why use a durable Edge actor? The actor gives each account a place to store its pending action, recent risk history, and audit ledger so the next request can use that context. Does the live call use an AI Assistant? No. The live path uses deterministic Call Control speech for the prompt and final verdict. Resources - Code example: github.com/team-telnyx/telnyx-code-examples/tree/… - Video walkthrough: youtu.be - Deepfake Detection: telnyx.com - Verify API: telnyx.com - Stateful Edge Functions: telnyx.com - Embedded SQL for Edge Functions: telnyx.com
Pipecat agents now run on Telnyx Edge. telnyx-edge ship, connect a number, call it. Phone number, call audio, Flux STT, LLM inference and TTS on one platform, with one API key. Runs anywhere Edge runs. team-telnyx/pipecat-edge t.co
built a Python workflow for provisioning and warming up a dedicated email IP I have been working on a Python/Flask sample that turns dedicated email infrastructure into a reproducible API workflow instead of a sequence of portal steps. The application: - Purchases a dedicated sending IP with an idempotency key - Starts the IP warm-up lifecycle - Polls until warm-up is active and DNS is confirmed - Creates a default IP pool - Adds the dedicated IP to that pool - Queues a test email to verify the configured sending path A few implementation details were more interesting than I expected. The provisioning state lives on the API, so if the application restarts during warm-up, it can query the IP and continue from the real server-side state. Starting warm-up twice is rejected, and unavailable regional inventory is surfaced instead of being retried indefinitely. The current Python SDK does not expose dedicated-IP or IP-pool resources, so the provisioning calls use `requests`. The final email send uses the SDK. The sample runs with `DEMO_MODE=true` by default. That simulates the complete sequence without purchasing an IP or sending an email. Live mode must be enabled explicitly. Code: github.com/team-telnyx/telnyx-code-examples/tree/… For anyone managing dedicated sending infrastructure: do you orchestrate IP warm-up with polling like this, scheduled jobs, or provider callbacks?
I built an AI gateway fallback demo that proves which model actually served the request Most LLM fallback demos stop after receiving a successful response. That does not tell you whether the primary recovered, the fallback answered, or an SDK retry hid the original failure. I built an open-source Python example that makes the entire failover path observable. It: - Provisions a Telnyx AI Gateway token group with Kimi K3 as the primary and GLM-5.3-Flash as the fallback - Keeps retries and fallback policy in the gateway instead of duplicating them in application code - Sets the OpenAI client to `max_retries=0` - Uses a heavy streaming request and a one-second timeout to exercise the fallback path - Reads `x-ltg-served-model` and `x-ltg-attempts` from the response - Confirms the result independently through the spend ledger - Tracks the requested model, serving model, attempts, status, and cache result - Uses ETags and idempotency keys when changing or deleting gateway resources The induced failure is intentionally treated as a latency race. The script retries the demonstration up to three times and reports honestly when the fallback does not fire. Code: github.com/team-telnyx/telnyx-code-examples/tree/… I would be interested to hear how others handle model failover today: inside the application, through a gateway, or through provider-specific routing?
AI Support Agent That Carries Context Between Email and WhatsApp (Python)
I built a self-refreshing company handbook assistant with durable state I’ve been exploring what happens when a RAG demo has to keep working after the first successful query. This TypeScript sample creates one durable Stateful Actor per company. Each actor: - Embeds a handbook URL into Telnyx Storage - Polls asynchronous indexing jobs and retries failures - Searches the handbook before generating an answer - Refuses to answer when the retrieval match is weak - Records every Q&A in an embedded SQL audit log - Reindexes the handbook automatically each night The interesting part isn’t really the chatbot. It’s giving the entire retrieval lifecycle a durable owner: source state, indexing progress, retries, scheduled refreshes, and answer history all stay with the company’s actor. The sample uses Telnyx Edge Compute, Stateful Actors, Embeddings, Storage, and AI Inference. Code: github.com/team-telnyx/telnyx-code-examples/tree/… The public routes are intentionally unauthenticated for the demo, so production use would need authorization, retention rules, evaluations for the similarity threshold, and better observability. I’d be interested in feedback on the actor-per-tenant approach, especially from anyone maintaining frequently changing internal knowledge bases.