Sending Message Templates

You can use the /messages endpoint to send message templates to your customers.

Before You Start

Make sure that you have completed the actions in the Messages — Prerequisites documentation.

Step 1: Create Template Using the WhatsApp Manager

Message templates are created in the WhatsApp Manager, which is part of your WhatsApp Account in the Facebook Business Manager. Your message templates will be reviewed to ensure they do not violate WhatsApp policies. Once approved, your business will have its own namespace where the message templates live.

When creating a message template, you must have the following:

1. Message template name — Can only contain lowercase alphanumeric characters and underscores ( _ ). No other characters or white space are allowed.
2. Components of the message template — Fill in the template with the text and/or media components, including parameter placeholders, as required. Make sure it contains no newlines, tabs, or more than 4 consecutive spaces and meets the length restrictions as called out in the Business Manager or WhatsApp Business Management API.
3. All other translations your business desires.

When creating a message template, you can add a sample template by clicking the Add Sample button. This helps us during the review and approval process, so we can understand what kind of message you plan to send. Make sure these are examples and do not include any confidential or personal information.

See Create Message Templates for your WhatsApp Business API Account for more detailed steps for creating message templates.

Examples

Creating a welcome message where the message template name is welcome and the message is

  "Welcome {{1}}. We look forward to serving you on WhatsApp." 

Creating an order confirmation message where the message template name is order_confirmation and the message is

  "Your order {{1}} for a total of {{2}} is confirmed. The expected delivery is {{3}}." 

Translations

WhatsApp does not do any translations for your business. All message template translations must be entered by you in same format described here. The element name is the same for all translations. For more information, see:

• Translations
• Supported languages

Step 2: Make POST Request to /messages

Once you have your template, you can send it to your customers. There are two ways of doing this: using the template or the hsm message template types.

Recommended: Using the template Message Template Type

POST /v1/messages
{
  "to": "recipient_wa_id",
  "ttl": "P4D" | "3600" | 3600, # The "ttl" field will be deprecated in v2.35.
  "type": "template",
  "template": {
        "namespace": "your-namespace",
        "name": "your-template-name",
        "language": {
            "code": "your-language-and-locale-code",
            "policy": "deterministic"
        },
        "components": [{
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "your-text-string"
                },
                {
                    "type": "currency",
                    "currency": {
                        "fallback_value": "$100.99",
                        "code": "USD",
                        "amount_1000": 100990
                    }
                },
                {
                    "type": "date_time",
                    "date_time" : {
                        "fallback_value": "February 25, 1977",
                        "day_of_week": 5,
                        "day_of_month": 25,
                        "year": 1977,
                        "month": 2,
                        "hour": 15,
                        "minute": 33
                    }
                },
                {
                "type": "date_time",
                    "date_time" : {
                    "fallback_value": "February 25, 1977",
                    "timestamp": 1485470276
                    }
                }
            ]
        }]
    }
}

Using the hsm Message Template Type

The hsm parameter contains a namespace and an element_name pair that identify a template and the values to apply to variables in that template. Deprecation of the hsm message template type is planned for a future version.

The following code provides an example of sending a message template. This example uses the purchase_with_credit_card element name within the cdb2df51_9816_c754_c5a4_64cdabdcad3e namespace —the namespace and element_name parameters must match up or the message fails to send.

POST /v1/messages
  
{
    "to": "whatsapp_id",
    "ttl": "P1D" | "86400" | 86400,
    "type": "hsm",
  
    "hsm": { 
        "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e",
        "element_name": "purchase_with_credit_card", 
        "language": {
            "policy": "deterministic",
            "code": "en_US"
        },
        "localizable_params": [ 
            { "default": "$10" }, 
            { "default": "1234" } 
        ]
    }  
}

The resulting message received by the customer looks like this:

You made a purchase for $10 using a credit card ending in 1234.

As you can see from looking at the localizable parameters and the message the client received, the template used the default value of 10 as the amount of the purchase and the default value of 1234 as the last numbers of the account.

Parameters

• Parameters common to all message requests
• Parameters for message templates: template object, components object, parameters object, hsm object, and the language object.
• Language: Language policy options, language object, Localizable parameters.

Step 3: Check Your API Response

A successful response includes a messages object with an id.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}  

An unsuccessful response contains an error object with an error string, error code and other information. See Error and Status Codes for more information.

FAQ