Before sending a message
Successfully send and receive messages
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.
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.
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:
- 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.
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
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 iOSwhatsapp://send- contact pickerwhatsapp://chat- HomeActivityupi://pay- payments
*Universal Links
http[s]://v.whatsapp.com- verify SMS deeplinkhttp[s]://api.whatsapp.com- text and direct chat deeplinkhttp[s]://wa.me- text and direct chat deeplinkhttp[s]://chat.whatsapp.com- accept invite link deeplink
We highly recommend using Universal Links and not Deeplinks.
- 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_idis 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",}]}
Code | Description | Possible Solutions | HTTP Status Code |
|---|---|---|---|
131026Message Undeliverable | Unable to deliver message. Reasons can include:
| Confirm with the recipient that they agree to be contacted by you over WhatsApp and are using the latest version of WhatsApp. | 400Bad 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.
- 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_urlto 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_idto the phones-object when the user receiving a contact shall be able to save it to the phone."phones": [{"phone": "+1 (940) 555-1234","type": "HOME"},{"phone": "+1 (650) 555-1234","type": "WORK","wa_id": "16505551234"}]When you send a phone number without awa_idit's only possible to "invite" users. If thewa_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 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(```).
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:
Typical fixes include:
- 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
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.
Make sure that the DNS-entry of the callback endpoint is propagated and registered with official DNS-servers (ex. 8.8.8.8).
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.