Log inTry for free
Back to all APIs

Send WhatsApp template message

Send a single or multiple template messages to one or more recipients. Template messages can be sent and delivered at anytime. Each template needs to be registered and pre-approved by WhatsApp.
The API response will not contain the final delivery status, use Delivery Reports instead.

Learn more about WhatsApp channel and use cases
Please log in to see full path URL. Learn why.
post
/whatsapp/1/message/template
Authorizations:
API Key Header
Basic
IBSSO Token Header
OAuth 2
Scopes:
message:send
whatsapp:manage
whatsapp:message:send
Request rate limit:
4000 requests / second (per account)
Request Body schema:
application/json
collapse all -
messages
required
Array of objects

An array of messages being sent.

Array
from
required
string [ 1 .. 24 ] characters

Registered WhatsApp sender number. Must be in international format and comply with WhatsApp's requirements.

to
required
string [ 1 .. 24 ] characters

Message recipient number. Must be in international format.

messageId
string [ 0 .. 100 ] characters

The ID that uniquely identifies the message sent.

content
required
object

The content object to build a message that will be sent.

templateName
required
string [ 1 .. 512 ] characters

Template name. Should only contain lowercase alphanumeric characters and underscores.

templateData
required
object

Template data. Values have to be set as registered in the template.

body
required
object

Template body.

placeholders
required
Array of strings

Template's parameter values submitted in the same order as in the registered template. The value must not be null, but it can be an empty array, if the template was registered without placeholders. Values within the array must not be null or empty.

header
object

Template header. Should be defined, only if placeholders or media have been registered in the template's header.

type
required
string
TEXT
placeholder
required
string

Value of a placeholder in the text header.

buttons
Array of objects

Template buttons. Should be defined in the correct order, only if quick reply, dynamic URL, copy code or flow buttons have been registered. It can have up to ten buttons including a maximum of two dynamic URL buttons and one copy code button. When flow, catalog, multi product or order details button is used it needs to be the only button.

Array
type
required
string
QUICK_REPLY
parameter
required
string [ 1 .. 128 ] characters

Payload of a quick reply button.

carousel
object

Template carousel. Should be defined only when template contains carousel.

cards
required
Array of objects [ 1 .. 10 ] items

Carousel cards. Should be defined in the correct order. It can have between one and ten cards.

Array
header
required
object

Template header. Should be defined, only if placeholders or media have been registered in the template's header.

type
required
string
TEXT
placeholder
required
string

Value of a placeholder in the text header.

body
object

Template body.

placeholders
required
Array of strings

Template's parameter values submitted in the same order as in the registered template. The value must not be null, but it can be an empty array, if the template was registered without placeholders. Values within the array must not be null or empty.

buttons
Array of objects [ 1 .. 2 ] items

Card buttons. Should be defined in the correct order, only if quick reply or dynamic URL buttons have been registered.

Array
type
required
string
QUICK_REPLY
parameter
required
string [ 1 .. 128 ] characters

Payload of a quick reply button.

limitedTimeOffer
object

Template limited-time offer. Should be defined, only if template contains limited-time offer.

expirationTime
required
string <date-time>

Offer code expiration time. Has the following format: yyyy-MM-dd'T'HH:mm:ss.SSSZ.

language
required
string

The code of language or locale to use. Must be the same code used when registering the template.

callbackData
string [ 0 .. 4000 ] characters

Custom client data that will be included in a Delivery Report.

notifyUrl
string [ 0 .. 2048 ] characters

The URL on your callback server to which delivery and seen reports will be sent. Delivery report format, Seen report format.

urlOptions
object

Sets up URL shortening and tracking feature.

shortenUrl
boolean
Default: true

Enable shortening of the URLs within a message. Set this to true, if you want to set up other URL options.

trackClicks
boolean
Default: true

Enable tracking of short URL clicks within a message: which URL was clicked, how many times, and by whom.

trackingUrl
string

The URL of your callback server on to which the Click report will be sent.

removeProtocol
boolean
Default: false

Remove a protocol, such as https://, from links to shorten a message. Note that some mobiles may not recognize such links as a URL.

customDomain
string

Select a predefined custom domain to use when generating a short URL.

smsFailover
object

SMS message to be sent if the WhatsApp template message could not be delivered.

from
required
string [ 1 .. 24 ] characters

SMS sender number. Must be in international format.

text
required
string [ 1 .. 4096 ] characters

Content of the SMS that will be sent.

entityId
string [ 0 .. 255 ] characters

Required for entity use in a send request for outbound traffic. Returned in notification events. For more details, see our documentation.

applicationId
string [ 0 .. 255 ] characters

Required for application use in a send request for outbound traffic. Returned in notification events. For more details, see our documentation.

bulkId
string [ 0 .. 100 ] characters

The ID that uniquely identifies the request. Bulk ID will be received only when you send a message to more than one destination address.

Responses

200

Message accepted for delivery

400

Bad request

401

Unauthorized

403

Forbidden

429

Too Many Requests

500

Internal Server Error

Request samples

Content type
application/json
Example
Body template message
Copy
 Collapse all
{
  • "messages":
    [
    • {
      • "from": "441134960000",
      • "to": "441134960001",
      • "messageId": "a28dd97c-1ffb-4fcf-99f1-0b557ed381da",
      • "content":
        {
        • "templateName": "template_name",
        • "templateData":
          {
          • "body":
            {
            • "placeholders":
              [
              • "Placeholder Value 1",
              • "Placeholder Value 2"
              ]
            }
          },
        • "language": "en_GB"
        },
      • "callbackData": "Callback data",
      • "notifyUrl": "https://www.example.com/whatsapp",
      • "urlOptions":
        {}
      }
    ]
}

Response samples

Content type
application/json
Copy
 Collapse all
{
  • "messages":
    [
    • {
      • "to": "441134960001",
      • "messageCount": 1,
      • "messageId": "a28dd97c-1ffb-4fcf-99f1-0b557ed381da",
      • "status":
        {
        • "groupId": 1,
        • "groupName": "PENDING",
        • "id": 7,
        • "name": "PENDING_ENROUTE",
        • "description": "Message sent to next instance"
        }
      }
    ],
  • "bulkId": "2034072219640523073"
}

Need assistance

Explore Infobip Tutorials

Encountering issues

Contact our support

What's new? Check out

Release Notes

Unsure about a term? See

Glossary

Research panel

Help shape the future of our products
Learn more
Service status

Copyright @ 2006-2025 Infobip ltd.

Privacy documentsTerms of use