Best Practices
Successfully send and receive messages
Consent flows support both brand and user-initiated conversations. Customer success management can share know-how on how you can create widgets and descriptions for Desktop Web, Mobile Web, e-mail, print to drive users into the messenger, ensuring that the opt-in gets captured and stored.
The MT-Flow (mobile-terminated) is intended for Desktop users where it's not clear if they have installed the app. Users check the box and enter their phone number. In e-Commerce solutions, the phone number might be already available - it can be pre-populated. The consent management would then send a welcome message (aka Welcome MT) to the given phone number.
The MO-Flow (mobile-originated) is intended for users who reach out on their own, by following a link to WhatsApp Web, by scanning a QR-code, or by typing in or sharing the phone number. In the user-initiated chat session, the consent management will first ask the user to agree on the terms & conditions. If the user agrees, the conversation can continue, if the user disagrees, then his profile and the incoming message get deleted.
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.
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. Try to get the Official Business Approval to show your brand instead of the WhatsApp number.
WhatsApp allows users to report spam or to even block the number - a quality signal
Try to get started with MO-flows and send your business contact, so the customer can store it on his/her phone. This will improve the user experience and will reduce the risk of being flagged.
Send contact card early in the process
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.
If you check too many phone numbers without sending anything to them, you will be banned.
Exclude users from future messaging if there is no delivery notification
Currently, there is no way to see how many or which users have blocked your business. The best indicator would be to listen for status callbacks and if you do not receive the delivered status, then either the user has blocked your business or they do not have a network connection. See the Webhook documentation for more details.
- 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 to the API /v1/media endpoint 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 /v1/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.