# Add contacts to broadcast

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

`POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/contacts`

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

## Parameters

- `broadcastId` (path, string, required)

## Body

- `contacts` (object[], 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.
    - `{key}` (string)
  - `templateButtonVariables` (object): Per-contact button variables for dynamic URL/OTP buttons. Keys are the button index (0, 1, 2).
    - `{key}` (string)
  - `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.
    - `{key}` (string)

## Responses

### 201

Contacts added.

- `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)

### 400

Invalid request or broadcast not in draft status.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 404

Broadcast not found.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X POST "https://api.zavu.dev/v1/broadcasts/broadcast_abc123/contacts" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contacts": [
    {
      "recipient": "+14155551234",
      "templateVariables": {
        "name": "John",
        "order_id": "ORD-001"
      }
    },
    {
      "recipient": "+14155555678",
      "templateVariables": {
        "name": "Jane",
        "order_id": "ORD-002"
      }
    }
  ]
}'
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.broadcasts.contacts.add("broadcast_abc123", {
  contacts: [
    {
      recipient: "+14155551234",
      templateVariables: {
        name: "John",
        order_id: "ORD-001",
      },
    },
    {
      recipient: "+14155555678",
      templateVariables: {
        name: "Jane",
        order_id: "ORD-002",
      },
    },
  ],
});

console.log(result);
```