Template messages use a message template that has already been submitted to and approved by Meta for your WhatsApp Business Account. Unlike text messages, a template message can be sent to a customer at any time, even outside the 24-hour customer service window.

Endpoint

POST /messages.php

Request body

template.components is not re-validated by Riffre - it is forwarded to Meta exactly as sent, so it must match the structure Meta expects for your specific template (parameter count, type and order).

If the template has an IMAGE, VIDEO or DOCUMENT header, you must include a matching header component - use List Templates to check a template's header format before sending it. Omitting the header component when the template requires one is rejected with Meta error #132012 ("Parameter format does not match format in the created template... expected IMAGE, received UNKNOWN").

Example: template with an IMAGE header

A public HTTPS link works directly - Meta fetches it at send time, no separate upload needed. Use id instead of link if you already have a media ID from Upload Media.

{
  "to": "919876543210",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "link": "https://example.com/order-photo.jpg" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" }
        ]
      }
    ]
  }
}

For a VIDEO or DOCUMENT header, use "type": "video" / "type": "document" with a matching video/document object in the same shape.

Example: template with a body parameter

curl -X POST "https://your-riffre-domain.com/api/v1/messages.php" \
  -H "Authorization: Bearer rf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "type": "template",
    "template": {
      "name": "order_update",
      "language": { "code": "en_US" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "John" }
          ]
        }
      ]
    }
  }'

Example: template with no parameters

{
  "to": "919876543210",
  "type": "template",
  "template": {
    "name": "welcome_message",
    "language": { "code": "en_US" }
  }
}

Success response

Same shape as Send a Text Message: 202 Accepted with queue_id, status, status_label, charged, currency, balance_after, message_id and internal_queue_id.

Errors specific to this message type

If the template name, language or component structure does not match what is approved for your account, Meta will reject the message during delivery; that failure surfaces asynchronously as a failed status rather than as an immediate API error - see Message Status & Response Codes.