メニュー

Expand
ページを評価:

Send WhatsApp Notification Messages with Templates

Twilio's support for the WhatsApp Business API is now Generally Available! Read more in the Changelog.

Non-transactional templates are now allowed for businesses registered in the Mexico and Indonesia in FB Business Manager. This includes marketing and promotional templates.

WhatsApp Message Templates Overview

A WhatsApp message template is a message format that you can use over and over again to message users once they have opted-in and given your app permission to send them messages. To use a message template, you must first submit it to WhatsApp. WhatsApp reviews and approves each message template, typically in 48 hours or less, to maintain high-quality content and avoid spam in the ecosystem. Once WhatsApp has approved your template, you can use the templated message to send notifications.

Template messages use placeholder values that can be replaced with dynamic content inside double curly braces ({{...}}) when the message is sent:

  • “Your login code for {{1}} is {{2}}.”
  • Example of a message sent using this template: “Your login code for Twilio is 12345.”

Think of your template message as a conversation starter; the goal is to convert this initial message into a two-way conversation when the user replies. Two-way conversations are considered higher value because you are engaging with your end-user. In addition, they reduce your spend because WhatsApp does not charge for outbound messages within the 24-hour session. (For more information on pricing, please see our pricing page.)

Sending Non-Template Messages Within a 24-hour Session

If a WhatsApp user has sent your application a message - whether it is a reply to one of your outbound messages, or they have initiated communication themselves - your application has a 24-hour window (sometimes called a "24-hour session") to send that user messages that don't use a template. For the 24 hours following the last message sent to your application by a WhatsApp user, your application can reply or send outbound messages to that user without using a template.

When your application sends a message to a WhatsApp user outside a 24-hour session, the message must use an approved template.

Templates pre-registered for the Sandbox

Twilio has pre-provisioned for the following templates for use in the WhatsApp Sandbox:

  • Your {{1}} code is {{2}}
  • Your {{1}} appointment is coming up on {{2}}
  • Your {{1}} order of {{2}} has shipped and should be delivered on {{3}}. Details : {{4}}

(Read our guide to getting started with the Twilio Sandbox for WhatsApp.)

WhatsApp Notification categories

Your WhatsApp message templates must fall into one of the following categories. Templates that do not align clearly with these template types are more likely to be rejected by WhatsApp in the template approval process described below.

  • Account Update: Let customers know about updates or changes to their accounts.
  • Alert Update: Send important updates or news to customers.
  • Appointment Update: Send confirmations, reminders, or other updates to customers about their appointments.
  • Auto-Reply: Send auto-replies to customers when your business isn't online or available to respond right away.
  • Issue Resolution: Respond to questions, concerns, or feedback from customers about your business.
  • Payment Update: Send a message to customers about their payment.
  • Personal Finance Update: Send a message to customers about their personal finances.
  • Reservation Update: Send confirmations, reminders, or other updates to customers about their reservations.
  • Shipping Update: Send shipping updates to customers about their orders.
  • Ticket Update: Send ticketing information or updates to customers.
  • Transportation Update: Send transportation information or updates to customers.

Creating Message Templates and submitting them for Approval

Customers interested in sending Notifications outside of the 24-hour window need to create their own templates for these messages.

Set up WhatsApp Message Templates on your Twilio Account

To create a template, go to Twilio Console > Programmable SMS/Messaging > Senders > WhatsApp Templates. Click on "New message template."

whatsapp_add_new_message_template_console.png

On the next screen, you will be able to fill out information to submit to WhatsApp. WhatsApp's team uses the information you submit to approve or reject your template submission.

Please note: Once you submit a template, it cannot be edited or deleted through the Twilio console. If you need to delete a template, please reach out to help@twilio.com.

  • Template name: Must be a unique name and can only contain lowercase alphanumeric characters and underscores. Tip: Use a name that helps WhatsApp's reviewer understand the purpose of your message, for example "order_delivery" rather than "template_1".
  • Template category: Select the one that best fits your use case.
  • Message language: Select from the languages provided by WhatsApp.
  • Message body: The text of the message that you want to send

whatsapp_template_submission_form.png

After you fill out the message template, click "Submit Message Template," and the template will be sent to WhatsApp for approval. All templates must be approved by WhatsApp before you can use them for messaging users. (See tips and guidelines in the next section.)

Please refer to the WhatsApp documentation to learn more about message template formatting and supported languages.

Template Translations

Twilio supports multiple translations per template. If you need the same template in different languages, click "Add template translation" on an individual template's view in console. Translations have higher chance of approval if submitted together.

Please note that WhatsApp does not support editing or deleting individual translations within a template. If you need to resubmit a translation, you must submit it as another new template.

Message Template Approval Criteria

WhatsApp supports up to 250 templates per account by default. We recommend starting with a handful to get started faster. If you need more than 250 templates, please open a support ticket stating your reason. WhatsApp reviews requests within 2-4 weeks and may approve a higher limit of 1500 templates at their discretion.

First, please note that the following is not allowed on WhatsApp’s Business API:

  • Marketing or promotional content: This includes any offers, coupons, free gifts, upselling, cold call messages and/or surveys to collect data. Certain words that may make the template sound promotional may also cause it to be rejected. Note: As of October 15, 2020, this rule does not apply to businesses registered in Mexico and Indonesia in the Facebook Business Manager.
  • Subscription messages: Subscription content, including newsletters or blog post alerts, are not allowed on WhatsApp.

Your template text should make it clear to the user why they received your message. You can remind them of the reason why they originally granted you permission to send the messages. For example: “Hi {{1}}, thanks for your order {{2}} placed on {{3}}. Your order has shipped. You can get a tracking update any time by replying TRACK.”

Here are some guidelines for increasing the odds of getting your templates approved:

  • Placeholders must have double curly braces, such as {{1}}; single curly braces will not work.
  • Templates must have a specific, self-evident purpose. For example: “{{1}} {{2}}” would be rejected because it could be abused to spam users. You need to surround the parameters with information so it is clear what type of information will be inserted.
  • Templates should be concise and convey only the necessary information that aligns with the template category. We suggest getting feedback from others to ensure that the template text is clear.
  • Templates must not have any grammatical or spelling mistakes. Templates that include even minor spelling or grammatical mistakes are likely to be rejected by WhatsApp.
  • Templates should be tagged with the appropriate category and language.
  • If you need to write a template to re-open the 24-hour window, we suggest starting with some mention of the previous thread. Examples: "I'm sorry that I wasn't able to respond to your concerns yesterday but I’m happy to
    assist you now. If you’d like to continue this discussion, please reply with YES".

Including links in your templates

You may send URLs in a template, e.g., “Thanks for registering with My Business. To continue click on https://app.example.com

If you have an Official WhatsApp Business Account, recipients will see a link preview in the message.

If you have another type of WhatsApp Business Account, recipients will not see a link preview if they have not added the business to their contact list. Recipients can add your Business Account as a contact by clicking the "Add as a Contact" button in the WhatsApp interface. As soon as they do this, the link previews will retroactively appear, and all future links will also display previews.

The Approval Period

Typically, templates are approved by WhatsApp within 48 hours. If you are experiencing delays, please open a support ticket with Twilio and include the “name” of the template that you created.

Marketing & Promotional Templates in Mexico and Indonesia

As of October 15, WhatsApp is approving non-transactional templates for businesses registered in Mexico and Indonesia. This includes templates that WhatsApp deems to comprise promotional or marketing content. To be eligible, businesses must have a Mexico or Indonesia address in the FB Business Manager account that was used to register with WhatsApp (the FB Business Manager ID provided in the Request Access form). To check this business address, go to FB Business Manager > Settings > Business Info.

whatsapp-templates-promotional-template-address-fb-bm

Revising rejected Message Templates

If your message template was rejected, you will see a rejection reason code in the Twilio console specifying why WhatsApp rejected it. You may revise your rejected template and submit a new one to replace the rejected template at any time.

These are the rejection reasons that WhatsApp has disclosed to date:

  • PROMOTIONAL: WhatsApp has deemed this to contain promotional or marketing content.
  • TAG_CONTENT_MISMATCH: The language and/or template category selected don't match the template content.
  • INVALID_FORMAT: Placeholders or other elementse formatted incorrectly.

If you are having a difficulties getting your template approved, it often helps to provide additional detail in your template to make its use evident to WhatsApp. For example, you may add "You asked us to let you know about [Topic]". If you feel your templates are being rejected by mistake and resubmissions continue to be rejected, please open a support ticket explaining the issue in detail. Twilio can request that WhatsApp reconsider the rejected template.

Send a WhatsApp message using a template

Twilio supports sending messages with WhatsApp Message Templates without requiring a change in how you use the Twilio Programmable Messaging API.

To send a templated message, include the full body of the message in the API call. Twilio will send the message as a templated message if it matches one of the approved templates. If the body does not match a pre-registered template, the message will be sent as a freeform message. This means it may not deliver if it is outside a 24-hour session.

For example, if your approved template is:

Hi {{1}}! Thanks for placing an order with us. We’ll let you know once your order has been processed and delivered. Your order number is {{2}}

in the Body parameter of the message resource, you would write the following, replacing the {{1}} placeholder with the end user's information:

Body=“Hi Joe! Thanks for placing an order with us. We’ll let you know once your order has been processed and delivered. Your order number is O12235234”
        
        
        
        

        Encountering Error Code 63016

        Twilio's Error 63016 indicates that you are making an attempt to send a freeform message when there’s no conversation set with that user. This may happen if your text does not exactly match the text from the approved template. Please make sure that you use a diff tool to check for any differences between the approved template and the content being sent (i.e. extra spaces or newlines). If you need to change the template to match your needs, please submit a new template. If you are seeing a different error code and you believe it is related to templates, please open a support ticket, and we will help you understand why this is happening.

        Including new lines and escape characters in your templates

        In addition, if you are rendering new lines or other escaped characters, you will need to encode the linebreaks properly based on the language you are using. The Twilio Console may show line breaks and other escaped characters in their raw form, such as \n. However, if your message body shown on Twilio has "\n" visible in the body contents, you need to check your code to ensure you pass an actual line break character to Twilio.

        Please note: If you are using cURL, you will need to use the following syntax, $'Body=Hello \n world!' with single quotes ($'...') to send newlines. Below is a full example:

        curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
        --data-urlencode 'To=whatsapp:+15005550006' \
        --data-urlencode 'From=whatsapp:+14155238886' \
        --data-urlencode $'Body=Hi, there.\nWelcome to ALVIN instant servicing.\n\nKindly provide your reference number to proceed' \
        -u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token
        

        Initiate the 24-hour window with a generic template

        As a developer, you may want to send different types of notifications and messages to your users. However, it is difficult and inefficient to go through the template approval process described above for each type of message that you wish to send to your end users.

        For example, let's say you want to send out a time-sensitive message to all of your end users, such as "Today, we are having a company-wide announcement at 11am." It is unlikely that WhatsApp will approve this template, which makes it challenging to build a real notification flow.

        The Solution: To work around this problem, you can create a generic template that asks your users to respond. An example of generic notification template that you can submit for approval is:

        "Hello {{1}}, we have a new update regarding your account. Please respond to this message to receive it. Have a nice day!"

        Once your end user replies to this templated message, it initiates the 24-hour session, during which your business can send free-form messages.

        Examples of Approved and Rejected Message Templates

        Examples of Approved Message Templates

        • Welcome {{1}}. What company do you work for?
        • Your {{1}} appointment is coming up on {{2}}.
        • Your {{1}} appointment is coming up on {{2}}. Reply with {{3}} or {{4}}
        • Unfortunately your pending booking did not go through.
          No charges were made to your bank account.
          You can try to rebook the hotel again.
          We sincerely apologize for the inconvenience.

        Examples of Rejected Message Templates

        The following templates don't provide sufficient detail on how they will be used:

        • Reminder: {{1}}
        • {{1}} was added
        • {{1}}, {{2}}!

        The following templates are considered promotional or spam, as they do not make it clear to the user why they are receiving this message:

        • I am Jenn, the virtual assistant.
        • We will put our platform up and running soon, I would like to get to know you better by asking 5 questions.
        • Do not worry, I will not share your answers with anyone.

        These message templates contain promotional content:

        • Rejected: Ready! Thank you for your purchase of {{1}}. You can find your receipt at {{3}}. Download the App and get a $10 credit {{4}}.
        • Revised and approved: Thank you for your purchase of {{1}}. You can find your receipt at {{3}}.

        • Rejected: Hi {{1}}! Not sure how to activate your Prepaid Card? It is quick and easy! Get your new Prepaid Card in your pocket and start to enjoy all the advantages! Access at {{2}}.
        • Revised and approved: Hi {{1}}! Our records show that your new Prepaid Card is delivered. Reply “ACTIVATE” to activate your card now.

        These message templates are promotional by nature and cannot be approved for user in WhatsApp as a template:

        • Rejected: “...trying to touch base with you over text as I couldn't connect with you either by phone or email...”
        • Rejected: Thank you for your booking. Now refer your friends and earn credits. Ask your friends to book with code {{1}}.

        関連トピック

        Ready to create your own WhatsApp templates? Head over to the Twilio Console to get started.

        ページを評価:

        ヘルプが必要ですか?

        誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。

              
              
              

              フィードバックくださりありがとうございます!

              We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

              Sending your feedback...
              🎉 Thank you for your feedback!
              Something went wrong. Please try again.

              Thanks for your feedback!

              Refer us and get $10 in 3 simple steps!

              ステップ1

              Get link

              Get a free personal referral link here

              ステップ2:

              Give $10

              Your user signs up and upgrade using link

              ステップ3

              Get $10

              1,250 free SMSes
              OR 1,000 free voice mins
              OR 12,000 chats
              OR more