LogoLogo
Become a PartnerStatus Page
  • get started
    • Welcome to 360Dialog
    • Quickstarts
      • Getting started as a partner
      • Register as a Meta Tech Provider
      • Add a WhatsApp Number
      • Set up Integrated Onboarding
      • Create a Message Template
      • Send a Message
    • 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
  • 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
  • API Reference
  • [will be deprecated] If the WABA is registered in On-premise API
  • Delivery Sequence of Multiple Messages
  • Text Truncation for Marketing Messages
  • Time-To-Live
  • Template Pacing
  • Per-User Marketing Template Message Limits
  • Experiments

Was this helpful?

  1. Messaging
  2. Template Messages

Sending Template Messages

PreviousTemplate ElementsNextAuthentication Templates

Last updated 1 month ago

Was this helpful?

It is only possible to send Templates with Active status. A message template status can change automatically from Active to Paused or Disabled based on feedback from customers. See .

Currently, you can send the following template types:

  • : To send a text-based message template, make a POST call to the endpoint below and attach a text message object.

  • : When sending messages with media such as images, videos, or audio files, see our Media documentation to find details.

  • : Interactive message templates expand the content you can send recipients beyond the standard message template and media messages template types to include interactive buttons.

  • : Showcase your products to customers directly from a template message.

  • : Send location-based message templates.

  • : Specific Authentication Templates to authenticate and validate OTPs directly from WhatsApp.

API Reference

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

Request Body

Name
Type
Description

to*

string

Recipient wa_id

type*

string

Message type

language*

string

Template language

policy*

string

Delivery policy

code*

string

Language code

name*

string

Template name

messaging_product*

string

Required for Cloud API. Messaging service used for the request. Use "whatsapp".

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

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

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

Request Body

Name
Type
Description

to

string

Recipient wa_id

type

string

Message type

namespace

string

Template namespace

language

string

Template language

policy

string

Delivery policy

code

string

Language code

name

string

Template name

Delivery Sequence of Multiple Messages

Text Truncation for Marketing Messages

The rollout of the Text Truncation feature is currently gradual, so you may have experienced it during your campaigns. It is expected to reach all users by mid-October 2024.

Text Truncation impacts how users view marketing messages in their chat screens. It shortens, or "truncates," messages that exceed five (5) lines of text, displaying a clickable ‘Read more’ option. This allows users to view the complete message if they choose.

This update is part of WhatsApp's commitment to enhancing the user experience with marketing messages, helping clients achieve more value from marketing campaigns. Meta has implemented this change to boost user satisfaction while optimizing click-through rates (CTR). You should expect this update in Marketing Messages campaigns.

Initially, Text Truncation applies to the ‘Single image + text + click-to-action button(s)’ templates. Over time, it will extend to all formats of Marketing Messages, including group chats.

To maximize the impact of your marketing messages with this update, consider these best practices:

  • Make Your Message Engaging: Capture the user's attention quickly with content that speaks to their interests and interactions with the business.

  • Focus on the First 5 Lines: Create a clear and powerful opening with the first five lines. This is the text that will be visible to users, even when the message is truncated.

  • Build on Previous Interactions: Use past interactions with the user to craft a message that feels relevant and personalized.

  • Structure Longer Messages: If your message requires more than five lines, use distinct sections with clear spacing. Aim to keep your message concise, limiting to 3-4 well-defined sections.

Time-To-Live

If Meta is unable to deliver a message to a WhatsApp user, they will continue attempting to deliver the message for a period of time known as a time-to-live (TTL), or message validity period. If Meta is unable to deliver a message for an amount of time that exceeds the TTL, they will stop trying and drop the message.

  • The TTL for all messages, except for template messages that use an authentication template, is 30 days.

  • Template messages that use an authentication template have a default TTL of 10 minutes.

Template Pacing

Template pacing applies worldwide to both Marketing and Utility templates.

For Marketing Templates campaigns with fewer recipients that do not reach their 'pace limit', their messages will not be subjected to pacing. This 'pace limit' number is dynamically determined by Meta and may vary depending on the template or business.

When a template is paced, messages will be sent normally until an unspecified threshold is reached. Once this threshold is reached, subsequent messages using that template will be held to allow enough time for customer feedback. Once Meta receives a good quality signal, subsequent messages using that template will be scaled to the entire target audience. If they receive a bad quality signal, subsequent messages using that template will be dropped, giving the business the opportunity to adjust content, targeting, etc.

Utility Template Pacing

API Behaviour

The immediate response from the messages endpoint will indicate if the message was sent (accepted) or held (held_for_quality_assessment) with the message_status property in the message object.

If the feedback is negative and changes the template's quality to low quality:

  • The template's status will be set to PAUSED

  • Each held message will be dropped and trigger a messages webhook with "status":"failed" and "code":"132015" (Cloud API users) or "code":"2061" ( On-Premises API users)

  • Admins of the WhatsApp Business Account owning business will be informed of the dropped messages by Meta Business Suite notification, WhatsApp Manager banner, and email

Note that Meta has internal guardrails in place to ensure that we evaluate and make a pacing decision within a reasonable time to avoid impact on time sensitive campaigns. The goal is that even if paced, campaign messages with highest throughput still get delivered within an hour (99 percentile).

Per-User Marketing Template Message Limits

Starting April 1, 2025, Meta will temporarily pause delivery of all marketing template messages to WhatsApp users who have a United States phone number (a number composed of a +1 dialing code and a US area code). This pause is intended to allow Meta to focus on building a better consumer experience in the US, which will ultimately lead to improved outcomes for businesses.

Attempting to send a template message to a WhatsApp user with a US phone number after this date will result in error 131049.

WhatsApp may limit the number of marketing template messages a person receives from any business in a given period of time, starting with delivering fewer marketing conversations to those users who are less likely to engage with them. In most WhatsApp markets, this is determined based on a number of factors, including a dynamic view of an individual’s marketing message read rate, and is not related to your business specifically.

For individuals with United States phone numbers (numbers composed of a +1 dialing code and a US area code), where WhatsApp is growing quickly but at an earlier stage, WhatsApp will not deliver any marketing template messages to focus on building the consumer experience.

Why it's important

WhatsApp has found that per-user marketing template limits maximize message engagement and improve the user experience, measured through improvements in user read rates and sentiment. This limit helps WhatsApp users find business messaging more valuable and feel less like they receive too many business messages.

How this Applies to Your Business

Example:

  • A second marketing template message can be sent in an existing conversation.

What to watch for: 131049 Error Code

If you do receive one this error code and suspect it is due to the limit, avoid immediately resending the template message, as it will only result in another error response. Instead, retry in increasing larger time increments until the message is delivered, since the limit may be in effect for differing periods of time.

Experiments

Meta's ongoing experiment on the WhatsApp Business Platform is focused on evaluating how marketing messages impact consumer experience and engagement. As part of this experiment, approximately 1% of WhatsApp consumers will not receive marketing messages.

When sending a series of messages, the order in which messages are delivered is not guaranteed to match the order of your API requests. If you need to ensure the sequence of message delivery, confirm receipt of a delivered status in a messages webhook before sending the next message in your message sequence. See

You can customize these defaults by setting a custom TTL on authentication, utility and marketing templates. See .

If you send a message but do not receive a corresponding indicating that the message was delivered before the TTL is exceeded, assume the message was dropped.

Note that if a message fails for some unrelated reason and it triggers a , there could be a minor delay before you receive the webhook, so you may wish to build in a small buffer before assuming a drop.

Template pacing is a mechanism that allows time for customers to provide early on newly created or unpaused marketing or utility templates. This identifies and pauses templates that have received poor feedback, giving the business time to adjust their contents before they are sent to too many customers, thereby reducing the likelihood of negative feedback impacting the business.

Template pacing is valid for utility and marketing templates. Newly created templates, , and templates that may have been created previously but don’t have a GREEN quality rating are potentially subject to pacing. — for example, low quality resulting in a template pause — is one of the primary reasons for template pacing and you may see other templates get paced.

Utility templates are subject to pacing only if the number had a utility Once a utility template has been paused, newly created templates, paused templates that are unpaused, and templates that may have been created previously but don’t have GREEN quality rating are potentially subject to pacing for the next 7 days.

If the feedback is positive and changes the template's quality rating to high quality, the held messages will be released and sent normally which will trigger the sent and delivered webhooks. The will send the quality update and the webhook will send the sent and delivered updates.

A will be sent with an event value of paused

A webhook will be triggered with the quality change

Seeto learn how to unpause a template that has been paused due to pacing.

Thus, if Meta internal guardrails are reached before a template has received enough feedback to change its quality to high or low, the held messages will be released normally along with any appropriate messages webhooks. See

The limit only applies to that would normally open a If a marketing conversation is already open between you and a WhatsApp user, marketing template messages sent to the user will not be affected. Further marketing template messages can only be sent in an open marketing conversation if the person responds to any message.

The first marketing template message is delivered and opens a new customer service window. The per-user marketing template message limit applies.

Each time the WhatsApp user responds in an existing conversation window, you can send one additional marketing template message. You can also send unlimited messages.

If a marketing template message is not delivered to a given user due to the limit, Cloud API will return error code 131049 with the description “This message was not delivered to maintain a healthy ecosystem engagement.” See error code: 131049 in

To understand more about these limits and how to adapt strategies, .

Businesses will not be charged for undelivered messages. While there is no guaranteed timeframe for how long a number may be part of the experiment, we do not recommend retrying to send marketing messages to consumers with experimentation error codes unless there is an active conversation open. See and on Meta's Official Documentation.

See differences between On-premise API and Cloud API
Learn how to change hosting type of registered numbers
read our blog post on this subject
Cloud API
On-Premise Experiments
Text-based message templates
Media-based message templates
Interactive message templates
Multi-Product Message templates
Location-based message templates
Authentication templates with one-time password buttons
Template Statuses
new marketing conversation.
feedback
Enable Cloud API in your Partner Hub to be able to register Cloud API numbers
24-hour marketing conversation
free-form
Error Messages.
Webhooks and events.
messages webhook
delivery failure messages webhook
message_template_quality_update
messages
message_template_quality_update
message_template_quality_update
Webhooks and events.
Customizing Time-To-Live
paused templates that are unpaused
Template quality history
template paused.
Template Pausing
marketing template messages