Send a template notification

Send one approved WhatsApp template to one person with one API request.

Send one approved WhatsApp template message to one person with one API request.

The Channel360 web app and the API send messages separately. The API ignores template tag settings. Put your actual placeholder values in the API request.

The template must exist under your organisation and be approved by WhatsApp. Tags vs. the API explains the difference.

Words used on this page

Term	Meaning
Notification	One WhatsApp message sent to one person through the API.
Template	A WhatsApp-approved message. It can contain numbered blanks such as {{1}}.
Placeholder	A numbered blank in a template.
Component	A part of a template: header, body or button. In the request these are written in lowercase.
Parameters	Values that fill placeholders, in order.

Before you start

• An API key — Settings → Developer Settings → API keys tab → Create.

• Your Organisation API URL — the Copy button on the API details card on the same page.

• A webhook, so you can see what happened to the message — see Receive delivery updates.

Authentication explains the key and URL in more detail.

Steps

1. Check the template

1. Open Templates in the Channel360 web app.

2. Create the template or select an existing one.

3. Wait until its status is APPROVED.

4. Copy its exact name and language code.

5. Note each placeholder and its order.

For example, record order_shipped, en, and {{1}}, {{2}}, {{3}}.

You do not need to configure template tags for API sends.

2. Build the request

Send a POST request to:

https://channel360.co.za/v1.1/org/<ORG_ID>/notification

Add these headers:

Authorization: Bearer <API_KEY>
Content-Type: application/json

Field	Required	Value
destination	Yes	Recipient mobile number in international format, country code included, digits only. Example: 27821234567.
message.type	Yes	Always "template".
message.template.name	Yes	Exact approved template name.
message.template.language.code	Yes	Exact approved language code, such as "en".
message.template.components	Yes	Components and parameters to fill. Use [] when there are no placeholders.
msg_id	No	Your reference, such as an order number. It comes back in delivery updates.

3. Fill placeholders

Add a component for each template part that has placeholders.

List the parameters in placeholder order. The first parameter fills {{1}}.

For a template with Hi {{1}}, welcome to Acme!, send:

{
  "destination": "27821234567",
  "message": {
    "type": "template",
    "template": {
      "name": "welcome_message",
      "language": { "code": "en" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Sipho" }
          ]
        }
      ]
    }
  }
}

See Filling template placeholders for media headers and URL buttons.

4. Send it

Replace the values inside <…> before running this command.

cURL

curl -X POST "https://channel360.co.za/v1.1/org/<ORG_ID>/notification" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "27821234567",
    "message": {
      "type": "template",
      "template": {
        "name": "welcome_message",
        "language": { "code": "en" },
        "components": [
          {
            "type": "body",
            "parameters": [
              { "type": "text", "text": "Sipho" }
            ]
          }
        ]
      }
    }
  }'

JavaScript

const response = await fetch(
  "https://channel360.co.za/v1.1/org/<ORG_ID>/notification",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <API_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      destination: "27821234567",
      message: {
        type: "template",
        template: {
          name: "welcome_message",
          language: { code: "en" },
          components: [
            {
              type: "body",
              parameters: [{ type: "text", text: "Sipho" }]
            }
          ]
        }
      }
    })
  }
);

console.log(await response.json());

Python

import requests

response = requests.post(
    "https://channel360.co.za/v1.1/org/<ORG_ID>/notification",
    headers={
        "Authorization": "Bearer <API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "destination": "27821234567",
        "message": {
            "type": "template",
            "template": {
                "name": "welcome_message",
                "language": {"code": "en"},
                "components": [
                    {
                        "type": "body",
                        "parameters": [{"type": "text", "text": "Sipho"}],
                    }
                ],
            },
        },
    },
)

print(response.json())

5. Check the response

A successful request returns HTTP 201 and a notification ID:

{ "notification": { "_id": "6710f3c2a1b2c3d4e5f60789" } }

201 means Channel360 accepted and queued the message. It does not mean the message was delivered.

Save the _id and your msg_id, if used. They help you match delivery updates.

6. Get delivery updates

Delivery results reach you only through webhooks. If no webhook is registered for your organisation, you cannot find out whether the message arrived.

Channel360 posts status updates to your webhook: sent, delivered, read or failed. They include your msg_id. See Receive delivery updates to set this up.

Check it worked

• The message arrives on the recipient's phone.

• Your webhook receives notification:delivery:channel when WhatsApp accepts the message.

• It then receives notification:delivery:user when the message reaches the phone.

• If it receives notification:delivery:failure instead, its error object says why.

What can go wrong

What you see	Why	What to do
400 Could not find a valid template	Channel360 cannot find a template with that name in your organisation.	Check the name, underscores and case. Check the organisation ID.
400 Template language code must be provided	message.template.language.code is missing.	Add "language": { "code": "en" }.
400 Organization Not Found	The organisation ID in the URL does not exist.	Copy the Organisation API URL again.
401 / 403 unauthorised	The API key is missing, wrong, or belongs to another organisation.	Check the Authorization: Bearer … header and organisation ID.
201, but no message arrives	The request was accepted. WhatsApp later rejected the message.	Check parameter counts, language, public media links and template approval. Check your webhook.

Every error message is listed in Troubleshooting.

Next

Filling template placeholdersReceive delivery updatesTags vs. the API