Client Documentation
Get StartedStatus Page
  • 360Dialog
    • Why you should use 360dialog as Business Solution Provider (BSP)
    • Prices, plans and payment options
  • client hub
    • 360Dialog Client Hub
    • Numbers
      • Manage your WABA
        • Account Statuses
    • Activity
    • Funds
      • Month Closing Invoice (MCI)
    • Payment Management
    • API Keys
    • Template Message Management
    • Partner Change
    • Cancellation
    • Downgrade
  • WhatsApp Marketing
    • Best practices to maintain Account Health and prevent being blocked
    • Driving users to your WhatsApp account
      • WhatsApp Channels
    • Business Search
    • Linking a WABA to a Facebook Page /EN
      • Vinculando uma conta WABA à uma página do Facebook /PT
      • Cómo vincular un WABA a una página de Facebook /ES
    • Linking a WABA to Google Message Ads
    • Ads that Click to WhatsApp (CTWA) /EN
      • Anúncios de Clique para o WhatsApp (CTWA) /PT
        • Como usar o WhatsApp para marketing e vendas? /PT
      • Anuncios que Click to WhatsApp (CTWA) /ES
        • ¿Cómo usar WhatsApp para marketing y ventas? /ES
    • Conversions API (CAPI)
    • Create Ads lookalike audience based on WhatsApp events
    • MM Lite API Beta
      • Onboarding
      • Sending Messages
  • waba basics
    • WhatsApp Business Platform
    • WhatsApp Accounts structure
    • WABA for Government Agencies
    • WABA Policy Enforcement
    • Architecture and Security
    • The Basics (Overview)
    • Webhook Events and Notifications
    • Messaging API
      • Messaging Health Status
      • Step to Step to move to Cloud API
        • [will be deprecated] WABA Integration (On-Premise)
    • Migrating Phone Numbers
      • Migrate number from Meta or alternate BSP to 360dialog Cloud API
      • Migrate a phone number to a new WABA
      • Migrate to alternate BSP
  • waba management
    • Creating new WABA
      • Using a new phone number
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
    • Display Name Guidelines
    • Meta Business Verification
    • Official Business Account (OBA) or blue badge
    • WABA Profile Info
    • Capacity, Quality Rating, and Messaging Limits
      • Accelerated Onboarding
    • Hosting type Change
  • waba Messaging
    • Sandbox (Test API Key)
    • Receiving messages
    • Before sending a message
      • Checklist for Message Broadcasts and Campaigns
    • Conversations
    • Messaging
    • Conversational Components
    • Media Messages
      • Upload, retrieve or delete media
    • Template Messages
      • Template Elements
      • Sending Template Messages
      • Authentication Templates
        • Zero-Tap Authentication Templates
        • One-Tap Autofill Authentication Templates
        • Copy Code Authentication Templates
      • Catalog Templates
      • Product Card Carousel Templates
      • Single-Product Message Templates
      • Coupon Code Templates
      • Limited-Time Offer Templates
      • Multi-Product Templates
    • Interactive Messages
      • Single and Multi Product Messages
      • Location Request Message
    • Flows
    • Products & Catalogs
    • Contacts and Location Messages
    • Payments (India Only)
      • Receive WhatsApp Payments via Payments Gateway
      • Receive WhatsApp Payments via Payment Links
      • Order Details Template Message
    • Payments (Singapore only)
      • Receive WhatsApp Payments via Stripe
  • Partners
    • Partner Documentation
  • Support
    • Help and Support
      • Opening Hours & Response Time
      • Status Pages
      • Meta Support
      • Common Issues
      • How to contact Support
    • Error Messages
    • Imprint & Data Privacy
    • FAQ
Powered by GitBook
On this page
  • Getting started
  • Opt-in
  • Requirements
  • Opt-in good practices
  • User reporting
  • Deep & Universal Links
  • Contact validation
  • Message sending
  • Latency issues
  • Callback handling
  • Chatbot integrations
  • Other

Was this helpful?

  1. waba Messaging

Before sending a message

Successfully send and receive messages

PreviousReceiving messagesNextChecklist for Message Broadcasts and Campaigns

Last updated 1 year ago

Was this helpful?

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 ).

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.

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

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

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.

  • 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

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

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.

    • 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

  • "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 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.

  • 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:

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

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.

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

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

Ensure that you only pass phone numbers consisting of digits, no leading zeros and a country prefix - .

Use a phone number validation library such as or a number database such as , or others to validate that the given number is well-formatted and that it should be valid; .

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

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

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

If you intend to benefit from URL-unfurling and you set preview_url to true the .

Make sure that the doesn't exceed given limit:

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

Implement the .

Implement handling for the - "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.

on the WhatsApp consumer app

Use to test the SSL-certificate.

Read the .

Commerce
Business
use an E.164 format validation
Google's phonelib
Numverify
RealPhoneValidation
consider exceptions for Mexico and Argentina
no dedicated endpoint
Error 131026
cut-off control
text message must contain a valid URL
file type is supported by WhatsApp and that the file size
receiving a contact
typical error scenarios mentioned in the FAQ
quality limit
Troubleshooting guide by WhatsApp
Reddit articles on delayed message delivery
How to speed up the WhatsApp client
Reasons for delayed, incoming messages
Slow connections
s
resetting the cache
SSLlabs
official FAQ
Opt-In requirements
WhatsApp allows users to report spam or to even block the number - a quality signal