Message Content

Learn the various customization options for your verification messages.

Default Message Content

The default verification message sent by Prelude is:

12345 is your verification code.

We provide this template translated into 43 different locales. Prelude automatically detects the phone number’s locale from its country code and sends the verification message in the appropriate language.

We strongly recommend starting the message with the code so it remains readable even when truncated (for example, on a watch or with large font sizes). For instance: “12345 is y…”. This layout has been battle-tested against many alternatives to optimize conversion and automated code detection.

We’ve also registered this template worldwide to ensure optimal deliverability and minimize the risk of carrier filtering.

Manually specifying the locale

You can manually specify a custom language for the message by setting the options.locale parameter on the POST /v2/verification endpoint.

options.locale · string

A BCP-47 formatted locale string with the language the text message will be sent to. If there’s no locale set, the language will be determined by the country code of the phone number. If the language specified doesn’t exist, it defaults to US English.

The locale parameter uses the BCP-47 format to specify the language of the message.

The BCP-47 format is a standard for identifying languages and their variants. It is a two-letter language code followed by a dash and a two-letter country code. For example, en-US is US English and fr-FR is French from France.

When you send a locale, Prelude will try to find the closest match for the language and country code. If it doesn’t find a match, it will default to US English.

Supported locales

Locales supported to send verification messages.

• Arabic (ar)
• Bulgarian (bg)
• Chinese (zh)
• Chinese (Taiwan) (zh-TW)
• Croatian (hr)
• Czech (cs)
• Danish (da)
• Dutch (nl)
• Dutch (Belgium) (nl-BE)
• English (en)
• Finnish (fi)
• French (fr)
• German (de)
• Greek (el)
• Hebrew (he)
• Hindi (hi)
• Hungarian (hu)
• Indonesian (id)
• Italian (it)
• Japanese (ja)
• Korean (ko)
• Latvian (lv)
• Lithuanian (lt)
• Macedonian (mk)
• Malay (ms)
• Mongolian (mn)
• Norwegian (no)
• Norwegian Bokmål (nb-NO)
• Polish (pl)
• Portuguese (pt)
• Romanian (ro)
• Russian (ru)
• Serbian (sr)
• Slovak (sk)
• Slovenian (sl)
• Spanish (es)
• Swedish (sv)
• Swiss German (de-CH)
• Thai (th)
• Turkish (tr)
• Ukrainian (uk)
• Uzbek (uz)
• Vietnamese (vi)

If a locale is not listed above and you need it for your implementation, contact our support team to get it added to the list.

Customization Options

Prelude provides a few options to customize the verification message content sent to your users.

These options may not be available on channels other than SMS. Availability depends on the selected channel.

To find information about branded sender IDs, see the Custom Sender ID documentation.

Brand Suffix

You can add a brand suffix to the verification message from the Prelude dashboard.

12345 is your verification code for Acme Inc.

Best practices:

1. Avoid setting a brand suffix that includes a link or text that could be interpreted as a link. Carriers may block messages that contain links.
2. Do not include any special characters such as emojis. Some carriers may block messages that contain special characters, or you might be charged more for the message.

This feature is subject to prior approval. Contact our support team to enable it on your account free of charge.

Brand per request

If you send verifications for several brands, you can set the brand of each verification with the options.brand parameter on the POST /v2/verification endpoint. The brand passed on the request overrides your brand suffix, for this verification only.

{
  "target": {
    "type": "phone_number",
    "value": "[phone]"
  },
  "options": {
    "brand": "Acme Inc"
  }
}

12345 is your verification code for Acme Inc

Leading and trailing spaces are removed from the brand. An empty brand is ignored and the message uses your brand suffix.

The brand follows the same rules as the brand suffix: it has 1 to 30 characters, it uses only letters, digits, spaces and ' & - !, and it must not look like another company or a public institution. Inside the brand, only plain spaces are allowed: line breaks, tabs and other space characters are refused. An invalid brand returns a 400 error with the invalid_brand code.

A request on the same phone number with the same brand is a retry of the open verification, as usual. A request with a different brand, or without a brand when the open verification has one, starts a new verification, so the user always receives the brand you asked for. The code of the previous verification can no longer be checked.

When the brand per request is not enabled on your account, or the brand suffix is not enabled, options.brand is ignored and the message uses your usual settings. In countries that do not support a brand suffix, the message does not show a brand.

The brand per request also applies when the request uses one of your own templates with template_id. The brand suffix settings of that template decide whether the brand is used, and options.brand has priority over the brand suffix of that template. The options.variables you send are not changed. Built-in templates such as prelude:psd2 ignore options.brand.

This feature is subject to prior approval. It also requires the brand suffix to be enabled on your account, or on the template you send with. Contact our support team to enable it on your account free of charge.

Security Suffix

You can add a security suffix that reminds users not to share the verification code with anyone.

12345 is your verification code. Do not share it.

This feature is subject to prior approval. Contact our support team to enable it on your account free of charge.

Built-in Templates

For certain use-cases, we provide built-in templates that you can use to send verification messages.

PSD2

The Payment Services Directive 2 (PSD2) is a European regulation that aims to make online payments more secure. The Verify API provides a built-in template for sending verification codes for PSD2 transactions.

{
  "target": {
    "type": "phone_number",
    "value": "[phone]"
  },
  "options": {
    "template_id": "prelude:psd2",
    "variables": {
      "description": "Fluffy Unicorn",
      "amount": "99999.99",
      "currency": "EUR",
      "recipient": "Rainbow LLC"
    }
  }
}

Variables

Variable	Type	Description
amount	string	Decimal amount of the transaction.
currency	string	ISO 4217 currency code (3 letters).
recipient	string	Payee name displayed to the payer. Capped at 35 characters in strict PSD2 mode.
description	string	Short description shown alongside the transaction. Capped at 140 characters in strict PSD2 mode.

Dynamic linking at verification time

PSD2 SCA RTS Article 5 requires the authentication code to be linked to the transaction’s amount and payee, with any change to either invalidating the code. For PSD2-issued codes, you must resubmit the variables provided at issuance as a psd2 block on the check endpoint:

{
  "target": { "type": "phone_number", "value": "[phone]" },
  "code": "123456",
  "psd2": {
    "amount": "99999.99",
    "currency": "EUR",
    "recipient": "Rainbow LLC"
  }
}

On a PSD2-issued code, omitting the psd2 block returns status: "transaction_missing", and submitting a block whose variables differ from issuance returns status: "transaction_mismatch".

Verification code length

You can set the verification code length either:

1. Through the Prelude dashboard.
2. By setting the options.code_size parameter on the POST /v2/verification endpoint.

The code length can be between 4 and 8 characters.

options.code_size · integer

The length of the verification code sent to your users.

Custom verification codes

Although Prelude can generate a code for you, you can also generate your own custom verification code. This is useful when:

1. You use a multi-provider setup where you can attribute which provider converted the user.
2. You want to drop Prelude into an existing verification flow.
3. You need to use alphanumeric characters in the code (subject to Prelude’s approval).

This feature is subject to prior approval. Contact our support team to enable it on your account free of charge.

If you just want to use codes of a variable length, you can use the options.code_size parameter on the POST /v2/verification endpoint.

How to use custom codes in your verification flow

To use a custom code for your verification flow, set the options.custom_code parameter to the code you want to use on the POST /v2/verification endpoint.

options.custom_code · string

The custom code you want to use. The code needs to be a string of 4 to 8 numeric characters.

Prelude will then send the message with this custom code to the user.

Caveats

To ensure optimal performance:

1. Send a different custom code for each verification request or retry.
2. Always call POST /v2/verification/check to verify the code when the user enters it.

Prelude uses the custom code to identify which provider converted the user. If you reuse the same custom code across multiple verification requests, Prelude will not be able to determine which provider converted the user and will not be able to attribute the conversion to a specific provider, which reduces the effectiveness of routing optimization for your account. You can read more about the multi-routing system here.

Don’t send a custom code for a test number: no message is sent for those, and only the code configured on the number itself is accepted, so the custom code is ignored.

Alphanumeric custom codes

Prelude supports alphanumeric custom codes.

This feature is subject to prior approval. Contact our support team to enable it on your account free of charge.