Messaging - Create WhatsApp template

This page walks you step-by-step through how to use Telesign Messaging to create a custom WhatsApp template.

Before you begin

1. Make sure Telesign Messaging is enabled for your account. Contact our Customer Support Team to enable this product.
2. Pricing varies with the destination of the device and the conversation type. Contact our Customer Support Team for more information about pricing.
3. Make sure you have set up a WhatsApp integration with your Messaging account.

Key terms

• Verified template: A template that needs to be approved by Telesign and WhatsApp before it can be used. WhatsApp Templates that initiate a new conversation with a user must be verified.
• Standard templates: A template used to send messages as part of the continuation of an active conversation with a user. These don't need to be verified before you use them with Telesign Messaging, although you must still wait until Telesign confirms the template has been successfully created. An active conversation is one in which no more than 24 hours have elapsed since the last user-initiated message.
• Category: One of a few pre-defined use cases that describes how you intend to use this template.
• Components: Parts of the message content that can be defined in your template.

Layout

At the highest level, the content of your template consists of one or more components arranged like this:

The body component is always required, but the other components are optional.

Variables

The header and body of your template can also include variables. Include a variable name in a parameter value in double curly brackets. When you send a message using a template with a variable, you can include that variable as an additional parameter. You cannot give a variable a name that matches a mandatory parameter for the template.

If you define a variable without a name ( {{}} ), the service assigns a default variable name based on which parameter the variable was included in as well as the order in which it was included:

You can also include a default value when you create a variable, by including it within the curly brackets after the variable name. Separate the variable name and the default value using " : ".

📘

NOTE:

Variables are supported in all templates, not just WhatsApp templates.

The text in the end user's message in this example is rendered as "A message from Viatu for Peter":

"header": {
  "text": "A message from Viatu for {{first_name}}:",
  "type": "text"
}

"message": {
  "whatsapp": {
    "template": "wa_template_1",
    "parameters": {
      "first_name": "Peter"
    }
  }
}

In this next example, the text in the end user's message if the "first_name" parameter is not included at all is rendered as "A message from Viatu for you":

"header": {
  "text": "A message from Viatu for {{first_name : you}}:",
  "type": "text"
}

Components

Each part of the layout has a set of available content type options.

header

This can include either text, media (image or video), a file attachment for the user to download or location to be shown to the user. You can include up to one variable. If you include media or a file for download in the header of a verified template, your request to create the template must also include the URL of a sample file.

Example 1: Message with text header

Example 2: Message with media header

body

This can only include text. This component is required for all templates. You can include any number of variables.

footer

This can only include text. Variables are not supported.

CTA

This can include a click-to-call button, a button that links to a static URL, a button that links to a dynamic URL, or a one-time passcode (OTP). Variables are not supported.

Example 3: Message with click-to-call button

Example 4: Message with link button

For a template with a button that links to a dynamic URL, specify as much of the base path as you want in the template. When you create a message using that template, you can then append more to that path for each message.

{
  "url": "https://viatushop.com/orders?id=",
  "url_text": "Track Order"
}

In this example of a Messaging request using the template above, the rendered URL of the button in the message is https://viatushop.com/orders?id=45390.

{
  "template": "wa_track_order",
  "parameters": {
    "dynamic_url": "45390"
  }
}

Example 5: Message with a one-time passcode and a copy code button

A copy code authentication template allows you to send a one-time passcode (OTP) along with a copy code button to your end users. When a WhatsApp user taps the copy code button, WhatsApp copies the passcode to the clipboard of the end user's device. The end user can then switch to your app and paste the passcode into the app.

When creating the copy code authentication template, only include text that will be shown on the OTP button. All other content such a header, footer, or suggested_reply will be rejected as an invalid request. You must include otp_text because this parameter defines the text next to the copy icon.

{
  "message": {
    "whatsapp": {
      "template": "copy_code_template",
      "parameters": {
        "otp_code": "123456"
      }
    }
  },
  "message_type": "OTP"
}

You can also have Telesign generate the OTP for you as show in the example below.

📘

NOTE:

Your template name must include “telesign_otp” if you want Telesign to generate the OTP for you. For example: "viatu_telesign_otp_wa_template". Contact our Customer Support Team to enable this feature.

{
  "message": {
    "whatsapp": {
      "template": "copy_code_telesign_otp"
    }
  },
  "message_type": "OTP"
}

Example 6: Message with a one-time passcode and one-tap autofill button

A one-tap autofill authentication template allows you to send a one-time passcode (OTP) along with an Autofill button to your end users. When a WhatsApp user taps the Autofill button, the WhatsApp client triggers an activity which opens the end user's app and delivers the password or code to the app.

📘

NOTE:

One-tap autofill buttons are only supported on Android . If you send an one-tap autofill authentication template to a WhatsApp end user who is using a non-Android device, the WhatsApp client will display a copy code button instead. The WhatsApp client performs eligibility checks when it receives an authentication template message. If a check fails, the one-tap autofill button will be replaced with a copy code button.

When creating the one-tap autofill authentication template, only include "Autofill" as the text that will be shown on the OTP button. All other content such a header, footer, or suggested_reply will be rejected as an invalid request. You must include "Autofill" as the otp_text.

Before using one-tap authentication template, you must set up your app so that the app signals the WhatsApp client to expect imminent delivery of a password or code. When an end user using your app requests a one-time password or verification code and chooses for it to be delivered to their WhatsApp number, first perform the handshake, then call our Messaging API to send the authentication template message. (A handshake is an Android intent and public class that you implement but that the WhatsApp client can start.) When the WhatsApp client receives the message, it will perform an eligibility check. If there are no errors, WhatsApp will start the intent and display the message to the end user. When the end user taps the message's one-tap autofill button, WhatsApp automatically loads your app and passes password or code to it.

Requirements for a successful completion of an eligibility check

1. The handshake was initiated no more than 10 minutes ago.
2. The package name in the template matches the package name set on the intent.
3. The app signing key hash in the template matches the installed app's signing key hash.
4. The app has defined an activity to receive the password or code.

🚧

CAUTION:

You must adjust your app where the OTP should be auto-filled at the end in order to have one-tap autofill templates fully supported. Before using one-tap or zero-tap, you must set up your app so that the app signals the WhatsApp client to expect imminent delivery of a password or code. If your app does not perform a handshake before sending the message, or the message fails an eligibility check, the delivered message will display a copy code button instead of a one-tap button.

The Messaging API request for adding a OTP with a one-tap autofill button is the same as that used for the Messaging request for a copy code button.

{
  "message": {
    "whatsapp": {
      "template": "copy_code_template",
      "parameters": {
        "otp_code": "123456"
      }
    }
  },
  "message_type": "OTP"
}

Like Messaging requests with a copy code button, you can also have Telesign generate the OTP for you. Your template name must include “telesign_otp” if you want Telesign to generate the OTP for you. For example: "viatu_telesign_otp_wa_template". Contact our Customer Support Team to enable this feature.

{
  "message": {
    "whatsapp": {
      "template": "copy_code_telesign_otp"
    }
  },
  "message_type": "OTP"
}

Example 7: Message with a one-time passcode with zero-tap authentication

A zero-tap authentication template allows end users to receive one-time passwords or codes via WhatsApp without having to leave your app. When an end user using your app requests a password or code and we deliver it using a zero-tap authentication template, the WhatsApp client simply broadcasts the included password or code so your app can capture it immediately with a broadcast receiver. From end user's perspective, they request a password or code in your app and it appears in the app automatically.

📘

NOTE:

Zero-tap authentication templates are only supported on Android. If you send an one-tap autofill authentication template to a WhatsApp end user who is using a non-Android device, the WhatsApp client will display a copy code button instead. The WhatsApp client performs eligibility checks when it receives an authentication template message. If a check fails, the one-tap autofill button will be replaced with a copy code button.

When creating the one-tap autofill authentication template, only include "Autofill" as the text that will be shown on the OTP button. All other content such a header, footer, or suggested_reply will be rejected as an invalid request. You must include "Autofill" as the otp_text.

Like one-tap autofill button authentication templates, when the WhatsApp client receives the template message containing the user's password or code, WhatsApp perform a series of eligibility checks. If the message fails these checks and it is not able to broadcast the password or code, the message will display either a one-tap autofill button or a copy code button. For this reason, when creating a zero-tap authentication template, we must include a one-tap autofill and copy code button in POST body payload, even if the end user may never see one of these buttons.

Requirements for a successful completion of an eligibility check

1. The handshake was initiated no more than 10 minutes ago.
2. The package name in the template matches the package name set on the intent.
3. The app signing key hash in the template matches the installed app's signing key hash.
4. The app has defined an activity to receive the password or code.

🚧

CAUTION:

You must adjust your app where the OTP should be auto-filled at the end in order to have zero-tap authentication templates fully supported. Before using one-tap or zero-tap, you must set up your app so that the app signals the WhatsApp client to expect imminent delivery of a password or code. If your app does not perform a handshake before sending the message, or the message fails an eligibility check, the delivered message will display a copy code button instead of a zero-tap authentication notification.

The Messaging API request for adding a zero-tap authentication is the same as that used for the Messaging request for a copy code button.

{
  "message": {
    "whatsapp": {
      "template": "copy_code_template",
      "parameters": {
        "otp_code": "123456"
      }
    }
  },
  "message_type": "OTP"
}

Like Messaging requests with a copy code button, you can also have Telesign generate the OTP for you. Your template name must include “telesign_otp” if you want Telesign to generate the OTP for you. For example: "viatu_telesign_otp_wa_template". Contact our Customer Support Team to enable this feature.

{
  "message": {
    "whatsapp": {
      "template": "copy_code_telesign_otp"
    }
  },
  "message_type": "OTP"
}

Interactive

Can include quick reply buttons or an options list for the user to select from. Variables are not supported.

Example 8: Quick reply buttons

Example 8a: Options list (message)

Example 8b: Options list (modal)

You can only include an options list in a standard template, not in a verified template. So you cannot use one to initiate a conversation with an end user.

Category

category is the use case that the template is intended for. The marketing, authentication, and utility categories are for conversations initiated by you and require end user opt-in. "Service" conversations are initiated by the end user and a message sent in response to the user can be of any template category.

authentication templates

Authentication templates allow you to authenticate end users with one-time passcodes to securely access their accounts. You can authenticate end users potentially at multiple steps in the sign in process (e.g., account verification, account recovery, and integrity challenges). Authentication templates include a button to copy the one-time passcode (OTP), making it convenient for your end users to securely authenticate.

Authentication templates must:

• Use a button to copy the one-time passcode (OTP).

• Follow content restrictions: URLs, media, and emojis are not allowed for authentication template content or parameters. Text for the copy code button is limited to a max length of 25 characters.

Example:

• Authentication code — {{1}} is your verification code. For your security, do not share this code.

utility templates

Utility templates relate to a specific, agreed-upon transaction and accomplish one of the following: Confirm, suspend, or change a transaction or subscription. Use utility templates to send account updates, order updates, alerts, and more to share important information. Any template that has a mix of utility and marketing content is a marketing template.

Examples:

• Terminate an existing transaction — "Your order has been canceled; your refund will be processed in 7-10 days"
• Change or update to a transaction — "Your password was changed"
• Account, billing, or payment notification — "Your payment failed, click here to retry"

marketing templates

Send promotional offers, product announcements, invitations for end users to respond or take action, and more to increase awareness and engagement. They do not relate to a specific, agreed-upon transaction and instead may relate to your business, products, or services. Any conversation that doesn't qualify for one of the other categories is a marketing conversation. Any conversation that has a mix of utility and marketing content is a marketing template.

Examples:

• Promotion or offer — "If you buy 2 or more coffees, you’ll get $5 off!"
• Welcoming or closing message — "Thank you for visiting our store, we really appreciate your visit."
• Updates, invitations, newsletters, or recommendations — "Good news! The product you saved is back in stock."
• Request to respond or complete a new transaction — "Thank you for your order. We’d love your feedback. Please click here."

Steps

1. Keep the page Create messaging template open in another window to reference while following these steps.
2. Decide on the content type of each part of the layout of the template based on the options above.
3. Decide on the category of the template.
4. Make a request to the Create messaging template endpoint like this:

POST /v1/omnichannel/templates HTTP/1.1
Content-Type: application/json
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Host: rest-ww.telesign.com
{
  "name": "wa_bogo",
  "type": "verified",
  "channel": "whatsapp",
  "category": "marketing",
  "content": [
    {
      "body": {
        "type": "text",
        "text": "Buy one get one free! Use code '{{bogo_code}}' at checkout on viatushop.com."
      }
    }
  ]
}

If the request is successful, you should receive a response like this:

HTTP/1.1 200 OK
Server: nginx/1.17.7
Date: Wed, 10 Oct 2022 21:25:54 GMT
Content-Type: application/json
Connection: keep-alive
Allow: GET,POST,HEAD
{
  "status": {
    "code": 3800,
    "description": "Request successful",
    "updated_on": "2022-10-22T21:25:53.765723Z"
  }
}

This response just confirms that the server received your request and is processing it. If the processing and approval (for verified templates) completes successfully, you should then receive a notification to your transaction callback service like this:

{
  "reference_id": "B56259E45884010488343BAA15FB0002",
  "name": "wa_bogo",
  "channel": "whatsapp",
  "language": "en_US",
  "status": {
    "code": 3850,
    "description": "Template successfully created",
    "updated_on": "2022-10-22T21:25:54.181346Z"
  }
}

Search your notifications based on the "name" and "channel" properties; the combination of these two properties uniquely identifies each template. Once you receive this notification, you can begin using this template with Telesign Messaging. See the Templates Callbacks resource in Reference for more details about these notifications.