Send a Message

In this quickstart, you'll learn how to send a template message using the WhatsApp Business API. Template messages allow you to initiate conversations with users when there has been no interaction in the past 24 hours.

1

Verify Template Availability

Before sending a template message, check that your template is approved and ready to use:

curl --request GET \
  --url https://waba-v2.360dialog.io/v1/configs/templates \
  --header 'D360-API-KEY: your_api_key' \
  --header 'Content-Type: application/json'

Confirm that your template shows a status of "APPROVED" in the response. Only templates with an active status can be sent to users.

2

Prepare Your Template Parameters

Most template messages contain variables (parameters) that need to be filled with specific information for each recipient.

For example, if your template is:

Thank you for your order, {{1}}! Your confirmation number is {{2}}.

Identify the variables you need to replace:

• {{1}} will be the customer's name

• {{2}} will be the order number

Make sure you have these values ready before sending your message.

3

Send Your Template Message

Use the /messages endpoint to send your template message:

curl --request POST \
  --url https://waba-v2.360dialog.io/messages \
  --header 'D360-API-KEY: your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "15551234567",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": {
        "code": "en_US"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Maria"
            },
            {
              "type": "text",
              "text": "B67890"
            }
          ]
        }
      ]
    }
  }'

This sends the "order_confirmation" template to the specified phone number, replacing the variables with "Maria" and "B67890".

4

Check The Response

After sending your request, you'll receive a response containing a message ID:

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "15551234567",
      "wa_id": "15551234567"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
    }
  ]
}

Save this message ID to track the delivery status of your message.

5

Monitor Message Status

Set up a webhook endpoint in your application to receive message status updates. The webhook will receive notifications when the message is:

• sent: Message has been sent from your WABA

• delivered: Message has reached the recipient's device

• read: Recipient has opened and read the message

• failed: Message failed to send

A typical status webhook looks like this:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "PHONE_NUMBER",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
                "status": "delivered",
                "timestamp": "1675175992",
                "recipient_id": "15551234567"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

This webhook tells you that the message was delivered to the recipient's device.

Common Template Types

Text Templates

The simplest type of template with only text content and variables:

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "appointment_reminder",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "February 25, 2023"
            }
          }
        ]
      }
    ]
  }
}

Media Templates

Templates that include images, videos, or documents:

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "product_update",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/product.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "New Summer Collection"
          }
        ]
      }
    ]
  }
}

Interactive Templates

Templates with buttons for quick replies or actions:

{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "order_feedback",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "B67890"
          }
        ]
      },
      {
        "type": "buttons"
      }
    ]
  }
}

Best Practices

• Send template messages at appropriate times based on the recipient's time zone

• Use template parameters to personalize messages for each recipient

• Monitor message delivery rates and adjust your strategy if delivery rates drop

• For marketing templates, focus on making the first 5 lines engaging due to text truncation

Troubleshooting If your template message fails to send, check for these common issues:

• Incorrect template name or namespace

• Missing or incorrect parameters

• Template has been paused or disabled due to poor quality rating

• Recipient may have blocked messages from your business

• Per-user marketing template limits may be in effect (error code 131049)

That's it! You've now sent your first template message using the WhatsApp Business API. For more information about template messages, see the Template Messages documentation.