Sending SMS (v1)
Preview / Alpha
This step is in preview / alpha. Its functionality and documentation can still change.
Sends an informational SMS to the user's phone number
Sending SMS (v1) sends a plain informational text message — not a one-time passcode — to a phone number supplied at session creation or produced by an earlier step in the flow. It is intended for journeys that begin on one channel and need the user to continue on their phone.
Key features
- Background step: no Player screen is rendered and the user is not interrupted.
- Verified identity required: the step messages the
mobilePhoneNumberof anExtendedIdentitydata block. Supply the block at session creation, or let an earlier identity step produce it. When that block carries no mobile number, the step takes theunreachableroute instead of failing the session. - Customer-supplied template: the message body is a
messageTemplatedata block supplied at session creation, so the customer controls the wording. - Reserved placeholder: the only supported placeholder is
{session.url}, which the step replaces with a short Player link. The placeholder may appear anywhere in the template, any number of times; using no placeholder is also valid. - Validated template: the message must fit one SMS segment and must pass character and link restrictions. See Template validation for the full rule set and the error codes returned at session creation.
- Two routes:
sentwhen the messaging service accepts the message,unreachablewhen the identity carries no mobile number or the service reports that the recipient cannot receive an SMS.
Template validation
The template is validated at session creation. A rejected template fails the whole request — no session is created.
| Check | Rule | Rejection |
|---|---|---|
| Characters | No control characters other than line breaks, no bidirectional formatting characters, no zero-width spaces, no lone surrogates. The zero-width non-joiner and joiner (U+200C and U+200D), which some scripts and compound emoji rely on, are allowed. | 412 — FIELD_CONTAINS_UNSUPPORTED_CHARACTERS |
| Links | No http://, https:// or www. address other than {session.url}. Links are detected by their explicit scheme or www. prefix, so this is a content guard, not a guarantee that a message can never carry a link. | 412 — FIELD_CONTAINS_EXTERNAL_URL |
| Raw template length | A GSM-7 message may use the configured limit (160 septets by default, lowered by the platform operator). A message containing any character outside GSM-7 (an accented letter such as ç, an emoji or a CJK character) is UCS-2 and limited to 70 UTF-16 code units by default; the platform operator may raise that to 134, which is two segments. GSM extension characters (|, ^, {, }, [, ], ~, \, €) count as two septets. | 412 — FIELD_LENGTH_EXCEEDED |
| Rendered length | The same budget, measured after every {session.url} is replaced by the short link, so a placeholder costs the length of the link rather than the 13 characters of the placeholder itself. | 412 — FIELD_LENGTH_EXCEEDED |
| Hard bound | At most 100,000 UTF-16 code units, whether or not a step consumes the template. | 400 Bad Request |
Configuration
This step has no configuration options.
Input data blocks
| Data block | Required | Description |
|---|---|---|
ExtendedIdentity | Yes | Identity whose mobilePhoneNumber is messaged, in E.164 format. A missing number routes the step to unreachable. |
MessageTemplate | Yes | The message body to send. Supply it at session creation by declaring messageTemplate in the Start step inputs. |
Routes
| Route | Description |
|---|---|
sent | The messaging service accepted the message. This confirms hand-over to the network, not delivery to the handset. |
unreachable | No phone number was available in the extended identity, or the messaging service reported that the message cannot be delivered. |
Output data blocks
| Route | Data blocks produced |
|---|---|
sent | — |
unreachable | — |
Example payloads
At session creation, supply the template for a flow that declares it:
{
"input": {
"extendedIdentity": {
"mobilePhoneNumber": "+33612345678"
},
"messageTemplate": {
"template": "Continue your verification here: {session.url}"
}
},
"metadata": {
"subjectId": "customer-subject-id"
}
}