LogoLogo
Become a PartnerStatus Page
  • get started
    • Welcome to 360Dialog
    • Quickstarts
      • Register as a Meta Tech Provider
      • Add a WhatsApp Number
      • Set up Integrated Onboarding
      • Create a Message Template
      • Send a Message
      • (temp title) Getting started as a partner
    • Pricing & Billing
      • Payment Methods for BR: Pix & Boleto
      • Month Closing Invoice (MCI)
    • Get API Access
    • Tech Provider Program
      • Understanding the Meta Tech Provider Program
      • Becoming a Meta Tech Provider: A Step-by-Step Guide
  • MM Lite Beta Program
    • Onboarding
    • Sending Messages
    • Expected Errors & Programming Languages
    • MM Lite Sandbox Testing
      • Sending Messages using MM Lite Sandbox
      • Expected Erros & Programming Languages
  • Partner & Account Management
    • Solutions for Partners
      • Benefits for Partners
      • Partner Hub
      • WABA Management
    • Account Setup & Management
      • Prerequisites and best practices for account creation
      • Account Structure
      • Account Creation
  • Integrations & API Development
    • Webhook Events & Setup
      • Webhook Events (Partner & Messaging API)
      • Webhook Configuration & Management
    • Integration Best Practices
      • Architecture and Security
      • Best Practices for Designing Integrations
        • Design a Stable Webhook Receiving Endpoint
      • Sizing Your Environment Based on Expected Throughput
      • Design a Resilient Message Sending Service
      • Integrated Onboarding
        • Basic Integrated Onboarding
        • Custom Integrated Onboarding
        • Host Your Own Embedded Signup
      • API Key Authentication for the Partner API
  • API Reference
    • Messaging API
    • Messaging Health Status
    • Sandbox (Test API Key)
    • Differences Between Cloud API and On-Premise API for Partners
      • [will be deprecated] Messaging with On-Premise API
    • Partner API
  • WABA Management
    • Managing WABA Accounts
      • Using the Partner Hub to manage Clients and Channels
      • Using the Partner API to manage Clients and Channels
      • Partner Permission to Generate API Key
      • Checking Usage & Statistics
    • Phone Number & Hosting
      • Migrating a Phone Number
        • Migrate number from Meta or alternate BSP to 360Dialog
        • Migrate a phone number to a new WABA
        • Migrate a phone number to a new WABA to change messaging Currency
      • WhatsApp Coexistence
        • Coexistence Onboarding
        • Coexistence Webhooks
      • Hosting type Change (On-premise API to Cloud API)
    • WABA Profile & Compliance
      • Display Name Guidelines
      • WABA Profile Info
      • WABA Policy Enforcement
      • Business Account Verification
    • Partner change (between 360Dialog Partners)
    • WhatsApp Flows
    • Accelerated Onboarding
    • Business Account Verification
  • Messaging
    • Sending & Receiving Messages
      • Conversations
      • Receiving messages
      • Before sending a message
    • Message Types
      • Conversational Components
      • Checklist for Message Broadcasts and Campaigns
      • Text messages
      • Interactive messages
        • Single and Multi Product Messages
        • Location Request Messages
        • Address Messages (India and Singapore only)
      • Contacts & Location Messages
    • Template Messages
      • Template Library
      • 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
    • Media Messages
      • Upload, retrieve or delete media
    • Messaging Health & Troubleshooting
      • Messaging Limits & Quality Rating
      • Errors While Messaging
      • Messages statuses
  • Commerce & Payments
    • 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
    • Products and Catalogs
      • India Businesses: Compliance for Commerce
  • Support & Updates
    • Help & Troubleshooting
      • FAQ
      • Error Code Reference
      • User Support Documentation
        • Tutorials
          • Page How to Troubleshoot Login Issues in the 360dialog Hub
          • How to Report an Issue
          • How to Contact Support
        • How-To Guides
          • Raise a support request
          • Requesting a Status Update for Business Verification
        • Reference
          • Troubleshooting Embedded Signup Issues
          • Commerce Policy Checks for WhatsApp API Access
          • Support Availability & SLAs
          • Incident Issue Prioritization
          • Case Types Table
        • Explanation
          • Why Business Verification Takes Time
          • Why Some Issues Are Not Emergencies
          • Understanding the Support Process
      • Support with Meta
    • Imprint & Data Privacy
    • Product Updates & News
      • How to ensure your Template Messages will be received
      • Integrated Onboarding new look and Campaigns Best Practices
Powered by GitBook
On this page

Was this helpful?

Last updated 4 months ago

Was this helpful?

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

Opt-in

As per the update, before messaging people on WhatsApp, businesses are required to obtain opt-in permission, which can be general and not specifically for WhatsApp, as long as businesses comply with all local laws.

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.

Businesses may contact people on WhatsApp if: (a) they have given their mobile phone number; and (b) businesses have received opt-in permission from the recipient confirming that they wish to receive subsequent messages or calls from a particular business.

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.

Opt-in methods

It is up to businesses to determine the method of opt-in, that they have obtained opt-in in a manner that complies with laws applicable to their communications, and that they have otherwise provided notices and obtained permissions that are required under applicable law.

As long as the opt-in method meets the above requirements, it will be policy compliant. The following are examples of supported opt-in methods:

Helpful tips

Businesses should continue to optimize for the user experience while obtaining opt-in. For example:

  • Users should expect the messages they receive. Businesses can set this expectation by:

    • Obtaining an opt-in that encompasses the different categories of messages that a business 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 opt-in and opt-out flows are clear and intuitive for users.

  • Businesses should clearly communicate the value of receiving this information.

  • Businesses should monitor 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.

Handling Webhook Notifications

Before sending any messages, ensure that you have setup a server endpoint to handle WhatsApp Webhook Notifications asynchronously.

Capacity Rate Limits

Capacity rate limiting is imposed on each available API endpoint and will return the appropriate HTTPS error codes (e.g., 429, 503, etc.) depending on the state of the system.

Two forms of capacity rate limiting are currently supported:

  • Request rate limiting — Request rate limiting is the throttling of incoming requests on an API endpoint. When the number of requests per second limit is reached, the endpoint will start returning a 429 error code.

    • Beginning with v2.25.3, the request rate limit for the messages endpoint is 50 requests per second with bursts allowed up to 150 requests per second.

    • For versions prior to v2.25.3 and all other endpoints, the request rate limit is 20 requests per second with bursts allowed up to 60 requests per second.

  • Concurrent rate limiting — Concurrent rate limiting is the throttling of incoming requests when the Coreapp itself is under heavy load (e.g., job queue size grew too large). At this point, the endpoint will start returning a 503 error.

When you hit either of these capacity rate limiting scenarios, you should halt any further requests and slow the pace of your API requests. If you start seeing many capacity rate limit errors, it would be advisable to build a queue on your end to throttle the requests.

See our for more details.

  1. Messaging
  2. Sending & Receiving Messages

Before sending a message

This documentation describes how to start sending messages to your users. Remember that API messages only APP, and not another API.

PreviousReceiving messagesNextMessage Types
  • Sending Messages
  • Opt-in
  • Handling Webhook Notifications
  • Capacity Rate Limits
Best Practices for designing Integrations documentation
WhatsApp Business Messaging Policy
Opt-in requirements
WhatsApp allows users to report spam or to even block the number - a quality signal