# Before sending a message ## 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](https://developers.facebook.com/docs/whatsapp/guides/opt-in)). {% hint style="warning" %} Sending messages to users without an opt-in may result in users blocking your business and suspension of your Whatsapp business account. {% endhint %} ### 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](https://3527970750-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M4sMxKjL6eJRvZn6jeG%2F-MA2-RDZsSaR5lZr82Az%2F-MA2-YYfVhz9fEXnL7_k%2Fimage.png?alt=media\&token=29d9f689-5f8d-419d-86e3-187ad18cc4cb) 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. {% hint style="warning" %} ### **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 {% endhint %} #### 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/?text= ``` 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 | {% hint style="info" %} ### **Recommendation** Always use **Universal Links** over Deeplinks for broader device support. {% endhint %} ## 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](https://stackoverflow.com/questions/6478875/regular-expression-matching-e-164-formatted-phone-numbers). * Use a phone number validation library such as [Google's phonelib](https://github.com/google/libphonenumber) or a number database such as [Numverify](https://numverify.com/), [RealPhoneValidation](https://realphonevalidation.com/) or others to validate that the given number is well-formatted and that it should be valid; [consider exceptions for Mexico and Argentina](https://faq.whatsapp.com/general/contacts/how-to-add-an-international-phone-number/?lang=en). * There is [no dedicated endpoint](https://developers.facebook.com/community/threads/1221785015365753) for contact validation. Instead, the `wa_id` is obtained as part of the successful response to a sent message ([text message ](https://docs.360dialog.com/docs/messaging/overview#send-text-messages)or [template message](https://docs.360dialog.com/docs/resources/templates)). 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. {% hint style="info" %} 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. {% endhint %} **Successful Response:** ```json { "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](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#cloud-api-error-codes)).
CodeDescriptionPossible 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**](https://developers.facebook.com/docs/whatsapp/api/messages#cutoffcontrol)**:** 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](https://developers.facebook.com/docs/whatsapp/api/messages/text#urls). * **Media:** * Confirm that file types are supported. * Respect file size limits. * Video messages must include an audio track. * Use WhatsApp-supported codecs. {% hint style="info" %} 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. {% endhint %} ### 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](https://developers.facebook.com/docs/whatsapp/api/settings/media-providers). #### Contacts with wa\_id Include a `wa_id` when the user should be able to save or message a contact directly. **Example:** ```json "phones": [ { "phone": "+1 (940) 555-1234", "type": "HOME" }, { "phone": "+1 (650) 555-1234", "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](https://360dialog-messaging.api-docs.io/v1/whatsapp/whatsapp-faq)) * [**Quality restrictions**](https://developers.facebook.com/docs/whatsapp/api/rate-limits#quality-rating-and-messaging-limits)**:** 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: ````go *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](https://faq.whatsapp.com/de/general/21069306/?category=5245260\&lang=en) * [Reddit articles on delayed message delivery](https://www.reddit.com/r/oneplus/comments/2zkvx2/whatsapp_messages_delayed_delivery/) * [How to speed up the WhatsApp client](https://indianexpress.com/article/technology/techook/how-to-speed-up-whatsapp-and-fix-other-performance-slowdown-issues-5212805/) * [Slow connections](https://speedify.com/blog/fix-slow-internet/fix-slow-whatsapp-connections-prevent-delayed-messages/)[s](https://www.youtube.com/watch?v=2GyAAbGOpD8) #### Typical Fixes If delays occur, the following steps often help: 1. [**Clear app cache**](https://www.youtube.com/watch?v=2GyAAbGOpD8) 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](https://ssllabs.com/ssltest/analyze.html) 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** * [x] **Brand consistency:** Does the chatbot visually and linguistically align with the company’s identity? * [x] **Conversational tone:** Is the interaction natural and engaging (greeting, small talk, empathy)? * [x] **Language consistency:** Does it use phrasing and tone consistent with the company’s website or app? #### **Performance** * [x] **Purpose clarity:** Is the chatbot’s primary goal clear to the user? * [x] **Effectiveness:** Does it fulfill its purpose and guide users effectively? * [x] **Knowledge:** Can it handle common questions and provide accurate help? * [x] **Feedback:** Does it acknowledge user progress or confirm actions? #### **Consistency** * [x] **Reliability:** Does the bot consistently help users achieve their intended goal? * [x] **Journey alignment:** Is the conversation flow aligned with the company’s expected user journey? * [x] **Relevance:** Is the content regularly updated? * [x] **Coverage:** Does it maintain a balanced knowledge level across all topics? #### **Humanity** * [x] **Transparency:** Is it clear that the user is interacting with a chatbot? * [x] **Self-awareness:** Can it answer basic questions about itself and its limitations? * [x] **Escalation:** Does it gracefully transfer conversations to human agents when needed? * [x] **User control:** Does it explain how users can reach a human agent directly? {% hint style="info" %} Always review chatbot flows regularly to ensure accuracy, freshness, and compliance with WhatsApp Business Policy and Meta’s [Conversational Guidelines](https://developers.facebook.com/docs/whatsapp). {% endhint %} {% hint style="warning" %} ### **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) {% endhint %} ## Other resources Read the [official FAQ](https://developers.facebook.com/docs/whatsapp/faq). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.360dialog.com/docs/guides/best-practices.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.