---
title: "Whatsapp template"
method: POST
path: "/whatsapp/template"
tags: ["WhatsApp"]
---

# Whatsapp template

`POST /whatsapp/template`

## Request

- Base URL: `https://api.commpeak.com/textpeak/streams`
- URL: `https://api.commpeak.com/textpeak/streams/whatsapp/template`
- Auth: API key in header `Authorization`

Send an approved WhatsApp Business template message to one or more recipients. Identify the template with `event`, and supply its variables per recipient by section: `HEADER`, `BODY` and `BUTTONS`.

`sender` is the WhatsApp Business number the template is sent from; it defaults to the stream's sender. A variable the template declares but you leave out is sent as a blank space, so the message still goes out — check your variables.

**Response.** HTTP `200` with a `task_id` and one entry per message. `status` is `false` when any message failed: failed entries come first and carry `error` (hex code) and `details`; accepted entries carry `message_uuid` (and `conversation_uuid` on two-way channels). Match entries by `internal_id`. Final delivery status is sent asynchronously to your configured webhook.

**Authentication:** stream token in the `Authorization` header (see **Authentication** in the API Overview).

## Request body

- WhatsAppTemplateRequest
  - `sender` string, nullable: WhatsApp Business sender phone number. Defaults to the stream's sender.
  - `event` string, nullable: The approved WhatsApp template, by its `eventKey` on the stream. Required unless every recipient sets `event`.
  - `recipients` WhatsAppTemplateRecipient[], required: The recipients, up to 250 per request.
    - `internal_id` string, nullable: Your identifier for the message. Echoed back in the response and in delivery webhooks (`internal_id`). Up to 36 characters are kept; longer values are cut. Not checked for uniqueness.
    - `sender` string, nullable: WhatsApp Business sender phone number for this recipient.
    - `event` string, nullable: Template for this recipient; overrides the top-level `event`.
    - `recipient_phone` string, nullable: Recipient phone number in international format, as a string. `+`, spaces, `-` and parentheses are removed before validation. Not needed when `conversation_uuid` or `contact.phone` identifies the recipient.
    - `template_variables` WhatsAppTemplateVariables
      - `HEADER` object, nullable: Header variables, `{ "name": "value" }`.
      - `BODY` object, nullable: Body variables, `{ "name": "value" }`.
      - `BUTTONS` object, nullable: Button variables per button index: `{ "idx_0": { "name": "value" } }`.
    - `contact` Contact
      - `display_name` string, nullable: Name shown in the inbox. Defaults to `first_name` + `last_name`.
      - `first_name` string, nullable: First name.
      - `last_name` string, nullable: Last name.
      - `phone` string, nullable: Phone number; used as the recipient when `recipient_phone` is not set.
      - `email` string, nullable: E-mail address.
      - `external_id` string, nullable: Your CRM identifier for the contact; stored as the conversation lead ID.
      - `additional` object, nullable: Extra contact attributes. `additional.lead_id` takes precedence over `external_id`.
    - `conversation_uuid` string, nullable: Continue an existing conversation: the sender and recipient are taken from it. Two-way channels only (WhatsApp, Telegram, two-way SMS); ignored on one-way SMS.

## Response `200`

Successful Response

- SendResponse
  - `status` boolean, required: `true` when every message was accepted; `false` when at least one failed. The HTTP status is `200` either way.
  - `task_id` string, required: Identifier of this request.
  - `messages` SendResultItem[], required: One entry per message. Failed messages are listed first, then accepted ones; match them by `internal_id`.
    - `internal_id` string, nullable: Your `internal_id`, echoed back (cut to 36 characters).
    - `message_uuid` string, nullable: Platform message identifier. Accepted messages only; use it with **Get message status**.
    - `conversation_uuid` string, nullable: The conversation the message belongs to. Two-way channels only.
    - `error` string, nullable: Failed messages only: the hex error code, for example `0x1` (invalid input), `0x19` (duplicate) or `0x31` (daily limit).
    - `details` string, nullable: Failed messages only: why it failed.

## Other responses

- `401`: Invalid token, or the token is not valid from this IP address.
- `402`: Payment required: the account balance is depleted (`0x41`).
- `403`: Missing token, blocked IP address, or the stream is not available (`0x11`, `0x16`, `0x21`, `0x22`).
- `422`: Validation Error
- `500`: The request was rejected as a whole (`0x0`): for example an unknown template or more than 250 items.

---

[API](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api.md) - [All operations](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api/llms.txt) - [OpenAPI document](https://skmtc.dev/commpeak/apis/commpeak-textpeak-streams-api/revisions/b9aaa8b4efa2?raw)