---
title: "Add contacts to broadcast"
method: POST
path: "/v1/broadcasts/{broadcastId}/contacts"
---

# Add contacts to broadcast

`POST /v1/broadcasts/{broadcastId}/contacts`

## Request

- Base URL: `https://api.zavu.dev`
- URL: `https://api.zavu.dev/v1/broadcasts/{broadcastId}/contacts`
- Auth: HTTP bearer

Add contacts to a broadcast in batch. Maximum 1000 contacts per request.

## Path parameters

- `broadcastId` string, required

## Request body

- BroadcastContactsAddRequest
  - `contacts` BroadcastContactInput[], required: List of contacts to add (max 1000 per request).
    - `recipient` string, required: Phone number (E.164) or email address. On a `telegram` broadcast, the numeric chat ID of someone who has already written to your bot (`838360395`, or `telegram:838360395`); a phone number is rejected there, because a bot cannot start a chat.
    - `templateVariables` object: Per-contact body variables. Key them to match the template body: by position (`1`, `2`, ...) for positional templates, or by name (e.g. `customer_name`) for named templates. Zavu detects the template's format and sends the correct payload to Meta. Do not mix positional and named keys.
    - `templateButtonVariables` object: Per-contact button variables for dynamic URL/OTP buttons. Keys are the button index (0, 1, 2).
    - `templateHeaderVariables` object: Per-contact value for a text-header variable, keyed by `1`. If omitted, Zavu resolves the header from `templateVariables` by the header placeholder's name.

## Response `201`

Contacts added.

- BroadcastContactsAddResponse
  - `added` integer, required: Number of contacts successfully added.
  - `duplicates` integer, required: Number of duplicate contacts skipped.
  - `invalid` integer, required: Number of invalid contacts rejected.
  - `errors` object[]: Details about invalid contacts.
    - `recipient` string
    - `reason` string

## Other responses

- `400`: Invalid request or broadcast not in draft status.
- `401`: Unauthorized.
- `404`: Broadcast not found.

## Changes

> 80 revisions in range; 1 not diffed.

- **2026-05-28** `fe72e5565564`: 1 info
  - added the new optional request property `contacts/items/templateHeaderVariables`
- **2026-05-15** `3e45958691da`: 1 info
  - added the new optional request property `contacts/items/templateButtonVariables`

[Operation history](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/changes/v1/broadcasts/:broadcastId/contacts/post.md)

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) - [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/75bc777b0ffb?raw)