Send Template Messages

POST

businesses

{businessId}

send

whatsapp_templated_messages

Send Template Messages

curl --request POST \
  --url https://api.example.com/v1/businesses/{businessId}/send/whatsapp_templated_messages

const options = {method: 'POST'};

fetch('https://api.example.com/v1/businesses/{businessId}/send/whatsapp_templated_messages', 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.example.com/v1/businesses/{businessId}/send/whatsapp_templated_messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.example.com/v1/businesses/{businessId}/send/whatsapp_templated_messages"

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

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/businesses/{businessId}/send/whatsapp_templated_messages")

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

request = Net::HTTP::Post.new(url)

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

Template messages are pre-approved formats managed in your WhatsApp Manager (inside Facebook Business Manager). Because Meta approves them in advance, you can send them to any customer at any time, including first-time contacts and customers whose 24-hour session has expired.

Your template must be created and approved in WhatsApp Manager before you can reference it here. Contact the Connectly team if you need help getting a template approved.

Template messages can only be sent to personal WhatsApp accounts, not to WhatsApp API (business) accounts. When testing, use your personal WhatsApp number and make sure it has accepted all WhatsApp app and privacy updates.

Endpoint

POST /v1/businesses/{businessId}/send/whatsapp_templated_messages

POST https://api.connectly.ai/v1/businesses/{businessId}/send/whatsapp_templated_messages

Rate limit: 200 requests/second. Exceeding this returns 429 Too Many Requests.

Request body

Field	Type	Required	Description
`number`	string	Yes	Recipient’s WhatsApp number in E.164 format (e.g. `+16502223333`). To target a BSUID customer, use the prefixed form `bsuid:US.…`.
`templateName`	string	Yes	Exact name of the approved template in your WhatsApp Manager.
`language`	string	Yes	Language code for the template translation (e.g. `en`, `en_US`, `pt_BR`, `es`). The template must have an approved translation for this language.
`parameters`	array	No	Variable substitution objects. See Template parameters below.
`sender`	string	No	Your WhatsApp sender number in E.164 format. Only required when you have more than one WhatsApp number registered with Connectly.
`callbackData`	any	No	Up to 1024 bytes of JSON echoed back in webhook events for this message. See callbackData.
`campaignName`	string	No	Tags this send with a campaign name for analytics.

Response

{ "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }

The id uniquely identifies the message. Use it to correlate delivery status webhook events (sent, delivered, read, delivery_failed).

Template parameters

The parameters array substitutes variables in your template’s header, body, and buttons. Each object has a name and value, plus an optional filename for document headers.

"parameters": [
  { "name": "header_document", "value": "https://example.com/invoice.pdf", "filename": "invoice.pdf" },
  { "name": "body_1", "value": "John" },
  { "name": "body_2", "value": "Order #98765" }
]

Available name values:

Category	Name	Description
Header	`header_text`	Substitutes a text variable in the template header.
Header	`header_image`	Sets a header image. `value` must be a public image URL.
Header	`header_document`	Sets a header document. `value` must be a public document URL. Pair with `filename` to control the displayed file name.
Body	`body_1` … `body_15`	Substitutes the 1st through 15th variable in the template body, in order.
Buttons	`button_1_url_suffix`	Appended to the base URL of button 1.
Buttons	`button_2_url_suffix`	Appended to the base URL of button 2.
Buttons	`button_3_url_suffix`	Appended to the base URL of button 3.
Buttons	`button_N_custom_wa_flow_action_data`	JSON string with the initial screen data for a WhatsApp Flow button at position N. Optional; only if the flow’s entry screen needs starting data.
Carousel	`card.N.header.image`	Image URL for carousel card N (zero-indexed).
Carousel	`card.N.body.M`	Body variable M of carousel card N (both zero-indexed).
Carousel	`card.N.button.M.urlSuffix`	URL suffix for button M of carousel card N.

callbackData

Set callbackData to any JSON value up to 1024 bytes. Connectly echoes it back in every webhook event tied to this message:

Delivery status events: sent, delivered, read, delivery_failed
Inbound replies that reference this message: quoted replies, button & list replies, reactions

Plain-text replies that don’t quote the original message do not include callbackData. Exceeding 1024 bytes returns a 400 error.

{
  "number": "+16044441234",
  "templateName": "order_confirmation",
  "language": "en",
  "parameters": [{ "name": "body_1", "value": "John" }],
  "callbackData": { "order_id": "12345" }
}

Examples

Text header + body variables

{
  "number": "+16044441234",
  "templateName": "my_template_name",
  "language": "en",
  "parameters": [
    { "name": "header_text", "value": "Hello" },
    { "name": "body_1", "value": "John" },
    { "name": "body_2", "value": "red" }
  ]
}

Image header + body variables (Brazilian Portuguese)

{
  "number": "+16044441234",
  "templateName": "external_header_test2",
  "language": "pt_BR",
  "parameters": [
    { "name": "header_image", "value": "https://i.picsum.photos/id/695/200/300" },
    { "name": "body_1", "value": "Connectly.ai" },
    { "name": "body_2", "value": "John" },
    { "name": "body_3", "value": "a new party" },
    { "name": "body_4", "value": "McDonald's" },
    { "name": "body_5", "value": "celebrate" }
  ]
}

Document header

{
  "number": "+16044441234",
  "templateName": "external_header_document",
  "language": "en",
  "parameters": [
    {
      "name": "header_document",
      "value": "https://example.com/invoice.pdf",
      "filename": "invoice.pdf"
    }
  ]
}

Link button with URL suffix (Spanish)

The value is appended to the button’s configured base URL, e.g. a base of www.facebook.com/ becomes www.facebook.com/connectlyai.

{
  "number": "+16044441234",
  "templateName": "external_link_button",
  "language": "es",
  "parameters": [
    { "name": "button_1_url_suffix", "value": "connectlyai" }
  ]
}

Carousel template

Create the carousel template first using the Template Management API, then reference it here with per-card parameters.

{
  "number": "+16044441234",
  "templateName": "carousel_demo_1",
  "language": "en_US",
  "parameters": [
    { "name": "card.0.header.image", "value": "https://example.com/card1.png" },
    { "name": "card.0.body.0", "value": "Summer Sale" },
    { "name": "card.0.button.0.urlSuffix", "value": "summer2024" },
    { "name": "card.1.header.image", "value": "https://example.com/card2.png" },
    { "name": "card.1.body.0", "value": "Up to 50% off" },
    { "name": "card.1.button.0.urlSuffix", "value": "sale50" }
  ]
}

To receive events when recipients tap carousel buttons, subscribe to the Webhook API.

Send from a specific number (multi-sender)

Include sender when your business has more than one WhatsApp number registered with Connectly.

{
  "sender": "+14151111234",
  "number": "+16044441111",
  "templateName": "order_confirmation",
  "language": "en",
  "parameters": []
}

Template languages

Your template can have multiple approved language translations. Specify the correct code in the language field, the template must have an approved translation for the language you request. See Meta’s language list for all supported codes.

Language	Code
English	`en`
English (US)	`en_US`
Brazilian Portuguese	`pt_BR`
Spanish	`es`

Targeting by BSUID

To target a customer identified by a Business-Scoped User ID, set number to the prefixed form bsuid:US.… (e.g. bsuid:US.13491208655302741918). See Business-scoped user IDs (BSUID) for full details.

Sending to phone-less (BSUID-only) customers is not yet available and currently returns a 400 error. Authentication templates (one-tap, zero-tap, copy-code) cannot use BSUIDs, they require a phone number.

Error responses

Status	Meaning
`400`	Malformed body, unapproved template, or `callbackData` exceeds 1024 bytes.
`401`	Missing or invalid `X-API-Key`.
`429`	Rate limit exceeded (200 req/s).
`500`	Internal server error.

See Error codes for the full list of error types and codes.

Messaging Overview

Send Session Messages

Get Started

Campaigns

Messaging

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Resources

Send Template Messages

Endpoint

Request body

Response

Template parameters

callbackData

Examples

Template languages

Targeting by BSUID

Error responses

​Endpoint

​Request body

​Response

​Template parameters

​callbackData

​Examples

​Template languages

​Targeting by BSUID

​Error responses

Endpoint

Request body

Response

Template parameters

callbackData

Examples

Template languages

Targeting by BSUID

Error responses