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 allows users to report spam or to even block the number - a quality signal

WhatsApp provides users with the ability to report or block a business number when they receive a message without prior interaction — such as in the case of notifications.

If the user doesn’t recognize the sender or the purpose of the message, this may lead to a higher rate of blocks or reports, and consequently, opt-outs.

To reduce the risk of user reporting, businesses must ensure that:

• Opt-out instructions are clearly visible and easy to follow within the message template.

• The message provides context — so the recipient understands why they are receiving it.

Impact of user reporting

Repeated user reports can result in a low quality rating, which leads to:

• Reduced messaging limits

• Temporary restrictions

• Permanent account suspension from the WhatsApp Business Platform

Best Practices for Notifications

When creating and sending notifications, follow these principles to maintain a high-quality user experience:

Expected	The user has opted in to receive this type of information and is not surprised by the contact.
Relevant	The content is personalized, concise, and provides clear next steps (e.g., based on past purchases or interactions).
Timely	Messages are sent at an appropriate moment, when they’re most relevant to the recipient.

Deep & Universal Links

The following links can be used to initiate chats or perform specific WhatsApp actions. Always ensure that the user has opted in before sending or triggering these links.

Standard Universal Link Example

https://wa.me/<YOUR_WABA_PHONE_NUMBER>?text=<YOUR_START_MESSAGE>

This URL opens WhatsApp directly (if installed) or a hosted landing page (if not).

Supported Link Types

Type	Scheme / Example	Notes
Deeplink	whatsapp://r	Account confirmation link (may not work consistently on iOS)
Deeplink	whatsapp://send	Contact picker
Deeplink	whatsapp://chat	HomeActivity
Deeplink	upi://pay	Ppayments
Universal Link	http[s]://v.whatsapp.com	Verify SMS deeplink
Universal Links	https://api.whatsapp.com / https://wa.me	Text and direct chat deeplink
Universal Link	https://chat.whatsapp.com	Accept invite link deeplink

Recommendation

Always use Universal Links over Deeplinks for broader device support.

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.

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

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.

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

Follow these rules to ensure reliable message delivery:

• Cut-off control: Do not send session messages if you receive a 470 response (session expired).

• Test setup: Always send a message to your WABA number before testing.

• Character limit: Text messages must not exceed 4096 characters.

• URL previews: If preview_url is set to true, ensure the message contains a valid URL.

• Media:

  • Confirm that file types are supported.

  • Respect file size limits.

  • Video messages must include an audio track.

  • Use WhatsApp-supported codecs.

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.

Messages with Media

When sending media messages:

• Prefer using media_id (upload once and reuse).

• For recurring links, upload media via the /media endpoint to avoid redundant downloads and storage bloat.

• For private media, configure a trusted provider as outlined in Meta’s Media Providers Guide.

Contacts with wa_id

Include a wa_id when the user should be able to save or message a contact directly.

Example:

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

Without wa_id, the client will only be able to invite the user.

With wa_id, they can add the contact or send a message, depending on device behavior (Android/iOS).

Error Handling & Quality Limits

Implement handling for:

• Common API errors (see FAQ)

• Quality restrictions: Numbers that reach a poor quality threshold may be switched to Restricted status for 24 hours. To prevent this, warm up new numbers gradually by sending a limited number of template messages first.

Use message formatting for readability:

*bold*   _italic_   ~strikethrough~   ```monospace```

Latency Issues

It’s important to note that message latency can occur due to factors outside of the WhatsApp Business Platform’s control. Delays are typically related to the user’s device performance, network quality, or WhatsApp consumer app behavior.

Common reasons include:

• Unstable or slow internet connection

• Device RAM limitations or background app restrictions

• Local cache issues in the WhatsApp consumer app

• Device sleep or network switching (e.g., Wi-Fi ↔ mobile data)

• Delayed app notifications on specific OS versions

See also:

• 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

If delays occur, the following steps often help:

1. Clear app cache on the WhatsApp consumer app.

2. Reset network connection (toggle airplane mode on/off).

3. Force-stop and restart the WhatsApp consumer app.

4. Ensure sufficient RAM is available for the WhatsApp app.

5. Save the contact being messaged in the address book.

Callback handling

Callbacks must always be processed asynchronously to ensure reliability and prevent timeouts. The recommended flow is:

Acknowledge first → Process later

Best Practices

• Do not process incoming messages or notifications directly in the callback handler.

• Always use valid SSL certificates for callback endpoints.

  • Certificates must support TLS 1.3.

  • Ensure the full certificate chain is valid.

• Use SSL Labs to test the certificate configuration.

• Confirm that your DNS entry for the callback endpoint is properly propagated and resolvable via public DNS servers (e.g., 8.8.8.8).

Chatbot integrations

During the setup or testing phase, it’s recommended to configure a default fallback message to inform users that the chatbot is not yet fully operational.

Example default message:

“Thank you 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.”

Chatbot Quality Review Checklist

Before launching your chatbot, review the following areas to ensure quality, consistency, and brand alignment.

Branding

• Brand consistency: Does the chatbot visually and linguistically align with the company’s identity?

• Conversational tone: Is the interaction natural and engaging (greeting, small talk, empathy)?

• Language consistency: Does it use phrasing and tone consistent with the company’s website or app?

Performance

• Purpose clarity: Is the chatbot’s primary goal clear to the user?

• Effectiveness: Does it fulfill its purpose and guide users effectively?

• Knowledge: Can it handle common questions and provide accurate help?

• Feedback: Does it acknowledge user progress or confirm actions?

Consistency

• Reliability: Does the bot consistently help users achieve their intended goal?

• Journey alignment: Is the conversation flow aligned with the company’s expected user journey?

• Relevance: Is the content regularly updated?

• Coverage: Does it maintain a balanced knowledge level across all topics?

Humanity

• Transparency: Is it clear that the user is interacting with a chatbot?

• Self-awareness: Can it answer basic questions about itself and its limitations?

• Escalation: Does it gracefully transfer conversations to human agents when needed?

• User control: Does it explain how users can reach a human agent directly?

Always review chatbot flows regularly to ensure accuracy, freshness, and compliance with WhatsApp Business Policy and Meta’s Conversational Guidelines.

Policy requirement:

WhatsApp requires a human escalation path whenever automation (chatbot) is used and the issue cannot be resolved automatically. Valid escalation paths include:

• Handoff to a human agent within the same chat thread

• Providing a phone number for support

• Offering email or web form support options

• Prompting the user to visit a physical store (when relevant)

Other resources

Read the official FAQ.