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
  • Getting started
  • Cloud API Local Storage
  • Base URL
  • Prerequisites & Basic Setup
  • 1. Retrieve API Key
  • 2. Set WABA Webhook URL
  • Send & Receive Messages
  • 3. Send a message
  • 4. Receive a message

Was this helpful?

  1. API Reference

Messaging API

PreviousAPI ReferenceNextMessaging Health Status

Last updated 11 months ago

Was this helpful?

The allows Partners and Clients to send and receive WhatsApp messages.

It is designed to empower businesses with the tools for sending high-scale messages to customers through WhatsApp. Since our API is designed for easy understanding and use, you can also use as a reference.

Getting started

For any outgoing actions in the Messaging API, you need to use requests with appropriate endpoints.

  • All Cloud API actions are available via different request types that use a combination of a root base URL + an endpoint suffix. To ensure that you use the correct endpoints for your API calls, we recommend setting https://waba-v2.360dialog.io/ as a base URL and, for each request suffix, you can refer to our documentation or reach out to our for clarification.

    • While referring to Meta Documentation, you may encounter requests with the path /PHONE_NUMBER_ID. Please note that 360dialog already transmits this value to Meta, hence, there is no need to include it in your request, as doing so may result in errors. (e.g. waba-v2.360dialog.io/PHONE_NUMBER_ID/business_compliance_info)

    • See

  • The body of the request to the API will determine what exactly you want to send (text, image, etc.).

  • You need to use an API key received from the Client in authorization purposes.

  • A business cannot send a freely composed message first. If business starts a conversation with a user, it should use a template message. Please do not forget about Opt-In requirements.

  • Tip: we can recommend to use Postman as first step instrument to test WABA opportunities.

  • Once Cloud API is enabled in your Partner Hub, it becomes the default choice for all clients onboarded through.

To receive any information that is not a response to your request to the API (e.g. incoming messages from users) you need to set a webhook address.

  • It should be unique for every WABA number

  • It should return an HTTPS 200 OK response immediately (before any other processing begins)

Registration Limits: A phone number is limited to 10 registration requests in a 72 hour (3 days) moving window. This restriction applies to actions like WABA Creation, Display Name Change, Migrating numbers from On-premise to Cloud API and registering Test Numbers. If a business exceeds this limit, the phone number will be rate limited and blocked for the next 72 hours before being restored. In case you have any issues,

As of May 15, 2024, Türkiye is no longer restricted for Cloud API business messaging. Cloud API businesses can now initiate conversations and receive messages from WhatsApp users with Turkish numbers.

Cloud API Local Storage

Local Storage for Cloud API number allows businesses to choose the location where their message data is stored at rest. For regulated industries like finance, government, or healthcare, storing data in a specific country may align with regulatory or company policies.

How to configure Local Storage

With such settings enabled, Cloud API uses a localized storage in the specified country for persisting message content, instead of using its default storage based in the US. Alternatively, by disabling Local Storage, Cloud API reverts to its default storage based in the US.

If a number is already in Cloud API with standard data localization, but wants to enable Local Data Storage, OTP will be required. If you are migrating from On-premise to Cloud and set the desired location during the migration, OTP is not required.

Enable Local Storage

POST https://hub.360dialog.io/api/v2 /partners/{partner_id}/clients/{client_id}/channels/{channel_id}/control/enable_local_storage

Request Example: curl --request POST --url https://hub.360dialog.io/api/v2/partners/partner_id/clients/client_id/channels/channel_id/control/enable_local_storage --header 'Accept: application/json' --header 'Authorization: Bearer 123' --header 'Content-Type: application/json' --data '{ "data_localization_region": "DE" }'

Path Parameters

Name
Type
Description

channel_id*

String

The ID of the channel. Example: exampleCH

client_id*

String

The ID of the client.

Example: exampleCL

partner_id*

String

The ID of the partner.

Example: examplePA

Request Body

Name
Type
Description

data_localization_region*

string

Australia, value: AU

Indonesia, value: ID

South Africa, value: ZA

India, value: IN

Canada, value: CA

Japan, value: JP

Singapore, value: SG

South Korea, value: KR

Germany, value: DE

Switzerland, value: CH

United Kingdom, value: GB

Brazil, value: BR

{
  "meta": {
    "success": true,
    "http_code": 200,
    "developer_message": "Local storage setting successfully adjusted."
  }
}

Base URL

The default base URL for the Cloud API is https://waba-v2.360dialog.io followed by the path-specific endpoint.

Prerequisites & Basic Setup

1. Retrieve API Key

In order to communicate with the WhatsApp Business API, you need the D360-API-KEY, which is used for authentication. Each registered WhatsApp phone number (channel) has its own D360-API-KEY.

Only the newest API key is valid, so if you generate another API key, the old one will stop working.

Create a new API key for a specific channel.

POST https://hub.360dialog.io/api/v2/partners/{partner_id}/channels/{channel_id}/api_keys

Path Parameters

Name
Type
Description

channel_id*

string

partner_id*

string

Request Body

Name
Type
Description

id*

string

address*

string

api_key*

string

app_id*

string

{
    // Response
}

Get authorization with the API Key

Each endpoint described later in the documentation has to be accessed with HTTP Request +SSL and either with API Key based authorization.

When making POST requests, JSON data specified in the docs has to be sent as POST data payload.

Every request to the needs to be authorized using an API Key authentication. Adding D360-API-KEY in the header with your unique API Key as a value will grant access.

Example for POST request with curl:

curl \
    -H "D360-API-KEY: {{your-api-key}}" \
    -X POST \
    https://waba-v2.360dialog.io/v1/messages \
    -H "Accept: application/json"
    ...

Example using Postman

Extra notes

  • Store and manage your D360-API-KEY securely and use it only for server-2-server authentication.

  • Ensure that you always use the corresponding D360-API-KEY when you deal with multiple configurations. A mismatch could lead to inconsistent data.

2. Set WABA Webhook URL

To receive notifications for in and outbound messages, you have to set a webhook URL.

This will serve as the destination for all Messaging Notifications associated with the WhatsApp Business Account (WABA) or the Phone Number.

Webhook URLs or headers for Cloud API does not support "_"(underscore) or ":xxxx"(port)in (sub)domain names.

Invalid webhook URL: https://your_webhook.example.com Valid webhook URL: https://yourwebhook.example.com

Invalid webhook URL:https://subdomain.your_webhook.example.com:3000 Valid webhook URL: https://subdomain.yourwebhook.example.com

Send & Receive Messages

3. Send a message

Use/messages to send text messages, media, documents, and message templates to your customers.

You can send messages by making a POST call to the /messages regardless of message type. The content of the JSON message body differs for each type of message (text, image, etc.).

Send a text message

POST https://waba-v2.360dialog.io/messages

To send a message, use the request URL and the following body parameters.

Request Body

Name
Type
Description

recipient_type

string

individual

to

string

wa_idof the contact you want to message

type

string

text

text

object

contains body field

A successful response includes a messages object with an ID for the newly created message.

{
    "messaging_product": "whatsapp",
    "contacts": [
        {
            "input": "16505076520",
            "wa_id": "16505076520"
        }
    ],
    "messages": [
        {
            "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
        }
    ]
}

Example payload

POST https://waba-v2.360dialog.io/messages

{
    "recipient_type": "individual",
    "to": "wa_id",
    "messaging_product":"whatsapp",
    "type": "text",
    "text": {
        "body": "Hello, dear customer!"
    }
}

4. Receive a message

In this Webhook URL, you will receive:

  • Messages sent by users

  • Message status notifications

If a webhook event isn't delivered or if the webhook request returns a HTTP status code other than 200, we retry the webhook delivery. We continue retrying delivery with increasing delays up to a certain timeout (typically 24 hours, though this may vary), or until the delivery succeeds.

Refer to our documentation for details on Cloud API Local Storage.

If you wish to change the local storage of a WABA, you can use . Note that you will need to receive a pin code in the phone number to confirm the change.

This means that you should make sure that the in your Partner Account is correct (in Europe or another Country) before starting to migrate or register numbers in Cloud API with default location in the U.S.

If you need any assistance, with the specific location, and we will configure this feature for you. Once enabled, you can see the configured local storage from the 360dialog Hub.

You can manage the API Key directly via API. See documentation for more details.

For each request you will need the .

If you only want to test sending messages, you can skip this step and continue with .

to find information about the payloads.

If this wa_id did not sent a message to your WhatsApp Business Account within the last 24 hours, you can only reach this number with a .

In case you have set a webhook URL as described in step you will have received a Outbound Message Status Notification for your test message by now.

See to find information about the payloads.

please reach out to our Support Team
Partner Permissions to Generate API Key
▶ Set Webhook URL
See Webhook events and Notifications
template message
Webhook Events (Partner & Messaging API)
3. Send a message
2. Set Webhook URL,
Meta documentation
Support Team
Integrated Onboarding
please reach out to our Support team.
Messaging API
the Partner API
Default Data Storage Region
Architecture and Security
Partner API Authorization Token
Cloud API Error Codes
Other events listed here
Webhook events and Notifications