Send WhatsApp Template

curl --request POST \
  --url https://api.callkaro.ai/whatsapp/send-template \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "phone_number_id": "123456789012345",
  "to_number": "919876543210",
  "template_name": "order_shipped",
  "language_code": "en",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Rahul"
        },
        {
          "type": "text",
          "text": "#1234"
        }
      ]
    }
  ],
  "wa_campaign_id": "spring_promo_2026",
  "metadata": {
    "plan_type": "Gold",
    "City": "Delhi"
  }
}
'

import requests

url = "https://api.callkaro.ai/whatsapp/send-template"

payload = {
    "phone_number_id": "123456789012345",
    "to_number": "919876543210",
    "template_name": "order_shipped",
    "language_code": "en",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "Rahul"
                },
                {
                    "type": "text",
                    "text": "#1234"
                }
            ]
        }
    ],
    "wa_campaign_id": "spring_promo_2026",
    "metadata": {
        "plan_type": "Gold",
        "City": "Delhi"
    }
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phone_number_id: '123456789012345',
    to_number: '919876543210',
    template_name: 'order_shipped',
    language_code: 'en',
    components: [
      {
        type: 'body',
        parameters: [{type: 'text', text: 'Rahul'}, {type: 'text', text: '#1234'}]
      }
    ],
    wa_campaign_id: 'spring_promo_2026',
    metadata: {plan_type: 'Gold', City: 'Delhi'}
  })
};

fetch('https://api.callkaro.ai/whatsapp/send-template', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.callkaro.ai/whatsapp/send-template",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number_id' => '123456789012345',
    'to_number' => '919876543210',
    'template_name' => 'order_shipped',
    'language_code' => 'en',
    'components' => [
        [
                'type' => 'body',
                'parameters' => [
                                [
                                                                'type' => 'text',
                                                                'text' => 'Rahul'
                                ],
                                [
                                                                'type' => 'text',
                                                                'text' => '#1234'
                                ]
                ]
        ]
    ],
    'wa_campaign_id' => 'spring_promo_2026',
    'metadata' => [
        'plan_type' => 'Gold',
        'City' => 'Delhi'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.callkaro.ai/whatsapp/send-template"

	payload := strings.NewReader("{\n  \"phone_number_id\": \"123456789012345\",\n  \"to_number\": \"919876543210\",\n  \"template_name\": \"order_shipped\",\n  \"language_code\": \"en\",\n  \"components\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"Rahul\"\n        },\n        {\n          \"type\": \"text\",\n          \"text\": \"#1234\"\n        }\n      ]\n    }\n  ],\n  \"wa_campaign_id\": \"spring_promo_2026\",\n  \"metadata\": {\n    \"plan_type\": \"Gold\",\n    \"City\": \"Delhi\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.callkaro.ai/whatsapp/send-template")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number_id\": \"123456789012345\",\n  \"to_number\": \"919876543210\",\n  \"template_name\": \"order_shipped\",\n  \"language_code\": \"en\",\n  \"components\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"Rahul\"\n        },\n        {\n          \"type\": \"text\",\n          \"text\": \"#1234\"\n        }\n      ]\n    }\n  ],\n  \"wa_campaign_id\": \"spring_promo_2026\",\n  \"metadata\": {\n    \"plan_type\": \"Gold\",\n    \"City\": \"Delhi\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.callkaro.ai/whatsapp/send-template")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number_id\": \"123456789012345\",\n  \"to_number\": \"919876543210\",\n  \"template_name\": \"order_shipped\",\n  \"language_code\": \"en\",\n  \"components\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"Rahul\"\n        },\n        {\n          \"type\": \"text\",\n          \"text\": \"#1234\"\n        }\n      ]\n    }\n  ],\n  \"wa_campaign_id\": \"spring_promo_2026\",\n  \"metadata\": {\n    \"plan_type\": \"Gold\",\n    \"City\": \"Delhi\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Template sent",
  "message_id": "wamid.HBgMOTE5..."
}

{
  "status": "error",
  "message": "Footer text length invalid. Min length: 0, Max length: 60",
  "whatsapp_error": {
    "code": 400,
    "message": "..."
  }
}

{
  "status": "error",
  "message": "Invalid API key"
}

{
  "status": "error",
  "message": "phone_number_id does not belong to this account"
}

{
  "status": "error",
  "message": "Missing required field: to_number"
}

POST

send-template

Send WhatsApp Template

curl --request POST \
  --url https://api.callkaro.ai/whatsapp/send-template \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "phone_number_id": "123456789012345",
  "to_number": "919876543210",
  "template_name": "order_shipped",
  "language_code": "en",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Rahul"
        },
        {
          "type": "text",
          "text": "#1234"
        }
      ]
    }
  ],
  "wa_campaign_id": "spring_promo_2026",
  "metadata": {
    "plan_type": "Gold",
    "City": "Delhi"
  }
}
'

import requests

url = "https://api.callkaro.ai/whatsapp/send-template"

payload = {
    "phone_number_id": "123456789012345",
    "to_number": "919876543210",
    "template_name": "order_shipped",
    "language_code": "en",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "Rahul"
                },
                {
                    "type": "text",
                    "text": "#1234"
                }
            ]
        }
    ],
    "wa_campaign_id": "spring_promo_2026",
    "metadata": {
        "plan_type": "Gold",
        "City": "Delhi"
    }
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phone_number_id: '123456789012345',
    to_number: '919876543210',
    template_name: 'order_shipped',
    language_code: 'en',
    components: [
      {
        type: 'body',
        parameters: [{type: 'text', text: 'Rahul'}, {type: 'text', text: '#1234'}]
      }
    ],
    wa_campaign_id: 'spring_promo_2026',
    metadata: {plan_type: 'Gold', City: 'Delhi'}
  })
};

fetch('https://api.callkaro.ai/whatsapp/send-template', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.callkaro.ai/whatsapp/send-template",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number_id' => '123456789012345',
    'to_number' => '919876543210',
    'template_name' => 'order_shipped',
    'language_code' => 'en',
    'components' => [
        [
                'type' => 'body',
                'parameters' => [
                                [
                                                                'type' => 'text',
                                                                'text' => 'Rahul'
                                ],
                                [
                                                                'type' => 'text',
                                                                'text' => '#1234'
                                ]
                ]
        ]
    ],
    'wa_campaign_id' => 'spring_promo_2026',
    'metadata' => [
        'plan_type' => 'Gold',
        'City' => 'Delhi'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.callkaro.ai/whatsapp/send-template"

	payload := strings.NewReader("{\n  \"phone_number_id\": \"123456789012345\",\n  \"to_number\": \"919876543210\",\n  \"template_name\": \"order_shipped\",\n  \"language_code\": \"en\",\n  \"components\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"Rahul\"\n        },\n        {\n          \"type\": \"text\",\n          \"text\": \"#1234\"\n        }\n      ]\n    }\n  ],\n  \"wa_campaign_id\": \"spring_promo_2026\",\n  \"metadata\": {\n    \"plan_type\": \"Gold\",\n    \"City\": \"Delhi\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.callkaro.ai/whatsapp/send-template")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number_id\": \"123456789012345\",\n  \"to_number\": \"919876543210\",\n  \"template_name\": \"order_shipped\",\n  \"language_code\": \"en\",\n  \"components\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"Rahul\"\n        },\n        {\n          \"type\": \"text\",\n          \"text\": \"#1234\"\n        }\n      ]\n    }\n  ],\n  \"wa_campaign_id\": \"spring_promo_2026\",\n  \"metadata\": {\n    \"plan_type\": \"Gold\",\n    \"City\": \"Delhi\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.callkaro.ai/whatsapp/send-template")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number_id\": \"123456789012345\",\n  \"to_number\": \"919876543210\",\n  \"template_name\": \"order_shipped\",\n  \"language_code\": \"en\",\n  \"components\": [\n    {\n      \"type\": \"body\",\n      \"parameters\": [\n        {\n          \"type\": \"text\",\n          \"text\": \"Rahul\"\n        },\n        {\n          \"type\": \"text\",\n          \"text\": \"#1234\"\n        }\n      ]\n    }\n  ],\n  \"wa_campaign_id\": \"spring_promo_2026\",\n  \"metadata\": {\n    \"plan_type\": \"Gold\",\n    \"City\": \"Delhi\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Template sent",
  "message_id": "wamid.HBgMOTE5..."
}

{
  "status": "error",
  "message": "Footer text length invalid. Min length: 0, Max length: 60",
  "whatsapp_error": {
    "code": 400,
    "message": "..."
  }
}

{
  "status": "error",
  "message": "Invalid API key"
}

{
  "status": "error",
  "message": "phone_number_id does not belong to this account"
}

{
  "status": "error",
  "message": "Missing required field: to_number"
}

Sends an approved WhatsApp template to one recipient and records it in your Inbox, so the send appears in the conversation alongside everything your agent does.

Quick Example

curl -X POST "https://api.callkaro.ai/whatsapp/send-template" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "phone_number_id": "123456789012345",
    "to_number": "919876543210",
    "template_name": "order_shipped",
    "components": [
      { "type": "body", "parameters": [
        { "type": "text", "text": "Rahul" },
        { "type": "text", "text": "#1234" }
      ]}
    ],
    "metadata": {
      "plan_type": "Gold",
      "City": "Delhi"
    }
  }'

Use Cases

Transactional notifications: order confirmations, shipping updates, appointment reminders
Re-opening a conversation: outside the 24-hour customer service window a template is the only thing WhatsApp allows
Campaign attribution: pass wa_campaign_id so the send, its delivery status and any follow-ups all roll up to one campaign
Enriching your CRM as you send: pass metadata and the data you already have about this person is saved onto their contact, instead of being discarded after the send

What happens on your account

Ownership is verified

The phone_number_id is checked against your WhatsApp Business Account. A number that is not yours returns 403, so a valid API key can never send from another customer’s number.

The language is resolved

If you omit language_code, the language the template is actually approved in is used. Pass it explicitly to override.

The message is recorded

The rendered template is stored and appears in your Inbox. A rejected send is stored too, with Meta’s reason attached, rather than disappearing into the API response.

A contact is created if needed

If this number is not yet a contact, one is created with lead direction outbound. An existing contact is never reclassified.

metadata is saved onto that contact

Any metadata keys matching your contact attributes are written in the same operation, so one call sends the template and populates the contact.

Saving contact attributes with `metadata`

The data you already have about a person — their plan, their city, an order number — is usually worth keeping after the send. Pass it as metadata and it is saved onto that recipient’s CRM contact, exactly the way extra columns in a campaign CSV are.

{
  "phone_number_id": "123456789012345",
  "to_number": "919876543210",
  "template_name": "order_shipped",
  "metadata": {
    "plan_type": "Gold",
    "City": "Delhi"
  }
}

The response tells you what happened:

{
  "status": "success",
  "message": "Template sent",
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEw",
  "contact_updated": ["City", "plan_type"],
  "metadata_ignored": []
}

Rule	Behaviour
The attribute must already exist	Create it under Contacts → Attributes first, then use its name as the key. Keys matching no attribute are ignored and returned in `metadata_ignored`
Name matching is forgiving	Case, spaces, underscores and hyphens are ignored — `"Plan Type"`, `"plan_type"` and `"plantype"` all match the same attribute. The value is stored under the attribute’s own spelling
Blank values are skipped	Sending `""` or `null` leaves the stored value alone, so a partly-filled payload never wipes existing data
Hand-edited values are protected	An attribute someone edited by hand in the CRM is never overwritten by this API
Other attributes are untouched	Only the keys you send are written; everything else on the contact is left as-is
Failed sends save nothing	If Meta rejects the send you get a `400` and no contact is created or updated. Retry the whole call

Limits: at most 50 keys, each value at most 1000 characters. Both are rejected with a 400 rather than truncated — silently shortening a value would put corrupted data in your CRM with no way to tell.

metadata vs components. components fills the template’s variables for this one message. metadata is saved on the contact and persists. They are separate on purpose: a value in components is not stored on the contact, and metadata is never sent to WhatsApp. Send a value in both if you want it to do both.

Check metadata_ignored the first time you integrate. A mistyped or undefined attribute name does not fail the request — the message still goes out and the response lists what was dropped. If you never look, a typo surfaces much later as an empty column, with the sends already made.

Delivery status

The response message_id is WhatsApp’s wamid. Delivery is asynchronous, and a 200 here does not mean the user received the message.

Status	Reached the user?
`sent`	Not yet — WhatsApp accepted it, but it is not on the user’s device
`delivered`	Yes — on their device
`read`	Yes — opened
`failed` / `not sent`	No

A message starts at sent and only delivered or read confirms it arrived. To read the current status, use Get WhatsApp Messages, or subscribe to the message_status_updated webhook event.

Errors worth handling

400 with a whatsapp_error object

Meta rejected the send. The message field carries Meta’s own reason, which is specific — a wrong template name, a variable count that does not match the approved template, or a field over its length limit (footer max 60 characters, body max 1024). Fix the payload rather than retrying.

403 phone_number_id does not belong to this account

The number is not on your WABA. Check the ID in WhatsApp → Phone Numbers.

400 WhatsApp Business Account not linked

The account has no wabaId. Complete WhatsApp onboarding first.

400 metadata must be an object / too many keys / value too long

metadata has to be a JSON object of {attribute_name: value}, with at most 50 keys and values of at most 1000 characters. Note that an undefined attribute name is not an error — it is ignored and reported in metadata_ignored.

A rejected send is not retried for you, and a 400 will keep failing with the same payload. Only 5xx responses are worth retrying.

Authorizations

X-API-KEY

string

header

required

API key from https://callkaro.ai/dashboard/api-key

Body

application/json

phone_number_id

string

required

WhatsApp phone number ID you are sending from. Must belong to your WABA.

to_number

string

required

Recipient, digits only including country code.

template_name

string

required

Name of an approved WhatsApp template.

language_code

string

default:en

Defaults to the language the template is actually approved in when that can be resolved, otherwise "en".

components

object[]

Meta template components (variable values). Same shape Meta's own send API takes.

agent_id

string

Optional. Tags the stored message with one of your agents.

wa_campaign_id

string

Optional campaign to attribute this send to. 1-64 characters of letters, digits, '_' or '-'. Alias: waCampaignId. Follow-ups triggered by this message inherit it.

metadata

object

Optional. Contact attributes to save onto the recipient's CRM contact, as {attribute_name: value}. The attribute must already be defined on your account; keys matching no definition are ignored and listed in metadata_ignored. Name matching ignores case, spaces, underscores and hyphens. Blank values are skipped, and a value edited by hand in the CRM is never overwritten. Max 50 keys, each value max 1000 characters. Nothing is written if the send fails.

Show child attributes

Example:

{ "plan_type": "Gold", "City": "Delhi" }

extra

object

Optional. Stored verbatim on the message row. Unlike metadata, this is not written to the contact.

Response

Template sent

status

string

Example:

"success"

message

string

Example:

"Template sent"

message_id

string

WhatsApp message ID (wamid) of the sent message.

contact_updated

string[]

Attribute names from metadata that were saved onto the contact.

Example:

["City", "plan_type"]

metadata_ignored

string[]

metadata keys that matched no attribute definition and were dropped. The send still succeeded -- check this on first integration to catch a mistyped name.

Example:

[]

​Quick Example

​Use Cases

​What happens on your account

​Saving contact attributes with metadata

​Delivery status

​Errors worth handling

Authorizations

Body

Response

Quick Example

Use Cases

What happens on your account

Saving contact attributes with `metadata`

Delivery status

Errors worth handling