Two Letters Decide the Field
The same value you paste into the sender field is sent under two different parameter names, and which one is chosen depends on the first two characters. That is not a quirk of the connector — it is Twilio telling you what kind of thing you gave it.
One settings field, labelled for the number your messages come from. Two entirely different things can legitimately go in it, they look similar, and Twilio needs to be told which is which — not by you, by the request. So the connector reads the first two characters and picks the parameter. It is two lines and it is the difference between a working connector and a rejected message.
Identifiers that say what they are
Twilio gives everything in its system an identifier that begins with two letters naming the type. An account starts one way, a phone number another, a message another, a messaging service another. Once you have seen it, every identifier in their console tells you what kind of object it points at before you know anything else about it.
That is a genuinely good design decision, and it has one immediate practical consequence: a string can be examined and identified without asking anybody. Which is exactly what the connector does.
| What you paste in | What it is | How it is sent |
|---|---|---|
| A phone number | One number you own on Twilio | As the sender number |
| A messaging service identifier | A pool of numbers with routing rules | As the messaging service |
One field on the screen, two meanings, and the request has to name the right one. The prefix is how the connector knows without asking.
Why a messaging service is worth having
It is worth explaining what the second option buys, because most people set up the first and never look further.
A single number is simple and has limits. It sends from one country. It has a throughput ceiling. If it is blocked or has a poor reputation with a carrier, every message you send inherits that.
A messaging service is a pool with rules — several numbers, possibly in several countries, with logic for choosing which to send from, and behaviour on top of it. For an organisation sending to more than one country, or sending enough volume to care about throughput, it is the difference between messages arriving and messages being rate limited.
The point for this connector is that supporting only one of the two would quietly cap what a workspace could do, and the cap would be invisible — you would simply not be able to paste in the thing your Twilio account is built around.
The alternative, and why it is worse
The obvious alternative is a second setting: a dropdown asking whether this is a number or a service.
It sounds more explicit and is worse in every respect. It is a question with exactly one correct answer, derivable from the value already entered — so it is a question that can only be got wrong. And when it is got wrong, the failure is a Twilio validation error about a parameter nobody typed, which sends whoever is fixing it looking at the value rather than at the dropdown.
A setting that can be derived should be derived. Every field on a settings screen is a chance for somebody to be wrong, and the ones that carry no information at all are pure cost.
Where the credentials sit, and why they sit there
Twilio needs two values to authorise a request and they are handled differently, correctly.
-
The account identifier is part of the address
It names whose account the message belongs to and appears as a segment of the request path. It is an identifier rather than a secret, which is why that position is fine.
-
And it is escaped for that position
A value going into a path segment is encoded for a path segment. It is a formality with these identifiers and it is the correct habit — the day a value with a slash in it reaches that line, the encoding is what stops it becoming a different request.
-
The token travels in the authorisation header
The actual secret goes where secrets go, using standard basic authentication, rather than in the address.
-
The body is form-encoded
Twilio's messaging interface predates the industry's move to JSON everywhere and takes form parameters. Sending JSON to it produces a confusing refusal.
That split is worth contrasting with one of the other connectors in this series, where the credential itself is the address. Here the identifier is in the path and the secret is in a header — which is the arrangement to prefer whenever a provider offers it.
Refusing before the network
Three values are required and all three are checked before any request is made. A missing one produces a message naming all three rather than a network round trip and a provider error about authentication.
That matters more on this connector than on most, because Twilio's two credentials are easy to confuse with each other and with the various other identifiers in the same console. An error that says which three things are needed is a better starting point than a rejection that says the request was not authenticated.
What is in place, layer by layer
The Twilio connector as it stands
One sender field, two kinds of value
A phone number or a messaging service identifier, distinguished by its own type prefix and sent under the parameter that matches.
Derived rather than asked
No second setting asking which kind it is, because the value already says — and a question with one derivable answer can only be answered wrongly.
Messaging services supported, not just numbers
Multi-country sending and higher throughput are configurations Twilio accounts are commonly built around, and pasting one in works.
The secret in a header, the identifier in the path
Standard basic authentication for the token; the account identifier as an encoded path segment, because it names rather than authorises.
Path values encoded for their position
A formality with well-formed identifiers, and the correct habit — the encoding is what stops an unexpected value becoming a different request.
Form encoding, as the API expects
Twilio's messaging interface takes form parameters rather than JSON, and sending the wrong one produces a refusal that reads as an authentication problem.
All three credentials checked first
A missing value produces a message naming what is needed, rather than a network round trip and a provider error about authentication.
Credentials encrypted at rest
Stored on the row for one workspace, never in configuration or environment, and never written into a log line.
Your own Twilio account
Your credentials, your numbers, your billing. The relationship with the provider is yours rather than mediated by us.
The three SMS providers share one settings screen and one stored shape, and each reads those fields with its own meanings — which is why the labels change when you change provider.
Three positions held on purpose
- Anything derivable from a value already entered is derived rather than asked. A settings field that carries no information the system does not already have is a pure opportunity to be wrong.
- The secret goes in a header and the identifier goes in the path. Where a provider separates the two, the separation is used — logs, proxies and monitoring tools record addresses far more readily than headers.
- Both kinds of sender are supported rather than only the simple one. Supporting only single numbers would cap a workspace at one country and one throughput ceiling, and the cap would be invisible until somebody tried to paste in what their account is actually built on.
Five questions about an SMS provider integration
Can we use a messaging service, not just a number?
A good answer sounds like
Yes.
What ours actually is
Both are accepted in one field, distinguished by the identifier's own type prefix.
Do we have to tell it which kind we pasted?
A good answer sounds like
No.
What ours actually is
It is derived from the value, because the value already says.
Where does the auth token travel?
A good answer sounds like
In a header.
What ours actually is
Standard basic authentication. The account identifier is in the path; the secret is not.
What if a credential is missing?
A good answer sounds like
A clear reason.
What ours actually is
Checked before the request, with a message naming all three required values.
Whose account sends the messages?
A good answer sounds like
Yours.
What ours actually is
Your credentials, numbers and billing. Nothing is mediated through a shared account.
Our take
Typed identifiers are a small idea with a large payoff, and Twilio is the best-known example of getting them right. Because every identifier announces what it is, code can accept a value without being told what kind it is, validate it without a lookup, and route it correctly with a two-character test. Compare that with the systems where an identifier is a bare number and the only way to know what it points at is to know where you got it. If you are designing an interface anybody else will integrate with, prefixing your identifiers by type costs you two characters and saves everybody downstream an entire class of configuration question.
Send from the account you already have
Your Twilio numbers, your messaging service, your billing — with the routing decision derived rather than asked for.
Talk through SMS alertsFrequently asked questions
Can we paste a messaging service identifier into the sender field?
Yes, and it is often the better choice. Twilio identifiers announce their own type, so the connector recognises which kind of value it has been given and sends it under the right parameter. There is no second setting to get wrong.
Why would we use a messaging service rather than a number?
Multiple countries, higher throughput, and pooled sender behaviour. A single number sends from one country with one throughput ceiling and carries its own reputation with carriers. If you send across borders or at volume, the pool is what makes messages arrive.
Which Twilio values do we need?
Three: the account identifier, the auth token, and the sender — either a number you own or a messaging service. All three are checked before any request is made, so a missing one produces a message naming what is needed rather than an authentication error.
Is our auth token safe?
It is stored encrypted on the row for your workspace, travels in the authorisation header rather than in the request address, and is never written into a log line or shown back in an error message. The account identifier does appear in the request path, which is correct — it names the account rather than authorising anything.
Can we switch SMS provider later?
Yes. The three providers share one settings screen, and choosing a different one changes what the fields ask for and which driver sends. Nothing about your notification routing has to be reconfigured.
