Send Template Messages

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.
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.

​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