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
  • Introduction
  • Send Text Messages
  • If the WABA is registered in Cloud API
  • Send Text Message
  • [will be deprecated] If the WABA is registered in On-premise API
  • Send Text Message
  • Formatting in Text Messages
  • Sending URLs in Text Messages
  • Message Templates
  • Bulk Messaging
  • Error scenarios
  • Message statuses
  • Received
  • Read
  • If the WABA is registered in Cloud API
  • [will be deprecated] If the WABA is registered in On-premise API

Was this helpful?

  1. waba Messaging

Messaging

This documentation describes how to send messages using the WhatsApp Business API.

PreviousConversationsNextConversational Components

Last updated 1 year ago

Was this helpful?

If you are using On-Premise API, remember that it is being discontinued by Meta. No new signups will be allowed with this type of integration from May 15, 2024.

Numbers registered before this date will still be supported, but should start planning a as soon as possible.

Introduction

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. See the official WhatsApp documentation for information regarding the parameters of each type of message you want to send to assemble your request payload.

On-Premise API (old)
Cloud API (standard)

Check out the on how to message your customers.

Send Text Messages

Specify text in the type field. A text message can be a maximum of 4096 characters long.

If the WABA is registered in Cloud API

Send Text Message

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

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

{

"messaging_product": "whatsapp",

"recipient_type": "individual",

"to": "PHONE_NUMBER",

"type": "text",

"text": {

"body": "Hello, dear customer!"

}

}

Request Body

Name
Type
Description

messaging_product*

string

Required only for Cloud API.

Messaging service used for the request: Use "whatsapp"

text*

object

contains body field

type*

string

type of the message: text

recipient_type*

string

individual

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"
        }
    ]
}

[will be deprecated] If the WABA is registered in On-premise API

As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.

Send Text Message

POST https://waba.360dialog.io/v1/messages

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

{

"recipient_type": "individual",

"to": "wa_id",

"type": "text",

"text": {

"body": "Hello, dear customer!"

}

}

Request Body

Name
Type
Description

recipient_type

string

individual

to

string

wa_id

type

string

text

text

object

contains body field

{
    "messages": [
        {
            "id": "gBGHSRUUIXKJTwIJVQgXRR0rdXiv"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.31.5"
    }
}

For non template messages, sending a message to a phone number without a WhatsApp account will result in a webhook notification related to the messaging attempt containing a 470 error code.

Formatting in Text Messages

WhatsApp allows some formatting in messages. To format all or part of a message, use these formatting symbols:

Formatting
Symbol
Example

Bold

Asterisk (*)

Your total is *$10.50*.

Italics

Underscore (_)

Welcome to _WhatsApp_!

Strike-through

Tilde (~)

This is ~better~ best!

Code

Three backticks (```)

```print 'Hello World';```

Sending URLs in Text Messages

By default, the mobile WhatsApp application recognizes URLs and makes them clickable. To include a URL preview, include "preview_url": true and make sure the URL begins with http:// or https://. A hostname is required, IP addresses are not matched.

If the WABA is registered in Cloud API

When sending preview-url with Cloud API hosting, the preview-url should be inside the text object.

Example:

    "text":  {// the text object
        "preview_url": true,
        "body": You have to check out this amazing messaging service https://www.whatsapp.com/"
    }

The majority of the time when you send a URL, whether with a preview or not, the receiver of the message will see a URL that they can click on.

URL previews are only rendered after one of the following has happened:

  1. The business has sent a message template to the user.

  2. The user initiates a conversation with a "click to chat" link.

  3. The user adds the business phone number to their address book and initiates a conversation.

If the end user did not initiate the conversation with you - you must use a Template message instead for a free-form message.

[will be deprecated] If the WABA is registered in On-premise API

To use preview-url with the 360dialog On-Premise hosting, it must be sent as a top-level object:

Example:

{
    "preview_url": true,
    "to": "whatsapp-id",
    "text": {
        "body": "You have to check out this amazing messaging service https://www.whatsapp.com/"
     }
     

Message Templates

We strongly advise uploading media intended to use in template messages and the usage of media ID instead of a URL.

  • Each WhatsApp Business Account can have up to 250 message templates (how many is determined by your plan). That means 250 message template names, and each of them can have multiple language translations. For example, a message template called hello_world translated into two languages counts as a single message template in regards to this limit.

  • The message template name field is limited to 512 characters.

  • The message template content field is limited to 1024 characters.

  • There is no limit to the number of parameters allowed in a Message Template.

360dialog stores media files for 14 days after upload. Media files older than 14 days may be deleted by 360dialog without prior notice.

Bulk Messaging

There are two options to send messages in bulk.

  1. Develop your own solution Code your own solution to send Template messages to a list of contacts.

Error scenarios

  • 408: Timeout Message failed to send because it was pending for too long. If this happens, we recommend that you implement graceful timeout handling and retry.

  • 470: Message failed to send because more than 24 hours have passed since the customer last replied to this number (no open session) Free-form text messages and media messages will result in a failure callback with error 470 when sent outside of the 24h-window. In other words, if it has been more than 24 hours since you last received a user initiated message - the session is closed and you can no longer use free-form messages. To re-initiate a conversation, you must use a Template Message.

  • 1000: Image file format (audio/mpeg) is not supported Make sure that the message type matches the MIME-type of the file (ex. audio files should be sent using "audio", not "image"; audio/mpeg is an unsupported combination). Another reason could be that the video file doesn't have an audio track: then the error message contains something like video/mp4/h264/NONE where NONE is an indicator that the audio track is missing.

  • 1009: Invalid latitude The valid range is from -90 to 90.

  • 1014: Request for .... failed You have provided a URL that seems to be double URL-encoded and the file cannot be delivered because of that, or the file behind the URL doesn't exist.

  • 2001: Template name does not exist in the translation Check that you are calling the correct language short code. Example:

        "language": {
            "policy": "deterministic",
            "code": "en"
        }

  • 500: structure unavailable: Client could not display the highly structured message (hsm) The Template was not understood by the WhatsApp consumer client. Check the format.

Message statuses

Received

The receive 'double check' on messages sent by the customer appears when the callback with the received status reaches the 360dialog Webhook.

The receive 'double check' on messages sent by the business appears when the customer’s WhatsApp app receives the message.

Read

The read double check on messages sent by the business appears when the customer’s WhatsApp app is open in the message.

To mark a message as read, follow the instructions below:

If the WABA is registered in Cloud API

Step 1: Make POST Request to /messages

The message_id used in this API call is the id provided in the Webhook Inbound Notification.

POST /messages
{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "MESSAGE_ID"
  }'

Parameters

Name
Description

messaging_product

Required. Use whatsapp

message_id

Required.

status

Required.

Updating status to read is applicable only for incoming messages.

Step 2: Check the API Response

A successful response returns:

null # or { "success" : true }

[will be deprecated] If the WABA is registered in On-premise API

As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.

Step 1: Make PUT Request to /messages

The message_id used in this API call is the id provided in the Webhook Inbound Notification.

PUT /v1/messages/message-id
{
    "status": "read"
}

Parameters

Name
Description

status

Required.

Updating status to read is applicable only for incoming messages.

Step 2: Check the API Response

A successful response returns:

null # or {}

Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to of numbers to Cloud as soon as possible. .

See all parameters for messages .

Please refer to our documentation on Message Templates, which includes, and .

Use an Integration Partner Bulk messaging, sometimes known as group messaging, is deprecated in the native WhatsApp API. But the same functionality is available in many of our . Although Meta has deprecated group management features on WhatsApp with an API, the same functionality has been implemented by our Partners.

For a complete overview of API error codes and status messages, please see

400: Bad Request Check that you are using the correct data type for Booleans and Strings, and that the JSON-payload is well-formed. Use an online tool (ex. ) to validate the payload if you are not sure.

402: Message failed to send because there were one or more errors related to your payment This happens when a WhatsApp Business Account is created but no Payment Method is set. If you get this error message - .

1000: Failed to generate processed file path This could occur when the file storage is full and files cannot be stored. If you get this error message - .

The read double check on messages sent by the customer appears when the message is.

Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to of numbers to Cloud as soon as possible. .

start changing the hosting type
Learn here how to integrate with Cloud API
here
Integration Partner Applications
Official WhatsApp documentation.
marked as read by the business
start changing the hosting type
Learn here how to integrate with Cloud API
Text Messages
Text Messages
Media Messages
Media Messages
Interactive Messages
Interactive Messages
Contacts & Location Messages
Contacts & Location Messages
Templates
Messages
Templates Messages
Media Template Messages
Media Template Messages
Interactive Template Messages
Interactive Template Messages
contact our support team
contact our support team
change of hosting type
Best practices
the steps required to get your Templates approved
the process for creating and deleting them
JSON formatter and validator