How the platform uses Telnyx

Telnyx is the telephone carrier. It rents the phone numbers, it places every call, it carries the hand-off to a person, and it sends and receives the text messages. This page shows what the platform does through Telnyx, what Telnyx reports back, and what a person sets up in the Telnyx account by hand. Each item on this page runs today, except where marked.

One account, four environments

LeadRefinery has 1 Telnyx account. Inside it, each environment has its own voice application, its own voice profile and its own API key. The key that signs the webhooks is 1 value for the whole account. Each dial names the address that Telnyx must report to, and the application carries the same address as a fallback. Thus a staging call can never report to production.

Since 19 October each production client also gets its own voice application, voice profile and billing group, so the invoice splits per client. Billing each client explains those 3 objects.

The 4 environment profiles share the same settings. Calls may go to the United States and Canada only. The 3 profiles outside production also allow Poland and Montenegro, for the team's own test phones. The profile the platform creates for each client allows the United States only. No profile records calls. No profile has a spend limit. No profile has a limit on calls at the same time, except the production demo line at 4. The account limit of 20 open calls covers all 4 environments together.

The demo line

A sales demo places a real call from the demo number on the demo application. It does not use the campaign machinery: no durable job, no number pool, no lead record. The demo code goes to the person by text first, from a toll-free number that Telnyx verified for that use. The demo registers the conversation with Retell before the dial, not at the ring, and the demo line has its own daily limit and a lifetime budget of calls per team member. After the answer, the hand-off to Retell and the transfer to a specialist are the same as for a campaign call.

How a call goes through Telnyx

The platform places every call itself. Retell, the voice service, never dials. The order is:

1. Claim a number. The platform claims one number from the client's pool, under its daily limit. How the platform rotates its numbers gives the rule.
2. Tell Telnyx to dial. The dial goes out on the client's own voice application, from the claimed number. The request carries the attempt's own id. Telnyx refuses a second request with the same id, so a retry can never ring the person twice. Before a retry that has no call id yet, the platform also asks Telnyx for its live calls; a live call it finds is adopted as the same attempt, never dialled beside. The dial sets no ring limit, so Telnyx's 30 seconds applies, and it asks Telnyx to retry the "answered" report 4 times if the platform does not answer it.
3. Telnyx reports "ringing". At that moment the platform registers the conversation with Retell, one call at a time, never in a batch. The registration moved twice: first from before the dial to the answer, then on 13 October from the answer to the ring. If the registration at the ring fails, the answer handler registers instead. The move to the ring keeps the safety gate's decision current until the last possible moment.
4. Telnyx reports "answered". The platform transfers the Telnyx call to Retell's own line. Retell then holds the conversation. Retell also decides whether a machine answered. Telnyx does no machine detection on a campaign call.
5. Telnyx reports "hung up". The hang-up carries the network's reason. "No answer" and "cancelled" become a no-answer outcome. "Busy" becomes busy. An unallocated or changed number becomes an invalid number. A network error becomes a carrier failure. A fax tone becomes fax. Two codes, 607 and 608, mean that the network blocked the call as unwanted; 603, a person who pressed decline, does not count. The 2 block codes take the number out of service at once, as Who decides a call is spam describes.

If the transfer to Retell does not complete within 20 seconds of the answer, or within the call's own time limit if that is shorter, the platform ends the call, so the person never listens to silence. The hang-up command has 3 settings per environment: off, where nothing is decided; log, the default, where the platform decides and writes "would abort"; and on, where it hangs up.

What Telnyx reports, and how the platform checks it

Telnyx sends each event of a call to the platform as a signed message. The platform checks every message before it counts:

• The message carries a cryptographic signature and a timestamp. The platform rejects a forged signature and a message more than 5 minutes old. A platform with no webhook key configured refuses every message.
• The platform stores each event once. Telnyx resends an event that got no answer. A resend of an event already stored counts once. If the first copy was stored but its signal to the call's job failed, the resend sends that signal again.
• Each message names the call attempt it belongs to. A message that arrives before the call record has Telnyx's call id is still filed on the right attempt.

Text messages arrive at a second address with the same signature check, and every text is stored. A report about a call that the platform did not place is counted and dropped, not stored. The platform also holds a second key for rehearsals; a report signed only with that key is refused for a real call.

The hand-off to a person goes through Telnyx

Retell cannot transfer a call that Telnyx bridged into it. Thus the platform runs the transfer itself, as Mid-call tools describes from the agent's side. Through Telnyx, the steps are:

1. Dial the client's specialist line from the number that placed the call, with a ring limit of 25 seconds. Telnyx's machine detection is off for this dial: a person reading a long briefing out loud was, in practice, sometimes read as an answering machine. A desk that hangs up counts as no answer.
2. Read the briefing to the person who answers, and collect one key: 1 to accept, 2 to hear it again (3 times at most), 3 to decline. Each wait for a key lasts 15 seconds, and the whole attempt ends after 80 seconds. The connection to the voice service now stays open well past this limit, so a slow desk is never cut off before it can answer.
3. On accept, join the merchant's call to the specialist's call. Retell leaves the line. Otherwise, hang up the specialist's call and tell the agent.

While the specialist listens to the briefing, the merchant hears a short hold message and hold music, in a loop.

Text messages go through Telnyx

• Each environment sends texts from 1 fixed number. A pool number never sends a text. The demo code goes from the toll-free number that Telnyx verified for that use.
• The platform sends the application link at most once per call, and only after the consent and do-not-call checks pass. A second call to the same person can send it again. A text is refused when the person withdrew consent, when any stop request stands, or when an undecided stop request waits. A text to a number outside the United States goes out under a name, not a number.
• A person who texts STOP, or one of the other stop words (STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT), is removed from calls and texts in every client at once. START never reverses it. HELP gets an automatic reply from Telnyx.
• The automatic replies to STOP, START and HELP live on the Telnyx messaging profile. A person sets them with a script; one run sets every messaging profile in the account. (a person does this today) The reply to START says "You are subscribed" while the platform keeps the block; the 2 disagree today. (open gap)

When Telnyx says no

Telnyx refuses a dial when the account is at its limit of calls at the same time, or when dials come too fast. The platform never retries that dial. It counts the refusal and its scope, and it holds every further dial to Telnyx for 1 minute, then 5, then 15, with 1 test dial at the end of each wait. A refusal during a hold does not lengthen it, and the ladder resets after 30 quiet minutes. A dial that Telnyx accepts clears the hold. The lead loses nothing: no attempt is spent. An empty balance is different: Telnyx answers "payment required", the attempt fails as "no credit", and no hold starts.

The platform also computes its own ceiling on open calls from the account limit. Each call takes 2 channels at Telnyx, one for the person and one for Retell, and the platform keeps 2 channels in reserve. The ceiling is the smaller of 20 and half the account limit less 2. The account limit itself is not known to the platform until a person enters it; with none entered, the ceiling is 20. (a person does this today)

The platform reads the public Telnyx status page every 60 seconds and records the health of the parts on the dial path: US calling, the API, the voice service, and the SIP trunks. The reading goes to the dashboards. It stops no dial on its own. If the page cannot be read, the last reading stands and a gauge shows that the feed is unreachable.

What a person does in the Telnyx account

The platform creates each client's 3 billing objects when the client is created, binds each pooled number to them, sets the client's voice application inactive when the client is archived and active again on restore, and removes the 3 objects when the client is deleted. If Telnyx refuses the binding of a number, the platform logs it and keeps the number in the pool. Everything else in the Telnyx account is a person's work, in the portal or with the runbook in the repository:

• Buy each number, and tag it with its environment. (a person does this today)
• Get a toll-free number verified for text messages. The verification of the current number took several days. (a person does this today)
• Ask Telnyx support to raise the account limit on calls at the same time, and give each client's voice profile its own limit after that. (a person does this today)
• Set the automatic text replies on each messaging profile. (a person does this today)
• Rotate an environment's API key, and move a number between environments. (a person does this today)
• Top up the balance. Nothing in the platform watches the balance. (a person does this today)

A number removed from a pool stays rented at Telnyx. Nothing in the platform cancels a number.