From Bright Pattern Documentation
Jump to: navigation, search
• 5.19

WhatsApp Directives

The following article describes chat directives that can only be used with the WhatsApp integration. There are two types of WhatsApp-specific chat directives:

Template Message Directive
Used to send pre-approved WhatsApp Template Messages. These allow your contact center to initiate conversations with users or send notifications outside the standard 24-hour customer service window.
Interactive Message Directives
Used to send richer, more engaging message types like buttons, lists, product messages, and more. These are generally more cost-effective than template messages but can only be sent within 24 hours of the last message received from the contact.

Template Message Directive

The /template directive allows you to send pre-approved WhatsApp Template Messages, which can include headers, variables in the body, and footers.

Template Usage

The template directive expects the following parameters: 

/template <TEMPLATE_NAME> [-l <LANGUAGE_CODE>] [-h [ "<HEADER_PARAMETER>" ]+] [-b [ "<BODY_PARAMETER>" ]+] [-f [ "<FOOTER_PARAMETER>" ]+]


  • <TEMPLATE_NAME> The name of the pre-approved WhatsApp template.


  • <LANGUAGE_CODE> (Optional) The language code for the template (e.g., en_US, es_MX). Defaults to en_US if omitted.


  • <HEADER_PARAMETER> (Optional) One or more parameters for the template's header (e.g., a media URL).


  • <BODY_PARAMETER> (Optional) One or more parameters (variables) to insert into the template's body text.


  • <FOOTER_PARAMETER> (Optional) One or more parameters for the template's footer


Note that any argument that contains a space character must be enclosed in double quotes ".


Examples:

  • Template usage with header and one body parameter: 
    /template sample_purchase_feedback -l en_US -h https://www.gstatic.com/webp/gallery/1.jpg -b "Apple TV"
  • Template with header and multiple body parameters 
    /template sample_movie_ticket_confirmation -b Cats "10/10/2022 7pm" "Theatre 123" 64h -h https://www.gstatic.com/webp/gallery/1.jpg

Button Templates

The /buttons, /buttons-column, and /choice directives can also be used to send WhatsApp button-type templates by adding the optional <TEMPLATE_NAME> parameter: 

/buttons [-t <TEMPLATE_NAME>] [ <BUTTON_TEXT> ]+
/buttons-column [-t <TEMPLATE_NAME>] [ <BUTTON_TEXT> ]+
/choice [-t <TEMPLATE_NAME>] [ <BUTTON_TEXT> ]+


  • <TEMPLATE_NAME> (Optional) Specify the exact name of an approved WhatsApp button-type template. The number and text of the <BUTTON_TEXT> arguments must match the buttons defined in the template.


  • <BUTTON_TEXT> The text displayed on each quick reply button.


Note that the -t parameter can only be used to call WhatsApp templates consisting solely of a text body and buttons. For more complex templates, use the /template directive.

Interactive Message Directives

All interactive messages are sent using the /interactive directive followed by a JSON payload defining the message structure: 

/interactive { <JSON_PAYLOAD> }

The specific structure of the <JSON_PAYLOAD> is based on the Meta API v19.0, and depends on the type of interactive message you want to send. The following types of interactive messages are supported:

List

Use List messages to present users with a menu of up to 10 options, potentially organized into sections. Tapping the main button reveals the list of choices.

Directive Payload

{
    "type": "list",
    "header": {
      "type": "text",
      "text": "<MESSAGE_HEADER_TEXT>"
    },
    "body": {
      "text": "<MESSAGE_BODY_TEXT>"
    },
    "footer": {
      "text": "<MESSAGE_FOOTER_TEXT>"
    },
    "action": {
      "sections": [
        {
          "title": "<SECTION_TITLE_TEXT>",
          "rows": [
            {
              "id": "<ROW_ID>",
              "title": "<ROW_TITLE_TEXT>",
              "description": "<ROW_DESCRIPTION_TEXT>"
            }
            /* Additional rows would go here*/
          ]
        }
        /* Additional sections would go here */
      ],
      "button": "<BUTTON_TEXT>",
    }
  }


Refer to the Meta API documentation for a detailed description of the List message Parameters.

Reply Button

Reply Buttons can be used to provide up to three simple text buttons below your message, allowing users to quickly respond.

Directive Payload

{
    "type": "button",
    "header": {<MESSAGE_HEADER>},
    "body": {
      "text": "<BODY_TEXT>"
    },
    "footer": {
      "text": "<FOOTER_TEXT>"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "<BUTTON_ID>",
            "title": "<BUTTON_LABEL_TEXT>"
          }
        }
        /* Additional buttons would go here (maximum 3) */
      ]
    }


Refer to the Meta API documentation for a detailed description of the Reply Button Parameters.

Interactive Call-to-Action URL Buttons

Call-to-Action messages include one or more buttons that, when tapped, direct the user to a specified webpage URL.

Directive Payload

{
    "type": "cta_url",

    /* Header optional */
    "header": {
      "type": "text",
      "text": "<HEADER_TEXT>"
    },

    /* Body optional */
    "body": {
      "text": "<BODY_TEXT>"
    },

    /* Footer optional */
    "footer": {
      "text": "<FOOTER_TEXT>"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "<BUTTON_TEXT>",
        "url": "<BUTTON_URL>"
      }
    }
}


Refer to the Meta API documentation for a detailed description of the Call-to-action URL message Parameters.

Flows

Use WhatsApp Flows to initiate multi-screen, structured experiences entirely within WhatsApp, for tasks like appointment booking, lead generation, or filling out custom forms.

Note that you will need to create a flow in your WhatsApp manager account before being able to use this directive.

Directive Payload

{
    "type": "flow",
    "header": {
      "type": "text",
      "text": "<MESSAGE_HEADER>"
    },
    "body": {
      "text": "<MESSAGE_BODY>"
    },
    "footer": {
      "text": "<MESSAGE_FOOTER>"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "<FLOW_TOKEN>",
        "flow_id": "<FLOW_ID>",
        "flow_cta": "<FLOW_CTA>",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_NAME>",
          "data": { <FLOW_ACTION_INPUT_DATA> }
        }
      }
    }
  }
}


Refer to the Meta API documentation for a detailed description of the Flow message Parameters.

Single Product

Showcase one specific item from your linked Meta product catalog using a Single-Product message.

Directive Payload

{
    "type": "product",
    "body": {
      "text": "<BODY_TEXT>"
    },
    "footer": {
      "text": "<FOOTER_TEXT>"
    },
    "action": {
      "catalog_id": "<CATALOG_ID>",
      "product_retailer_id": "<PRODUCT_RETAILER_ID>"
    }
}

Required Elements

  • CATALOG_ID The unique ID for the Facebook catalog linked to your WhatsApp Business Account. You can find this ID in the Meta Commerce Manager. Required for Single Product and Multi-Product messages.
  • PRODUCT_RETAILER_ID The unique identifier (often the SKU) for a specific product within your catalog. To find this ID, navigate to your shop in the Meta Commerce Manager, go to Catalog > Items, and locate the desired product. The ID is displayed below the item's name. Required for Single Product and Multi-Product messages.


Refer to the Meta API documentation for a detailed description of the product message parameters.

Multi-Product

Display a selection of up to 30 items from your catalog, organized into sections if needed, with a Multi-Product message.

Directive Payload

{
    "type": "product_list",
    "header":{
      "type": "text",
      "text": "<HEADER_CONTENT>"
    },
    "body": {
      "text": "<BODY_CONTENT>"
    },
    "footer": {
      "text": "<FOOTER_CONTENT>"
    },
    "action": {
      "catalog_id": "<CATALOG_ID>",
      "sections": [
        {
          "title": "<SECTION_TITLE>",
          "product_items": [
            { "product_retailer_id": "<PRODUCT_RETAILER_ID>" },
            { "product_retailer_id": "<PRODUCT_RETAILER_ID>" }
          ]
        },
        {
          "title": "<SECTION_TITLE>",
          "product_items": [
            { "product_retailer_id": "<PRODUCT_RETAILER_ID>" },
            { "product_retailer_id": "<PRODUCT_RETAILER_ID>" }
          ]
        }
      ]
    }
}

Required Elements

  • CATALOG_ID The unique ID for the Facebook catalog linked to your WhatsApp Business Account. You can find this ID in the Meta Commerce Manager. Required for Single Product and Multi-Product messages.
  • PRODUCT_RETAILER_ID The unique identifier (often the SKU) for a specific product within your catalog. To find this ID, navigate to your shop in the Meta Commerce Manager, go to Catalog > Items, and locate the desired product. The ID is displayed below the item's name. Required for Single Product and Multi-Product messages.
  • Sections must be an array of objects describing each section with a SECTION_TITLE and a product_items array.


Refer to the Meta API documentation for a detailed description of the product message parameters.

Catalog

Send a message that links directly to your entire Meta product catalog and optionally features a specific product as a thumbnail using a Catalog message.

Directive Payload

{
    "type" : "catalog_message",
    "body" : {
      "text": "<BODY_TEXT>"
    },
    "action": {
      "name": "catalog_message",
      
      /* Parameters object is optional */
      "parameters": {
        "thumbnail_product_retailer_id": "<THUMBNAIL_PRODUCT_RETAILER_ID>"
      }
    },

    /* Footer object is optional */
    "footer": {
      "text": "<FOOTER_TEXT>"
  }
}


Refer to the Meta API documentation for a detailed description of the catalog message parameters.

Location Request

Prompt the user to share their current geographic location or manually enter an address using a Location Request message.

Directive Payload

{
    "type": "location_request_message",
    "body": {
      "text": "<BODY_TEXT>"
    },
    "action": {
      "name": "send_location"
    }
}


Refer to the Meta API documentation for a detailed description of the location request message parameters.

Address

Request a delivery address from the user with an Address message, which can be pre-filled if you already have address information for the recipient. Note that this message type has geographic limitations.

Directive Payload

{
  "type": "address_message",
  "body": {
      "text": "<BODY_TEXT>"
  },
  "action": {
      "name": "address_message",
      "parameters": {
          "country": "<COUNTRY_ISO_CODE>"
          /* optional additional parameters */
      }
  }
}


Refer to the Meta API documentation for a detailed description of the address message parameters.

< Previous
Retrieved from "https://help.brightpattern.com/index.php?title=5.19:Chat-directives/whatsapp&oldid=162437"