A text-to-speech greeting can be technically available and still sound wrong.
Names, medications, locations, and product terms are especially good at exposing the gap between written text and spoken output. Fixing those pronunciations often means filing a developer ticket, changing configuration, and generating the audio again.
Fluency Lab explores a different operating model: one durable actor per clinic owns its pronunciation dictionary as a versioned resource. Staff submit a correction by SMS, the actor validates and applies it, the greeting is synthesized again, and a scheduled canary checks the generated audio.
The sample is written in TypeScript and combines Telnyx Edge Compute, the Agent SDK, Messaging, pronunciation dictionaries, and Text-to-Speech.
What the sample does
A staff member sends a correction using one of two supported forms:
add Novocaine to the dictionary — NO-voh-kayn
add Dr. Ng -> /dɹ.ɛŋ/
The first produces an alias item. Wrapping the pronunciation in slashes produces an IPA phoneme item.
Behind that message, the application:
- Verifies the Telnyx Messaging webhook signature.
- Maps the receiving number to a clinic identifier.
- Resolves one durable
FluencyLabactor for that clinic. - Parses and validates the proposed dictionary item.
- Adds the edit to a pending queue keyed by the webhook event ID.
- Fetches the current pronunciation dictionary.
- Sends a full replacement item list through
PATCH. - Retries after a concurrent-update conflict.
- Records the applied change and re-synthesizes the greeting.
- Sends a confirmation to the requesting staff member.
The public route stays thin. Business state and retry behavior live in the actor.
One durable actor per clinic
The webhook derives a stable clinic ID and forwards the verified event to its actor:
const stub = env.FLUENCY.idFromName(clinicIdFor(to, env));
await stub.receive({ text, from, to, eventId });
The actor owns the state required to continue after a restart:
type DictState = {
clinicId: string;
dictId: string | null;
version: number;
items: DictItem[];
pending: PendingEdit[];
lastCanaryHash: string | null;
lastAppliedVersion: number;
degraded: boolean;
};
On its first use, the actor creates the clinic dictionary. In live mode, a cold actor first searches for an existing dictionary with the expected name and reattaches to it instead of creating another one.
This is the central design choice: the pronunciation dictionary is not passive configuration. It has a durable owner responsible for applying, recording, and checking changes.
Retrying a concurrent dictionary update
Pronunciation dictionary updates replace the complete items array. If two editors build their updates from the same starting version, a blind retry could overwrite one of them.
Fluency Lab fetches the current dictionary before each attempt, merges the requested term, and retries a conflict up to three times:
for (let attempt = 0; attempt < 3; attempt++) {
const current = known ?? await this.fetchDictionary();
known = undefined;
if (!current) {
await this.markDegraded(state.clinicId);
return;
}
const items = [...current.items, edit.item];
const result = await this.patchDictionary(
current.id,
current.name,
items,
);
if (result.ok) {
await this.finalizeEdit(eventId, result.data.version, edit);
return;
}
if (result.status !== 409) return;
}
The production API uses server-side optimistic locking. A conflicting update returns HTTP 409 with error code 90200; the actor then fetches the latest item list and reapplies its term.
The pending queue deduplicates active work by webhook eventId, while term comparison prevents the same word from being appended again. A change is removed from the pending queue only after a successful update or after the actor observes that the term already exists.
What demo mode actually proves
DEMO_MODE=true uses recorded and in-memory fixtures rather than live Telnyx API calls.
The first dictionary update activates a one-shot “rival editor” fixture. That fixture adds a second term and wins the first update, forcing the sample through its 409 → fetch → merge → retry path. This is deterministic concurrency testing; it is not a literal second staff phone during the demo.
Demo-mode TTS returns a bundled silent MP3, and SMS messages are written to the console. To hear actual synthesis or send real messages, use live mode with configured Telnyx resources.
The repository includes a 55-check smoke suite covering parsing, signature verification, the conflict retry, durable state, SQL rows, greeting synthesis, canary scheduling, and idempotent term handling:
npm install
npx tsx smoke_test.ts
The suite runs locally without network access or live API credentials.
Re-synthesizing the greeting
After an update succeeds, the actor synthesizes GREETING_TEXT using the current pronunciation_dict_id:
const audio = await this.synthesize(
this.env.GREETING_TEXT,
state.dictId,
);
const hash = await sha256Hex(audio);
await this.setState({
lastGreetingHash: hash,
lastGreetingVersion: version,
});
The sample exposes the current result through GET /greeting-audio. In live deployments, AUDIO_ACCESS_TOKEN can require a bearer token before returning the audio.
A failed re-synthesis is logged without undoing the dictionary update. The scheduled canary provides another opportunity to detect a problem later.
Checking the audio output nightly
The actor schedules a canary at a configured local time. Each run schedules the next one using a stable task ID:
await this.schedule(
secondsUntilNext(this.env.VERIFY_AT, this.env.CLINIC_TZ),
"canary",
{},
{ id: `verify:${clinicId}` },
);
During the canary, the actor:
- fetches the dictionary;
- marks itself degraded and alerts the owner if the dictionary is missing;
- synthesizes a fixed phrase using the current dictionary;
- hashes the returned audio;
- compares that hash with the previous run;
- records the dictionary version used; and
- schedules the next check in a
finallyblock.
The hash is an output-drift signal, not a pronunciation-quality score. A matching hash shows that the generated bytes are stable under the same configured input. It does not prove that a human listener considers the pronunciation correct. Patient-facing or customer-facing pronunciations should still be reviewed by an authorized person.
Verifying inbound webhooks
The messaging endpoint verifies the signature before parsing the event:
const raw = await req.text();
const timestamp = req.headers.get("telnyx-timestamp");
const signature = req.headers.get("telnyx-signature-ed25519");
if (!timestamp || !signature) {
return new Response("Missing signature", { status: 401 });
}
if (!(await verifyTelnyxSignature(raw, timestamp, signature, publicKey))) {
return new Response("Invalid signature", { status: 401 });
}
Verification uses the unmodified request body and rejects stale timestamps outside the permitted clock-skew window. Re-serializing parsed JSON before verification would change the signed bytes and invalidate the check.
Running Fluency Lab
Clone the example and install its locked dependencies:
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/fluency-lab
cp .env.example .env
npm install
npm run types
npx tsx smoke_test.ts
The example uses placeholders for all phone numbers and credentials. Keep real values in environment variables or Telnyx secrets, never in the repository.
For a live deployment, configure:
- a Telnyx API key and webhook public key;
- an SMS-capable intake number and Messaging Profile;
- a TTS voice;
- the greeting and canary text;
- the clinic timezone and verification time; and
- an optional bearer token for the audio route.
Then deploy the Edge application and point the Messaging Profile webhook at:
https://<YOUR_EDGE_HOST>/webhooks/messaging
Production considerations
The sample demonstrates the ownership and recovery pattern, but a production pronunciation workflow should add controls appropriate to its domain:
- Require authentication or an allowlist for staff senders.
- Add an approval step before a correction becomes caller-facing.
- Store audit identifiers that connect each change to the original event.
- Monitor repeated conflicts and exhausted retries.
- Review pronunciation changes with a qualified human.
- Protect the audio route with
AUDIO_ACCESS_TOKENor an equivalent access layer. - Define retention and privacy rules for staff identifiers stored in the audit table.
The reusable idea extends beyond pronunciation. A durable actor can own any operational resource that non-developers need to change safely: greetings, menus, business hours, routing rules, or other versioned configuration.
Top comments (0)