Before sending a message

Successfully send and receive messages

Getting started

Message API calls are sent to the /messages endpoint regardless of message type, but the content of the JSON message body differs for each type of message (text, image, etc.).

You will see how to send each message type in its specific documentation.

Opt-in

Always ask for an active opt-in from the user. Any communication from the WhatsApp endpoint requires an active opt-in. "Active" means that it must be triggered by a user action, such as entering a phone number or checking a box to indicate consent (please consult the Opt-In requirements).

Sending messages to users without an opt-in may result in users blocking your business and suspension of your Whatsapp business account.

Requirements

Opt-ins must be collected before you initiate a conversation with a customer using WhatsApp. It is your responsibility, as a business, to obtain customer opt-ins and to ensure your opt-in policy complies with all laws applicable to your communications.

Business-initiated messages must be approved Message Templates. Any Message Template must comply with applicable laws and WhatsApp policies, and only be used for its designated purpose

Businesses must follow the below requirements when obtaining opt-in:

Opt-in good practices

• Users should expect the messages they receive. Set this expectation by:

  • Obtaining an opt-in that encompasses the different categories of messages that you will send (ex: order updates, relevant offers, product recommendations, etc.).

  • Obtaining separate opt-in by specific message category. This mitigates the risk that users will block your business because they receive unsolicited messages.

• Provide clear instructions for how people can opt out of receiving specific categories of messages, and honor these requests.

• Ensure your opt-in and opt-out flows are clear and intuitive for users.

• Clearly communicate the value of receiving this information on WhatsApp.

• Monitor your quality rating, especially when rolling out new opt-in methods.

User reporting

WhatsApp has a reporting and blocking mechanism that gets activated when the user receives a message without reaching out before (in a notifications case). If the user is unaware of receiving notifications this might lead to an increase in blocked numbers or users that want to opt-out.

The best way to avoid user reporting while starting campaigns via WhatsApp is ensuring there is a clear and easy opt-out in the template message, so the user can easily opt-out instead of reporting or blocking your number.

User reporting leads to low quality rating of the number, which leads to lower messaging limits, accounts restrictions and eventually the account being blocked from the WhatsApp Business API.

WhatsApp allows users to report spam or to even block the number - a quality signal

Businesses should create and send notifications with the below attributes in mind to drive a high-quality user experience:

• Expected: People have already opted in to receive this information from the business over WhatsApp so are not surprised when the business messages them

• Relevant: The messages are personalized to the specific person (Ex: based on recent purchases or recent engagement with the business, personalized content in the message itself), concise, contain necessary information, and clearly outline any next steps for the person

• Timely: People receive these messages when they are relevant

Businesses must still get opt-in from their customers and adhere to the Commerce and Business Policies. WhatsApp also recommends following the best practices outlined to drive a high-quality user experience.

Deep & Universal Links

https://wa.me/<YOUR_WABA_PHONE_NUMBER>?text=<YOUR_START_MESSAGE> will take the user straight into WhatsApp (if it's installed) or to a landing page hosted by WhatsApp (if it's not installed).

Please ensure that the user has opted in.

Deeplinks

• whatsapp://r - account confirmation link - which doesn't seem to work on iOS

• whatsapp://send - contact picker

• whatsapp://chat - HomeActivity

• upi://pay - payments

*Universal Links

• http[s]://v.whatsapp.com - verify SMS deeplink

• http[s]://api.whatsapp.com- text and direct chat deeplink

• http[s]://wa.me- text and direct chat deeplink

• http[s]://chat.whatsapp.com - accept invite link deeplink

We highly recommend using Universal Links and not Deeplinks.

Contact validation

• Ensure that you only pass phone numbers consisting of digits, no leading zeros and a country prefix - use an E.164 format validation.

The E.164-formatted version of a phone number is the only unique identifier that is available. It's sometimes referenced as wa_id. Don't get fooled in thinking that the wa_id is an internal identifier by WhatsApp that is linked to a user profile and may survive (re-)installs of the WhatsApp consumer client using different phone numbers. That's an urban legend.

• Use a phone number validation library such as Google's phonelib or a number database such as Numverify, RealPhoneValidation or others to validate that the given number is well-formatted and that it should be valid; consider exceptions for Mexico and Argentina.

• There is no dedicated endpoint for contact validation. Instead, the wa_id is obtained as part of the successful response to a sent message (text message or template message).

  This means that WABAs should always have a simple "start conversation" template message registered and trigger it whenever they need to send a message to a new contact.

  Successful Response:

  {
    "messaging_product": "whatsapp",
    "contacts": [{
        "input": "PHONE_NUMBER",
        "wa_id": "WHATSAPP_ID",
      }]
    "messages": [{
        "id": "wamid.ID",
      }]
  }

  If the template message fails, it could be due to an incorrect/invalid phone number (Error 131026).

Code	Description	Possible Solutions	HTTP Status Code
131026 Message Undeliverable	Unable to deliver message. Reasons can include: The recipient phone number is not a WhatsApp phone number. Recipient has not accepted the new Terms of Service and Privacy Policy. Recipient using an old WhatsApp version; must use the following WhatsApp version or greater:	Confirm with the recipient that they agree to be contacted by you over WhatsApp and are using the latest version of WhatsApp.	400 Bad Request

We recommend parsing your webhook to identify this error, allowing you to recognize that the message was undeliverable due to an invalid phone number.

This helps you avoid unnecessary requests or actions associated with that phone number.

Message sending

• Manage cut-off control (don't send messages other than templated-based messages if there is a 470 response).

Trying to send messages (other than template-based messages) to users who have not sent in a message is one of the most common errors - even for experienced developers and testers. Make sure you send in a test message to your WhatsApp for Business number before you start testing.

• Don't send text messages with more than 4096 characters.

• If you intend to benefit from URL-unfurling and you set preview_url to true the text message must contain a valid URL.

• Make sure that the file type is supported by WhatsApp and that the file size doesn't exceed given limit:

  • video files must have an audio track

  • audio and video files will require codecs supported by WhatsApp.

• Messages with media It is advised to consider sending media messages using media_id as media can be uploaded once and reused multiple times.

• Messages with linked media If the same link is reused for multiple messages it is recommended to upload the media at link directly to the API /media endpoint and reuse the relevant media id for messaging. Under certain conditions, reused links can result in increased storage being used to store downloaded media items.

• Private links for media If the use-case requires non-publicly accessible links for use in media messaging, it is recommended to setup/use a provider as documented here: https://developers.facebook.com/docs/whatsapp/api/settings/media-providers

• Add a wa_id to the phones-object when the user receiving a contact shall be able to save it to the phone.

  "phones": [
                          {
                              "phone": "[phone]",
                              "type": "HOME"
                          },
                          {
                              "phone": "[phone]",
                              "type": "WORK",
                              "wa_id": "16505551234"
                          }
                      ]

  When you send a phone number without a wa_id it's only possible to "invite" users. If the wa_id (=E.164-formatted version of the phone number) is given, the WhatsApp client will allow to "add a contact" and "send a message" which might come in different flavours on Android and iOS.

• Implement the typical error scenarios mentioned in the FAQ.

• Implement handling for the quality limit - "warm up" the number when sending template-based messages; there will be a capping when the quality limit has been reached and the number will be switched to "Restricted" by Facebook for 24h.

• Make use of message formatting: bold (*), italics (_), ~strikethrough~ (~) and mono-space (```).

Latency issues

Respect that WhatsApp might have latencies in their network or that the user's device or app install might have issues which might impact message delivery. Possible reasons for delays seem to be device and/or network related, which is not in our hands. See:

• Troubleshooting guide by WhatsApp

• Reddit articles on delayed message delivery

• How to speed up the WhatsApp client

• Reasons for delayed, incoming messages

• Slow connectionss

Typical fixes include:

• resetting the cache on the WhatsApp consumer app

• resetting the network connection

• killing and restarting the WhatsApp consumer app

• ensuring that there is enough RAM available for the WhatsApp consumer app

• saving the contact in the address book you are trying to reach

Callback handling

Only asynchronous handling of callbacks - acknowledge first, then process

Never process incoming messages and notifications in the callback handler.

Use valid SSL-certificates for the callback endpoint - the certificates must support TLS1.3, the certificate chain must not be broken.

Use SSLlabs to test the SSL-certificate.

Make sure that the DNS-entry of the callback endpoint is propagated and registered with official DNS-servers (ex. 8.8.8.8).

Chatbot integrations

Have a standard response while the service is not fully active: "Thank you very much for contacting us. Please note that this service is not yet fully operational. We plan to officially start on yyyy/mm/dd. Thank you for your patience."

Review that your chatbot does meet these minimum standards:

• Branding

  • Brand consistency: Does it look and feel like the company? Does it look out of place?

  • Conversational: Is the bot appropriately conversational? Does it use small talk, greet, engage?

  • Language consistency: Does the bot use language and phrasing that is consistent with the brand's website and image?

• Performance

  • Purpose: Is it clear what this bot is meant to do? Can you tell what the One True Goal is? Effectiveness: Is it effective at its job? Does it provide the right help? Knowledge: Can it answer common questions around the task it was built to perform? Can it help the user?

  • Feedback: Does it let the user know they are progressing towards their goal?

• Consistency

  • Doing its job: Can the bot consistently help the user achieve their goal? Journey consistency: Does the path the bot takes users on fit the expected path the company would take them on?

  • Up to date: Is the bot up to date?

  • Knowledge: Does the bot have a consistent amount of knowledge across the different topics it touches on?

• Humanity

  • Transparency: Does it pretend to be a human? Is it transparent and honest about being a machine?

  • Self-aware: Can it answer questions about itself? Does it know and is it open about its limitations?

  • Reaching humans: Can it hand conversations over to its human colleagues gracefully? Does it inform the users on how to skip straight to a human?

WhatsApp requires a human escalation path when using automation (chatbot), if an issue can't be resolved. Valid escalation paths include human agent handoff in thread, phone number, email or web support form or prompting an in-store visit.

Other

• Read the official FAQ.