Skip to main content

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 mobilePhoneNumber of an ExtendedIdentity data 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 the unreachable route instead of failing the session.
  • Customer-supplied template: the message body is a messageTemplate data 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: sent when the messaging service accepts the message, unreachable when 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.

CheckRuleRejection
CharactersNo 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
LinksNo 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 lengthA 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 lengthThe 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 boundAt 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 blockRequiredDescription
ExtendedIdentityYesIdentity whose mobilePhoneNumber is messaged, in E.164 format. A missing number routes the step to unreachable.
MessageTemplateYesThe message body to send. Supply it at session creation by declaring messageTemplate in the Start step inputs.

Routes​

RouteDescription
sentThe messaging service accepted the message. This confirms hand-over to the network, not delivery to the handset.
unreachableNo phone number was available in the extended identity, or the messaging service reported that the message cannot be delivered.

Output data blocks​

RouteData 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"
}
}