Guides

Direct Send API

Suggest Edits

You can now send business-initiated Utility messages directly through the WhatsApp Business Platform without opening a conversation with your end-users. Utility messages do not require prior template approval, enabling faster communication for transactional and account-related updates.

This feature is currently in beta and not yet publicly available to all customers. To participate in the beta program, your WhatsApp Business Account (WABA) must first be verified for eligibility by Meta. If you want to be involved in the beta testing, please ask your CM contact person to reach out to the WhatsApp product team.

This section outlines the features available to business and partner participants during the beta testing phase.

📘

Supported Messages Type

  • Text messages – Send plain text messages.
  • Interactive Call-to-Action (CTA) URL button messages – Include clickable URL buttons to drive end-user actions.
  • Interactive reply button messages – Add quick reply buttons for end-user responses.

How to send Direct Send Api Messages

A new category field has been introduced to specify the message category. When using Direct Send functionality, set the category parameter to utility.

{
  "messages": {
    "msg": [
      {
        "RichContent": {
          "conversation": [
            {
              "content": "text",
              "text": "MT message",
              "category": "utility" //category is necessary for Direct Send API usage
            }
          ]
        },
        "allowedChannels": [
          "WhatsApp"
        ],
        "body": {
          "content": "text"
        },
        "from": "00316098765432",
        "to": [
          {
            "number": "00316012345678"
          }
        ]
      }
    ]
  }
}

{
  "messages": {
    "msg": [
      {
        "from": "00316098765432",
        "to": [
          {
            "number": "00316012345678"
          }
        ],
        "body": {
          "type": "auto",
          "content": "This is a WhatsApp message"
        },
        "allowedChannels": [
          "WhatsApp"
        ],
        "richContent": {
          "conversation": [
            {
              "category": "utility", //category is necessary for Direct Send API usage
              "interactive": {
                "type": "button",
                "header": {
                  "type": "image",
                  "media": {
                    "mediaName": "CM.com - Be part of it.",
                    "mediaUri": "https://www.cm.com/cdn/web/blog/content/logo-cmcom.png",
                    "mimeType": "image/jpeg"
                  }
                },
                "body": {
                  "text": "your-text-body-content"
                },
                "footer": {
                  "text": "your-text-footer-content"
                },
                "action": {
                  "buttons": [
                    {
                      "type": "openurl",
                      "id": "unique-postback-id",
                      "title": "Button",
                      "url": "your url"
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    ]
  }
}

{
  "messages": {
    "msg": [
      {
        "from": "00316098765432",
        "to": [
          {
            "number": "00316012345678"
          }
        ],
        "body": {
          "type": "auto",
          "content": "This is a WhatsApp message"
        },
        "validity": "2026-04-21T18:00:00.0Z",
        "allowedChannels": [
          "WhatsApp"
        ],
        "richContent": {
          "conversation": [
            {
              "category": "utility", //category is necessary for Direct Send API usage
              "interactive": {
                "type": "button",
                "body": {
                  "text": "button_text"
                },
                "action": {
                  "buttons": [
                    {
                      "type": "reply",
                      "reply": {
                        "id": "1",
                        "title": "reply button here!"
                      }
                    },
                    {
                      "type": "reply",
                      "reply": {
                        "id": "2",
                        "title": "reply button 2 here!"
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    ]
  }
}

🚧

Warning

The only way to determine a Direct Send API message is by adding the category parameter.

Time To Live (TTL) Messages

The Direct Send API Beta now supports custom message expiration times for Utility messages. Custom TTL is only available for Direct Send API with category=utility. This is the amount of time that Meta will use to deliver the message to end-users.

Allowed values:

  • Minimum TTL: 30 seconds from now.
  • Maximum TTL: 12 hours from now.

If not provided or left empty, it will be 30 days by default.

Error Handling for TTL

Invalid TTL Values

Minimum Value Not Met
The validity parameter requires a minimum value of 30 seconds from now. Requests with values below this threshold will be rejected by Meta.

Maximum Value Exceeded
The validity parameter accepts a maximum value of 43,200 seconds (12 hours) from now. Requests with values exceeding this limit will be rejected by Meta.

Message Expiration Behavior
When a message cannot be delivered to the recipient within the configured TTL period (either default or custom), Meta will automatically drop the message. This message will not be sent.

❗️

Important Considerations from Meta

No error or notification is generated when a message is dropped due to TTL expiration from Meta.
Messages are permanently removed from the queue once the TTL expires on Meta side.
This behavior applies to both default (30 days) and custom TTL values

Please refer to Validity Period section to see how to configure the validity parameter correctly. Validity Period.

{
  "messages": {
    "msg": [
      {
        "RichContent": {
          "conversation": [
            {
              "content": "text",
              "text": "MT message",
              "category": "utility" //only for Direct Send API
            }
          ]
        },
        "allowedChannels": [
          "WhatsApp"
        ],
        "body": {
          "content": "text"
        },
        "validity": "2026-04-21T18:00:00.0Z", //validity for TTL. Current time  2026-04-21T12:00:00.0Z
        "from": "00316098765432",
        "to": [
          {
            "number": "00316012345678"
          }
        ]
      }
    ]
  }
}

{
  "messages": {
    "msg": [
      {
        "from": "00316098765432",
        "to": [
          {
            "number": "00316012345678"
          }
        ],
        "body": {
          "type": "auto",
          "content": "This is a WhatsApp message"
        },
        "validity": "2026-04-21T18:00:00.0Z", //validity for TTL. Current time  2026-04-21T12:00:00.0Z
        "allowedChannels": [
          "WhatsApp"
        ],
        "richContent": {
          "conversation": [
            {
              "category": "utility", //only for Direct Send API
              "interactive": {
                "type": "button",
                "header": {
                  "type": "image",
                  "media": {
                    "mediaName": "CM.com - Be part of it.",
                    "mediaUri": "https://www.cm.com/cdn/web/blog/content/logo-cmcom.png",
                    "mimeType": "image/jpeg"
                  }
                },
                "body": {
                  "text": "your-text-body-content"
                },
                "footer": {
                  "text": "your-text-footer-content"
                },
                "action": {
                  "buttons": [
                    {
                      "type": "openurl",
                      "id": "unique-postback-id",
                      "title": "Button",
                      "url": "your url"
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    ]
  }
}

{
  "messages": {
    "msg": [
      {
        "from": "00316098765432",
        "to": [
          {
            "number": "00316012345678"
          }
        ],
        "body": {
          "type": "auto",
          "content": "This is a WhatsApp message"
        },
        "validity": "2026-04-21T18:00:00.0Z", //validity for TTL. Current time  2026-04-21T12:00:00.0Z
        "allowedChannels": [
          "WhatsApp"
        ],
        "richContent": {
          "conversation": [
            {
              "category": "utility", //only for Direct Send API
              "interactive": {
                "type": "button",
                "body": {
                  "text": "button_text"
                },
                "action": {
                  "buttons": [
                    {
                      "type": "reply",
                      "reply": {
                        "id": "1",
                        "title": "reply button here!"
                      }
                    },
                    {
                      "type": "reply",
                      "reply": {
                        "id": "2",
                        "title": "reply button 2 here!"
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    ]
  }
}

📘

Validity Example

If the current date and time is 2026-04-21T12:00:00.0Z and you want to configure a custom TTL for your Direct Send API to expire 6 hours later, the validity should be set to 2026-04-21T18:00:00.0Z.

Updated 1 day ago