Adding Contacts

Add contacts to your broadcast before sending. Contacts can include personalization variables for customized messages.

Adding Contacts

const result = await zavu.broadcasts.contacts.add(broadcast.id, {
  contacts: [
    { recipient: "+14155551234" },
    { recipient: "+14155555678" },
    { recipient: "+14155559012" },
  ],
});

console.log(`Added: ${result.added}`);
console.log(`Duplicates: ${result.duplicates}`);
console.log(`Invalid: ${result.invalid}`);

result = zavu.broadcasts.contacts.add(broadcast.id, contacts=[
    {"recipient": "+14155551234"},
    {"recipient": "+14155555678"},
    {"recipient": "+14155559012"},
])

print(f"Added: {result.added}")
print(f"Duplicates: {result.duplicates}")
print(f"Invalid: {result.invalid}")

result = client.broadcasts.contacts.add(broadcast.id, contacts: [
  { recipient: "+14155551234" },
  { recipient: "+14155555678" },
  { recipient: "+14155559012" },
])

puts "Added: #{result.added}"
puts "Duplicates: #{result.duplicates}"
puts "Invalid: #{result.invalid}"

result, _ := client.Broadcasts.Contacts.Add(context.TODO(), broadcast.ID, zavudev.BroadcastAddContactsParams{
	Contacts: []zavudev.BroadcastContactInput{
		{Recipient: zavudev.String("+14155551234")},
		{Recipient: zavudev.String("+14155555678")},
		{Recipient: zavudev.String("+14155559012")},
	},
})

fmt.Printf("Added: %d\n", result.Added)
fmt.Printf("Duplicates: %d\n", result.Duplicates)
fmt.Printf("Invalid: %d\n", result.Invalid)

$result = $client->broadcasts->contacts->add($broadcast->id, [
    'contacts' => [
        ['recipient' => '+14155551234'],
        ['recipient' => '+14155555678'],
        ['recipient' => '+14155559012'],
    ],
]);

echo "Added: {$result->added}\n";
echo "Duplicates: {$result->duplicates}\n";
echo "Invalid: {$result->invalid}\n";

curl -X POST https://api.zavu.dev/v1/broadcasts/{broadcastId}/contacts \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"recipient": "+14155551234"},
      {"recipient": "+14155555678"},
      {"recipient": "+14155559012"}
    ]
  }'

Response

{
  "added": 3,
  "duplicates": 0,
  "invalid": 0,
  "errors": []
}

With Personalization

Add template variables for each contact to personalize messages:

await zavu.broadcasts.contacts.add(broadcast.id, {
  contacts: [
    {
      recipient: "+14155551234",
      templateVariables: {
        name: "John Smith",
        order_id: "ORD-12345",
        delivery_date: "January 20th",
      },
    },
    {
      recipient: "+14155555678",
      templateVariables: {
        name: "Jane Doe",
        order_id: "ORD-12346",
        delivery_date: "January 21st",
      },
    },
  ],
});

The message template Hi {{name}}, your order #{{order_id}} arrives {{delivery_date}}! becomes:

John: “Hi John Smith, your order #ORD-12345 arrives January 20th!”
Jane: “Hi Jane Doe, your order #ORD-12346 arrives January 21st!”

Per-contact URL button variables

If the template has a dynamic URL button (e.g., https://example.com/orders/{{1}}), supply each contact’s value via templateButtonVariables. Keys are the button index in the template’s buttons array ("0", "1", "2").

await zavu.broadcasts.contacts.add(broadcast.id, {
  contacts: [
    {
      recipient: "+14155551234",
      templateVariables: { "1": "John Smith" },
      templateButtonVariables: { "0": "ORD-12345" },
    },
    {
      recipient: "+14155555678",
      templateVariables: { "1": "Jane Doe" },
      templateButtonVariables: { "0": "ORD-12346" },
    },
  ],
});

When a contact omits templateButtonVariables, the broadcast falls back to the defaults defined on the broadcast itself.

Batch Processing

Add contacts in batches of up to 1,000 per request. For larger lists, make multiple requests:

const BATCH_SIZE = 1000;

async function addAllContacts(broadcastId: string, allContacts: Contact[]) {
  let totalAdded = 0;

  for (let i = 0; i < allContacts.length; i += BATCH_SIZE) {
    const batch = allContacts.slice(i, i + BATCH_SIZE);

    const result = await zavu.broadcasts.contacts.add(broadcastId, {
      contacts: batch.map(c => ({
        recipient: c.phone,
        templateVariables: { name: c.name },
      })),
    });

    totalAdded += result.added;
    console.log(`Batch ${Math.floor(i / BATCH_SIZE) + 1}: Added ${result.added} contacts`);
  }

  return totalAdded;
}

Recipient Formats

Channel	Format	Example
SMS	E.164 phone	`+14155551234`
WhatsApp	E.164 phone	`+14155551234`
Email	Email address	`user@example.com`

Phone numbers must be in E.164 format (starting with + and country code). Invalid formats will be rejected.

Handling Duplicates

The API automatically deduplicates contacts:

Within request: If the same recipient appears twice in one request, only one is added
Across requests: If a recipient is already in the broadcast, they won’t be added again

{
  "added": 8,
  "duplicates": 2,
  "invalid": 0,
  "errors": []
}

Handling Invalid Contacts

Invalid contacts are rejected with detailed errors:

{
  "added": 7,
  "duplicates": 0,
  "invalid": 3,
  "errors": [
    { "recipient": "invalid-phone", "reason": "Invalid phone number format" },
    { "recipient": "+1234", "reason": "Phone number too short" },
    { "recipient": "not-an-email", "reason": "Invalid email format" }
  ]
}

Validate phone numbers before adding them to avoid high rejection rates. Use E.164 format: +[country code][number] with no spaces or dashes.

Listing Contacts

View contacts in a broadcast:

const contacts = await zavu.broadcasts.contacts.list(broadcast.id, {
  limit: 50,
});

for (const contact of contacts.items) {
  console.log(`${contact.recipient}: ${contact.status}`);
}

// Paginate through all contacts
if (contacts.nextCursor) {
  const nextPage = await zavu.broadcasts.contacts.list(broadcast.id, {
    cursor: contacts.nextCursor,
  });
}

contacts = zavu.broadcasts.contacts.list(broadcast.id, limit=50)

for contact in contacts.items:
    print(f"{contact.recipient}: {contact.status}")

# Paginate through all contacts
if contacts.next_cursor:
    next_page = zavu.broadcasts.contacts.list(
        broadcast.id, cursor=contacts.next_cursor
    )

contacts = client.broadcasts.contacts.list(broadcast.id, limit: 50)

contacts.items.each do |contact|
  puts "#{contact.recipient}: #{contact.status}"
end

# Paginate through all contacts
if contacts.next_cursor
  next_page = client.broadcasts.contacts.list(
    broadcast.id, cursor: contacts.next_cursor
  )
end

contacts, _ := client.Broadcasts.Contacts.List(context.TODO(), broadcast.ID, zavudev.BroadcastListContactsParams{
	Limit: zavudev.Int(50),
})

for _, contact := range contacts.Items {
	fmt.Printf("%s: %s\n", contact.Recipient, contact.Status)
}

// Paginate through all contacts
if contacts.NextCursor != nil {
	nextPage, _ := client.Broadcasts.Contacts.List(context.TODO(), broadcast.ID, zavudev.BroadcastListContactsParams{
		Cursor: contacts.NextCursor,
	})
	_ = nextPage
}

$contacts = $client->broadcasts->contacts->list($broadcast->id, [
    'limit' => 50,
]);

foreach ($contacts->items as $contact) {
    echo "{$contact->recipient}: {$contact->status}\n";
}

// Paginate through all contacts
if ($contacts->nextCursor) {
    $nextPage = $client->broadcasts->contacts->list($broadcast->id, [
        'cursor' => $contacts->nextCursor,
    ]);
}

curl "https://api.zavu.dev/v1/broadcasts/{broadcastId}/contacts?limit=50" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Response

{
  "items": [
    {
      "id": "bc_abc123",
      "recipient": "+14155551234",
      "recipientType": "phone",
      "status": "pending",
      "templateVariables": { "name": "John" },
      "createdAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "bc_def456",
      "recipient": "+14155555678",
      "recipientType": "phone",
      "status": "pending",
      "templateVariables": { "name": "Jane" },
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6ImJjX2RlZjQ1NiJ9"
}

Filtering by Status

Filter contacts by delivery status:

curl "https://api.zavu.dev/v1/broadcasts/{broadcastId}/contacts?status=failed" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

Status	Description
`pending`	Not yet sent
`queued`	Message created, waiting to send
`sending`	Currently being sent
`delivered`	Successfully delivered
`failed`	Delivery failed
`skipped`	Skipped (broadcast cancelled)

Removing Contacts

Remove a contact before the broadcast is sent:

// The broadcast contact id comes first; the broadcast it belongs to is a param.
await zavu.broadcasts.contacts.remove(contact.id, { broadcastId: broadcast.id });

Contacts can only be removed while the broadcast is in draft status. Once sending begins, contacts cannot be removed.

Limits

Limit	Value	Notes
Contacts per request	1,000	Make multiple requests for larger lists
Contacts per broadcast	1,000 (default)	Contact support to increase this limit
Template variable size	1,024 chars	Per variable

Next Steps

Sending & Scheduling

Send your broadcast or schedule it for later

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

Adding Contacts

Adding Contacts

Response

With Personalization

Per-contact URL button variables

Batch Processing

Recipient Formats

Handling Duplicates

Handling Invalid Contacts

Listing Contacts

Response

Filtering by Status

Removing Contacts

Limits

Next Steps

Sending & Scheduling

​Adding Contacts

​Response

​With Personalization

​Per-contact URL button variables

​Batch Processing

​Recipient Formats

​Handling Duplicates

​Handling Invalid Contacts

​Listing Contacts

​Response

​Filtering by Status

​Removing Contacts

​Limits

​Next Steps

Sending & Scheduling

Adding Contacts

Response

With Personalization

Per-contact URL button variables

Batch Processing

Recipient Formats

Handling Duplicates

Handling Invalid Contacts

Listing Contacts

Response

Filtering by Status

Removing Contacts

Limits

Next Steps