Guides

Keyword

A Keyword Automation is a text message-based marketing strategy for engaging mobile users through predefined keywords. Users send a keyword via SMS, WhatsApp, or RCS to a shortcode, long code, or phone number. The platform triggers an automated response.

Short-code (4-6 digits): Short codes handle promotions, alerts, and two-factor authentication. Companies use short codes exclusively with SMS for:

  • Marketing promotions: To send ads, coupons, sales alerts, and other promotional information. US-based businesses require a short code to send marketing texts.
  • Two-factor authentication: This is because a message sent via an SMS short code is likely to be delivered more quickly.

For example:

Send 'Mammoth' to 12345 and receive an alert for Mammoth Resort.
Keyword: Mammoth
Short-code: 12345

Long code (10 digits): A long code number is a standard phone number used to send and receive voice calls and text messages. Typically, a long code is used by courier companies, banks, airlines, and other service sectors for customer service-related communication. Common use cases include:

  • A courier company could use a long code to inform a customer that their package is out for delivery.
  • A bank could text clients their account balance every month.
  • An airline can reply to a passenger's seat preference request.

Keyword Automations easily engage potential customers with targeted offers and deliver information straight to their mobile devices via mass text messaging.

You complete three steps to set up a Keyword Automation:

  1. Delivery
  2. Keyword
  3. Summary

Delivery

You define the delivery channel and automation recipients.

Currently, three delivery channels are available for the Keyword Automation:

The Delivery section covers delivery channel selection.

Keyword

In this step, you create interactions based on predefined keywords and associated response messages. You add webhooks to each interaction to track participant engagement.

Creating interactions involves:

  • The definition of the interaction, which includes keyword reception and the ensuing message, and
  • Event triggering capabilities via webhooks

  1. Interaction Label: First, enter the name of the Interaction in the Interaction Label text field. This identifies each interaction you create. Example: FreeTrialOffer or NewsletterSignup.

  2. Keywords: Enter the keywords that will trigger an automated response for this interaction. You add one or more keywords to an interaction. Multiple keywords per interaction help you determine which elements receive more engagement.

    You keep keywords short, simple, and relevant to your automation. For example, a keyword automation for a free trial of your service could use the keyword TRIAL. Special characters such as !, @, #, and $ cause confusion during entry and are not recommended.

    Keywords are not case-sensitive, so Trial and TRIAL are equivalent. Keywords used in other automations appear highlighted in red, as shown below.

    Keywords must be unique within an automation. If TRIAL is used in one automation, it cannot be reused in another automation for the same shortcode.

    📘

    NOTE

    A keyword and its corresponding platform engagement entity are unique. For example, say the 12345 shortcode is being used in a automation with the keyword "TRIAL". Creating a different automation with the shortcode 12345 and the "TRIAL" keyword would create a conflict with the existing automation. Hence, this condition is not allowed.

    You can have up to 30 keywords, and each keyword accepts up to 29 characters. To keep track of the number of keywords in use, at the bottom right corner of the Keywords section is a keyword counter.

    The Message section will be aligned with the channel type used in the automation, SMS, RCS, or WhatsApp, and with the features allowed in each of them.

    The Keyword Automation supports regular expressions (regex) for flexible input validation on user interactions. You define keyword patterns that match various text inputs, ideal for formats such as ID numbers or phone numbers.

    Example: Validating a National ID Format

    Suppose you want users to submit their national ID as part of a keyword interaction. The required format is that the ID must start with the letter "C" (uppercase only), followed by seven digits. You achieve this using a regular expression.

    Regular Expression -> ^C\d{7}$

    This regex can be used in the Keywords field to validate the following structure:

    • ^ ensures the input starts with..
    • C the uppercase letter C.
    • \d{7} exactly seven numeric digits.
    • $ ensures the input ends there (no extra characters).

    Therefore, the input starts with C, followed by seven digits. When a user sends a message matching this format, the automation is triggered, and the user receives a predefined message such as: "Thanks for sharing your ID."

    • If the user's input matches the regular expression, the system enters the automation flow and delivers the configured response.

    • If the input does not match, the system ignores the message, and no interaction is triggered.\

    📘

    NOTE

    Each keyword or regular expression is limited to 30 characters. Ensure your pattern is optimized and concise.


  3. Message: Enter the response message that users will receive after texting a keyword.

    For example, you create an automation with the JOIN keyword as an invitation. The automation delivers deals and news to customers who join your contact list.

    Participants see the following after sending the keyword JOIN.

    580

    You include a trigger event in your application by defining a webhook.

    The Response Message supports Markdown syntax for text formatting. Basic Markdown options include bold, italics, strikethrough, and monospace.


    📘

    Markdown syntax

    Markdown syntax is a powerful tool that can help you make your messages stand out and capture the attention of your recipients. You can create visually appealing and easy-to-understand messages. making your messages more readable. In the world of short attention spans, properly formatted messages can help ensure that your content is understood and remembered. Therefore, markdown is a lightweight markup language that you can use to add formatting elements to plain text text.

    WhatsApp only supports a limited set of basic formatting options, such as bold, italics, and strikethrough:

    1. Bold Text: To make text bold, place asterisks *around the text. (e.g., *this text is bold*).
    2. Italic Text: To italicize text, use underscores _ around the text. (e.g., _this text is italic_).
    3. Strikethrough Text: To strike through text, place tildes ~ around the text. (e.g., ~this text is Strikethrough~).

    Markdown syntax is supported exclusively for WhatsApp messages and is not available for SMS and RCS.

  4. Use external webhook: Select the webhook checkbox to register the interaction event to your application in real time. That is, the webhook allows you to forward data to your application for further processing.


    📘

    NOTE

    if you opt for WhatsApp as delivery channel and set a Webhook URL go to the Keyword (Webhook WhatsApp) section to know the data displayed on the JSON Payloads that is sent from the platform to your webhook URL.


    • Webhook name: The first step to set up the webhook is to give it a name.

    • POST Method: The platform offers the POST method as the de facto option from the dropdown method menu, a practice of any webhook configuration that allows the transfer of information of a web-based app to another.

    • Webhook URL: The next step is to enter the webhook URL where the data will be received. That is, the data is sent from the platform to a webhook URL, which should be set up to handle the contents provided in the payload.

      For example, each user who sends the TRIAL keyword will generate an event that will be sent to the webhook URL handler in your application. Your webhook URL will receive the information in JSON format as follows:


      {
  "date": "2020-10-22T20:29:57.453673Z",
  "owner": "[email protected]",
  "origin": "8641",
  "callback": "http://www.mycallback.com/",
  "externalId": 8,
  "id": "1abc2def3ghi4jkl",
  "text": "TRIAL",
  "user": "+580000000005"
}

      Inspired by the format used by JavaScript to declare objects — collections of keys and values like, for example, "text": "TRIAL".


      KeyValue
      dateUser participation date. The date is represented in UTC timezone.
      ownerAutomation owner.
      originCode where the user comes from.
      callbackSignature of the invoked method.
      externalIdProcess identifier.
      idUser identifier generated by the operator.
      textThe keyword the user sent to participate in the automation.
      userUser mobile number who participated in the automation.

      The information provided includes the keyword that triggered the event, as well as the user's number, which can be used to keep track of users who interacted with the automation and who may have opted in temporarily for this automation by sending the TRIAL keyword.

  5. Add Interaction: Select Add Interaction at the end of the current interaction to add another one.

    📘

    NOTE

    There are no limits to the number of Interactions you can add to a automation.

  6. Delete Interaction: To delete an interaction, select Delete Interaction immediately under the external webhook checkmark.

After the Keyword Configuration step is complete, you select Next to proceed to Summary.

Summary

The Summary step provides an overview of the automation settings before activation.

The step includes the following elements:

  • Delivery Channel: Type of channel (SMS, WhatsApp) through which the automation was sent.
  • Sender: According to the sender type selected during automation setup, it is used as the sender of the notification message. Each delivery channel has its own sender type (Sender number, Sender WhatsApp Business Account, RCS).
  • Components: Type of components of which the interactive automation is composed: Automation type.
  • Automation Activation: Set the automation delivery date (Live [Available if you set as delivery channel the SMS WhatsApp or RCS], Save as Draft).

The Summary section in the Automation Elements covers Summary step settings.