Module 16 · SMS

Lee en español: Módulo 16 · SMS.

Goal: register the provider your texts leave through, prepare an approved template, send a message, handle the replies, and know what the platform does with a consumer's opt-out and with the monthly cap. Time: ~9 minutes · You need: a dashboard user; to approve templates, register an account-wide provider or save the auto-reply, an account administrator.

SMS lives in the SMS menu (/sms). That screen puts together, top to bottom, the SMS inbox, the Send a message form, SMS usage and the SMS messages history. Templates and providers have their own screens.

1. Register a provider

Messages leave through an SMS provider. In Trunks & Carriers click SMS providers → (or go to /trunks/sms-providers). The list shows Name, Adapter, Region, Scope, Status and Webhook secret.

1. Click Register a provider.
2. Pick the Scope: This sede or Whole account (every sede). The dashboard offers the second one only to an account administrator; if you are not one, the screen says so ("Registering a provider for the whole account needs an account admin; here you register one for this sede.").
3. Pick the Adapter: HTTP (internal contract), Telnyx or Mock (no real sends), and the Region: United States (us), Mexico (mx) or Europe (eu).
4. Type the provider Name.
5. Only the HTTP adapter shows the Endpoint URL: it must start with https://, use port 443 and a public address; blank uses the platform-wide endpoint.
6. Paste the Webhook secret and click Save. For Telnyx it is your account's Ed25519 public key (base64), never a private key.

The secret is write-only: it is sent once, stored encrypted and never shown again. In the list you only see Stored or None stored, and Details opens the identifier, when it was registered and its last change.

Retire asks you to confirm with Retire for good (or Keep it): the provider stops carrying messages, cannot be brought back, and its history stays. A provider Inherited from the account is not retired from the sede: it says "Belongs to the whole account: not retired from here."

No provider of your own

If you have not registered one yet, the screen warns you: messages leave through the platform-wide configuration, if there is one.

2. Create a template and get it approved

In SMS click Manage templates (/sms/templates). A template is a text with variables and versions: what gets approved is one specific version.

1. Click New draft.
2. Type the Template name and the Message body. Variables go in the body between double braces, for example .
3. In Variables declare one per line as name:string, name:number or name:date; add :optional only when needed.
4. Click Save draft.

The platform requires the body to carry an opt-out notice naming a word it honors (see section 5) and to avoid prohibited terms; otherwise it rejects the draft.

Every version has a status: Draft, Approved or Retired.

• A Draft can be edited (Edit draft), Approved or Retired.
• An Approved version is no longer edited: it can only be Retired. To change it, write a new draft.
• A Retired version is final.

Who approves. Any dashboard user creates and edits drafts, but approving belongs to the account administrator. The Approve button shows on every draft and the server decides — the screen itself says so ("The server is the authority for every state change."). So the flow is: whoever writes the text saves the draft and asks the administrator to approve it. There is no "Reject" button: rejecting a draft means Retire-ing it.

Not in the dashboard

The "approved templates only" policy, which refuses every free-text send, is managed through the API. It is in the SMS developer guide.

3. Send an SMS

In the Send a message form: one message at a time.

1. Type the Recipient number (format +15551234567) and the Message.
2. If you need to, open More options: Sender number, Time zone, Campaign, Account ID and Contact reference.
3. Click Send message.

The form decides nothing: consent, do-not-call lists, quiet hours and the spending limit are checked by the platform. What it can answer:

• The platform accepted the message for that number, with the number of segments. A long text is split into several segments and each one counts toward usage.
• A compliance check refused this message, with its Reason and Rule. Nothing was sent and no message was created, and sending it again is refused again. When a record of the decision exists, the Verify the decision link opens it.
• The SMS provider rejected the message: the attempt shows in the history as Failed.
• No answer from the platform: the message may or may not have been sent. Trying again unchanged is safe, because it reuses the same send reference and duplicates nothing. If you change the text, it is a new send.
• Too many requests: wait the seconds shown and try again.
• The sender is not yours (sms_from_not_owned or sms_from_invalid): the sender (Sender number, or the provider's default line) must be an E.164 number and an active number of your account. Nothing was sent. Register the number under your numbers, or choose one you own.
• No rate (no_rate): no price covers that destination, so the send is refused. Topping up changes nothing; retrying unchanged is refused again until the platform prices it.

4. Read and reply in the inbox

The SMS inbox groups messages into conversations by consumer and sending line, newest activity first. Inbound activity only keeps those with received messages. Load more conversations brings the rest.

Pick a conversation to see its messages and "Using line …". From there:

• Reply — write your answer and Send reply; Reply accepted. confirms the platform took it. Your reply goes through the same checks as any send: it can be refused.
• Assign to shares the conversation across the team. An administrator assigns it to anyone; other users can only take it for themselves or release one that is already theirs. Unassigned releases it.
• Mark as read clears the mark for the whole team.
• Load older messages shows the older history of that conversation.

Below it, the SMS messages history lists every message newest first; filter by direction (Outbound or Inbound), status (Queued, Sent, Delivered, Undelivered, Failed, Received), campaign and account ID. Details opens the Message detail: the provider, the Status timeline, the Status changes and the Compliance decision it was sent under.

The SMS usage panel adds up billable segments between two dates (From and To), with messages, segments, amount and the rate in force per segment. A segment counts when the provider accepts the message.

5. Consumer opt-out by keyword

When a consumer replies with one of these words — STOP, ALTO, UNSUBSCRIBE, CANCEL, QUIT or END — the platform, without you doing anything:

• adds their number to your internal do-not-call list, and from then on texts and calls to that number are blocked;
• revokes their consent;
• sends them a message confirming the opt-out.

That confirmation goes once per number and window (24 hours by default): if the same number sends STOP again inside the window, the opt-out is applied again but no second confirmation is sent, so nobody can make you pay one SMS per message by looping STOP.

Who it applies to. If the STOP arrives through a provider inherited from the whole account (the one with the scope Whole account), the opt-out is written in every sede of the account, not only the one that last wrote to that consumer: to a regulator the caller is the company. If it arrives through a provider registered for one sede, it stays with that sede. It never crosses to another account.

The opt-out is applied always, even if the notice arrives late or out of order. The consumer can come back with START (what it lifts is below), and HELP or AYUDA gets a help message. It is the same list you see in Compliance, under Internal do-not-call list: that is also where you upload cease requests.

Words honoured without being announced. Besides those six, the platform also treats as an opt-out REVOKE, OPT OUT (also written OPTOUT or OPT-OUT), the suffix ALL after a stop word (STOP ALL, REVOKE ALL, STOPALL) and short phrases: a message of up to 6 words that contains a stop word as a whole word (please stop, stop texting me, Stop 🛑). Capitals, punctuation and emoji do not matter. A longer message does not unsubscribe anyone — "can you stop by the office tomorrow?" is just a message — but if it contains a stop word the live-floor frame sms.received carries possible_optout: true, so a person on the floor sees it and decides. ALL on its own, or a word that only contains a stop word (STOPPED, "unstoppable"), is not an opt-out.

What START lifts. START grants SMS consent again and removes only the listing an SMS STOP wrote. It does not erase an opt-out the consumer made by voice, with the keypress, through an inbound call or that your own team uploaded in a CSV, and it does not erase a listing of unknown origin (older ones with no recorded reason are kept): that number stays on the list and sends to it keep blocking. If a voice or CSV opt-out lands on a number that was on the list because of an SMS STOP, the listing becomes that one and a later START no longer lifts it. A START that arrives older than the state on file (the notice came late, after a newer STOP) changes nothing. It never touches the opt-out another sede holds for the same number, nor the regulatory lists.

That is why your templates and your auto-reply must name one of those words: a notice inviting a word the platform does not understand protects nobody.

6. Out-of-hours auto-reply

In Settings, the Out-of-hours SMS auto-reply card answers on its own the messages that arrive outside your business hours. It is off by default and needs three things at once:

1. The platform switch. It is operator level and Dialer Digital's team turns it on, not you: the dashboard says so ("Operator switch: off by default and managed outside the dashboard"). The card does not show its state and reads "server does not expose current state": if you saved everything and nothing answers, ask support to enable it.
2. The saved text: Body, Language and Cooldown (seconds).
3. The saved schedule: Time zone and the days and hours you are open.

Click Save settings; only an account administrator can ("Only an account administrator can change these settings."). If one of the two halves fails, the dashboard names which: Auto-reply or Business hours.

The auto-reply is not an exception: it goes through the same checks as a normal send (consent, do-not-call, quiet hours, frequency and spend), and if one blocks it, it is not sent and not held for the morning. It answers at most once per conversation in each cooldown period. Its body must also carry the opt-out notice.

7. The monthly cap

Your account manager can set each sede a monthly SMS spend cap; if none is set, there is no cap. When there is one and the month's spend reaches it, sends stop before reaching the provider: no message goes out and nothing is billed. Retrying does not help; sends resume when the cap is raised or the next month begins. Your account manager sets the cap, not the dashboard, so that a leaked key cannot raise its own budget. To see it coming, watch SMS usage during the month.

Three other refusals are about money rather than the cap, and each comes back as 402: wallet_insufficient (top up your prepaid balance), plan_exhausted (the SMS included in your plan is used up: upgrade your plan) and exposure_limit (complete the account verification). Nothing is sent or billed in any of them. A synthetic demo tenant gets 403 synthetic_tenant: it never sends outward, and no payment changes that.

8. A campaign that sends nothing

An SMS campaign sends from its own numbers (caller IDs or pool) or, failing that, from the provider's default line, and they must be active numbers of your account. If none is usable, or no provider resolves, the campaign does not fail: it ticks and sends nothing. The campaign statistics (send_unavailable_reason, in the API and the live stats frame) say why: provider_unresolved (no provider), caller_ids_no_active_did or caller_id_pool_no_active_did (no active number among the campaign's), default_from_invalid (the provider's default line is not a number you own), did_unverified (your account demands proven ownership of numbers and the active ones have none) or outside_calling_window (the campaign is outside its calling window; it sends again when the window opens). The reason clears itself on the first tick that passes. Detail in the SMS developer guide.

What you learned

• How to register and retire a provider, and why the webhook secret is never shown again.
• The life of a template (draft, approved, retired) and that approving belongs to the administrator.
• What the send form answers and when it is safe to retry.
• How to read, assign and reply in the inbox, and where to see usage.
• That the keyword opt-out is automatic, that the auto-reply is off by default and the platform turns it on, and what happens at the monthly cap.
• That the sender must be a number you own, that a destination with no rate is refused (no_rate), that STOP is confirmed once per window, and how to read why a campaign sends nothing.

More technical detail in the SMS developer guide, the webhooks and the rate limits and caps.