How the platform rotates its numbers

Rotation here has one meaning. The platform replaces a number that lost its health with a rested number. It also spreads each day's calls evenly across the numbers in service. Rotation never means many numbers that hide one caller. The scoring companies detect that pattern, and a new number starts with the business's own score.

The five states of a number

A number is in exactly one of five states:

• Warming up — the number makes a small count of calls each day, and the limit rises across ten working days. Bringing a number into service gives the reason for the slow start.
• In service — the number carries full traffic, at a limit of 75 calls each day.
• Throttled — the number still calls, at a limit of 40 calls each day. Today the code holds a limit of 25 calls. The change is decided, and it is not built yet.
• Quarantined — the number makes no calls. Its daily limit is zero.
• Retired — the number never calls again. Its health history stays.

The life cycle of a number gives each stage in full, with the registration that comes before the first call.

What moves a number between states

The health assessment judges a number over a window. The window holds at least the last 3 working days, and it must hold at least 150 calls. The floor of 150 calls applies to an answer rate of 25%. When the pool's answer rate is lower, the floor rises, because chance moves a low answer rate more: about 300 calls at 15%, and about 450 at 10%. The window then covers more days. The platform raises the floor and never loosens the half-the-median rule. Fewer calls are not evidence, and the state does not change. The same rule protects a number while it warms up: its first three working days hold 75 calls in total, so no window reaches the floor until day 8. A new number is therefore too quiet to judge for most of its ramp.

The platform compares every rate with the pool's median over the same window. It never compares a number with the number's own earlier rate. On an old list the answer rate of every number falls together across the term, because the easy-to-reach merchants leave early. A comparison with the number's own past reads that fall as a reputation failure on every number at once. A comparison with the pool does not.

These triggers move the number:

• A carrier label, or one attributable complaint. Either one moves the number to quarantined at once, from warming up, from in service, or from throttled. Neither one needs the window. One label is a label.
• The answer rate falls below the pool. The number goes to throttled when its answer rate is below half the pool's median answer rate, for two windows in a row.
• The short calls rise above the pool. The number also goes to throttled on the share of calls that end inside 15 seconds. The trigger is a share more than 1.5 times the pool's median share, for two windows in a row.
• A throttled number keeps a limit of 40 calls each day. The number keeps calling at that limit, because a number that stops calling builds no trust. At 25 calls each day a window holds only 75 calls. That count is under the floor of 150, so the platform can never judge the number healthy again.
• A throttled number goes to quarantined only on both triggers. Both triggers must hold for two more windows in a row. A fall in answers alone never quarantines a number, because a dead part of the list causes the same fall. The rise in short calls is the one signal that identifies a label.
• Recovery from throttled needs two good windows. The answer rate must go back above three quarters of the pool's median answer rate, for two windows in a row. The number then returns to service, at 75 calls each day. Today the code uses a different rule: 3 clean days of 20 or more dials each, or the 24-hour timer described below.
• Recovery from quarantine goes to warming up. After its rest, the number starts the ramp again. It never returns straight to service. The platform does not read the label before it releases the number.
• Retired is final. An operator retires a number, and no trigger moves it back.
• The whole pool falls together. This rule moves no single number. When the pool's answer rate falls by 30% in a week, the cause is the list, or a label across the whole pool. The platform then raises an alert, and it stops the admission of new leads. It rotates no numbers.

The short-call trigger is the important one. People who see “Spam likely” answer the call and end it at once. Thus the count of answers stays high, and the call length becomes much shorter. A number can look healthy on the answer rate alone.

The platform keeps these values in one place, and it can correct them. The platform measures every rate against the pool's median, and never against a fixed figure. A fixed figure fires on every number permanently.

The life cycle page states which part of the health assessment runs automatically today, and which part an operator applies.

Today the code holds the earlier values: a comparison with the number's own last week, a floor of 20 calls, a limit of 25, and 3 clean days. The decided rules above replace them, and the change is not built yet. (proposed)

How one call gets its number

The platform claims a number at the moment of the dial, inside the checks before each dial. The claim is one database step. Inside that step the platform works in this order:

1. It looks only at the client's own numbers.
2. It keeps the numbers in the three calling states: warming up, in service, and throttled.
3. It leaves out a number whose latest reading from Telnyx is high risk. A number with no reading may dial. Today no number has a reading, because the daily read is not yet connected to Telnyx.
4. It keeps only the numbers that are under their limit for today. A warming number's limit comes from the ramp for its day.
5. It sorts the numbers that remain. The number with the fewest calls today comes first. A number with no calls today counts as zero. Two numbers with the same count keep a fixed order, so the choice is repeatable.
6. It takes the first number of that order that no other worker holds at that moment. A held number is skipped, and the next number wins.
7. It adds one to that number's count for today.

The check of the limit and the increase of the count are the same step. Thus two calls that start at the same moment can never both take the last free slot of one number.

Three facts complete the picture:

• A count from an earlier day is stale. The first call of a new day resets that count to one, in the same step.
• When no number can be claimed, the check refuses the dial. The platform moves the call to another slot, and it uses no call attempt.
• When a later check refuses the dial, the platform gives the claim back. The day does not lose capacity to a call that never happened.
• On the rare occasion that two clients hold the same number, the daily limit counts the calls of both clients together. A block on that number removes it from both pools at once.
• The calling day ends at midnight in Hawaii, the last United States time zone. Thus no number's count resets while the platform still calls.

The reserve numbers, and the stop for the whole pool

Each client's pool holds two roles. The working numbers carry the campaign. The reserve numbers carry a different role name in the records, but the claim rule does not read the role: a reserve number dials exactly like a working one. The role is a sizing label. To change it, a person calls the platform's API; the pool screen shows the role but does not switch it.

Three rules size the pool and stop it:

• One working number for each 75 calls a day. The pool screen shows the working count from the day's dialling capacity, rounded up. The platform does not buy or assign numbers from that figure.
• The reserve is one quarter of the working numbers. It is a share, and not a fixed count. Past roughly fifty numbers, quarantine is a rate and not a single event, so a fixed reserve of two is too small.
• More than one tenth quarantined inside 7 days stops the intake. The platform then admits no new leads for that client. This is one of the automatic stops that the campaign page describes. The count covers every number quarantined in those 7 days against the working numbers not yet retired, with no minimum pool size: 1 number of 9 trips it. The alert for the team adds a floor of 10 numbers.

The last rule treats a wide problem as a wide problem. The reserve numbers get the same calls, so a swap gives the same result, and the client loses the reserve for no benefit.

Two proposals

Two changes to rotation are planned. Neither one runs today:

• The reserve numbers call while they wait. Each reserve number makes a few calls each day. A swap-in then has days of history, and it does not look like a new number that replaces a labelled one. Today this happens by accident and in full: the claim rule ignores the role, so a reserve number dials as much as a working one. The planned shape is a small, fixed share. The page on bringing a number into service gives the reason in full. (proposed)
• The same person hears from the same number. Today the platform picks a number for each call, without regard to that person's earlier calls. The change removes two harms. People who see many different numbers complain more. A shared calling pattern is also one of the ways that the scoring companies connect numbers to one caller. Protecting reputation lists both harms with the other planned habits. (proposed)

How a number comes back, and what watches the pool

A throttled number returns on its own once 24 hours have passed at the lower limit. The return happens in the daily job at 07:00 UTC, so the trial lasts between 24 and 48 hours. A number that had finished its ramp, and is registered, returns to service at 75. Any other goes back to warming at its ramp day's limit. A fault during the trial does not block the return; it throttles the number again afterwards. A quarantined number rests 14 days, and then it returns as warming, from day one of the ramp. An operator can release a quarantined number early on the Dialling tab. The dialog asks only to confirm. The platform writes who did it and when, not why.

Seven alerts watch the pools, and a person acts on each:

• a client has numbers on the books, and none that the dialler can pick;
• a client's working pool is smaller than its reserve;
• more than one tenth of a client's pool went to quarantine inside 7 days;
• more than 3 numbers carry a spam label;
• most numbers in a pool failed the same way, and dialling paused;
• a pool's numbers are dialling above nine tenths of their daily limits;
• every daily limit in a pool is used up.

Further alerts fire on each throttle or quarantine, on a reaction that failed to run, and on a long hold caused by the carrier's refusals.

Three known gaps today

A daily job runs the health check, the warm-up step and the pool breaker for each client, after the last calls of the day have ended in every time zone the platform calls. The job is built and connected to read each number's standing with the phone company and to hold back any number the company has marked as unwanted, but that read is switched off everywhere, because each fresh reading is billed per number. (open gap) Number reputation explains. A number does not wait for the daily job either: the moment a call ends, if the calling service's own reason for ending it says the carrier blocked the number outright, or the carrier has refused most of that number's recent calls, the platform throttles or removes the number at once. (built)

The rest of the decided rules do not all run yet. Three parts are still missing:

• The health check does not yet receive the pool figures the decided rate triggers need: the pool's median answer rate, and the pool's median share of short calls. So neither rate trigger fires yet, and the fall in answers and the rise in short calls move no number today. (open gap)
• A complaint does not yet take a number out. The platform has no way to hear a complaint about one of its numbers today, so a complaint is never recorded and that trigger never fires. A feed of complaints from the phone company is the missing piece. (open gap)
• No code changes a number's role. A person does it through the platform's API today; the pool screen shows the role only. (a person does this today)