---
title: "Broadcast to customers"
description: "Send one SMS or email notification to multiple recipients and track each resulting delivery."
canonical: "https://studio.inttegro.com/guides/broadcast-to-customers"
format: inttegro-machine-docs/v1
language: "PHP"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/php/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 533
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["get_message","list_messages"]
estimated_tokens: 2389
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Accept one same-transport audience and one content source for asynchronous fan-out; the broadcast ID tracks execution while each created Chime tracks recipient delivery.

### Five questions

#### Q1. Can a single broadcast mix SMS and email recipients?

No. Every recipient must resolve to one transport; an invalid contact rejects the request before acceptance. Use separate broadcasts for SMS and email, and the [Broadcast Chimes reference](https://studio.inttegro.com/machine/php/api/chimes.md#broadcast-chimes) for exact recipient shapes.

#### Q2. How should message content be chosen?

Use the documented raw message or one published, channel-matched template with valid variables; do not combine an inline email object and stored template source. [Message templates](https://studio.inttegro.com/machine/php/api/message-templates.md) owns publish and preview rules.

#### Q3. Does 202 Accepted mean every recipient was reached?

No. Preserve the broadcast ID, [look up the broadcast](https://studio.inttegro.com/machine/php/api/chimes.md#lookup-a-broadcast) for its created Chime IDs and per-recipient errors, then [look up each Chime](https://studio.inttegro.com/machine/php/api/chimes.md#lookup-chime) for transmission and delivery.

#### Q4. Is cancellation an approval window?

No. [Cancel a broadcast](https://studio.inttegro.com/machine/php/api/chimes.md#cancel-a-broadcast) works only before completion, and immediate fan-out may finish quickly. Confirm audience and content before submission and use a stable idempotency key for an uncertain request.

#### Q5. Can MCP submit the audience?

No current MCP action broadcasts or cancels. [list_messages](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#list_messages) and [get_message](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#get_message) can review resulting Chimes. Never use broadcasts for OTP; use [OTP verification](https://studio.inttegro.com/machine/php/api/otps.md) and the [Chimes API](https://studio.inttegro.com/machine/php/api/chimes.md) for the exact native or wire broadcast contract.

## Document content

# Broadcast to customers

A broadcast turns one notification into individual Chimes for many recipients. Use it for shipping updates, service notices, and campaigns when every recipient should receive the same SMS or email and each delivery still needs its own tracking record.

> Mcp Guide Callout is interactive content. Use the canonical page to view it.

> **Note:**
>
> Do not use broadcasts for verification codes. The [OTP API](https://studio.inttegro.com/machine/php/api/otps.md) provides
> token generation, expiry, validation, and rate limits for authentication
> flows.

## Prerequisites

- At least one valid inline phone number or email address, or a [saved customer](https://studio.inttegro.com/machine/php/api/customers.md) with the contact method you intend to use
- An allowed sender address for email broadcasts

## Choose one audience and one content source

Every recipient in a broadcast must resolve to the same transport. An SMS broadcast can contain only phone recipients; an email broadcast can contain only email recipients. If any recipient is malformed, refers to an unavailable customer, or lacks the selected contact method, the request is rejected before the broadcast is accepted.

Use one of these recipient shapes:

**Inline recipient**

```php
[
  'recipients' => [
    [
      'type' => 'phone',
      'phone' => [
        'number' => '+233544998605',
      ],
      'name' => 'Gloria Kesewaa',
    ],
  ],
]
```

**Saved customer**

```php
[
  'recipients' => [
    [
      'customer_id' => 'cu_gloria_k',
      'transport' => 'sms',
    ],
  ],
]
```

For SMS, set `message_template` to either raw message text or a stored SMS template reference. For email, provide either `email` or a stored email template reference in `message_template`. Do not combine the inline and stored-template content sources.

> **Note:**
>
> A stored template must be published, its channel must match the audience, and
> its variables must satisfy the template's published variable contract. See
> [Render a message template
> preview](https://studio.inttegro.com/machine/php/api/message-templates.md#render-a-message-template-preview) before using
> customer or catalog data in a campaign.

## Submit the broadcast

Call [Broadcast Chimes](https://studio.inttegro.com/machine/php/api/chimes.md#broadcast-chimes). A successful request returns `202 Accepted` with a [`broadcast.id`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-BroadcastCreationDetail.html); it means the audience and content were accepted for asynchronous processing, not that every message has already been delivered.

The examples below send the same SMS to three inline recipients. `sender` is optional in the wire contract, but no broadcast-specific default is applied, so production integrations should provide it explicitly.

**Broadcast notification — POST /chimes/broadcast**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->chimes->broadcast([
  'message_template' => 'Your order OR-12345 has shipped. Track it at https://yourstore.example/track/or-12345.',
  'purpose' => 'shipping_update',
  'recipients' => [
    [
      'type' => 'phone',
      'phone' => [
        'number' => '+233544998605',
      ],
    ],
    [
      'type' => 'phone',
      'phone' => [
        'number' => '+233501234567',
      ],
    ],
    [
      'type' => 'phone',
      'phone' => [
        'number' => '+233208765432',
      ],
    ],
  ],
  'sender' => 'YourStore',
]);
```

For an email broadcast, keep the recipient transport consistent and replace the SMS `message_template` string with an `email` object containing `email.from`, `email.subject`, and `email.text`. Optional `email.headers` and `email.html` are validated before acceptance. You may instead use a published email template reference in `message_template`.

## Track execution and delivery

Store the returned broadcast ID and retrieve it with [Lookup a broadcast](https://studio.inttegro.com/machine/php/api/chimes.md#lookup-a-broadcast). The response changes as processing progresses:

- [`broadcast.executed_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-BroadcastDetail.html)
  is omitted until processing has run.
- [`broadcast.chime_ids`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-BroadcastDetail.html)
  is omitted until individual Chimes are created; each ID can be passed to
  [Lookup Chime](https://studio.inttegro.com/machine/php/api/chimes.md#lookup-chime) for transmission-level status.
- [`broadcast.errors`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-BroadcastDetail.html)
  is omitted when there are no recipient-level execution failures. When present,
  each item identifies the affected recipient and includes machine-readable
  [`broadcast.errors[].type`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-BroadcastDetail.html)
  and
  [`broadcast.errors[].fix_code`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-BroadcastDetail.html)
  values when available.

The accepted broadcast does not promise an exact send or delivery time. Provider processing and recipient networks can delay or reject individual transmissions, so use each Chime's [`chime.transmission`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Chime.html) object as the delivery record.

## Cancel before completion

[Cancel a broadcast](https://studio.inttegro.com/machine/php/api/chimes.md#cancel-a-broadcast) stops a broadcast only while it has not completed. Immediate broadcasts may complete quickly, so treat cancellation as a narrow recovery control, not as an approval window.

The cancel endpoint requires `broadcast_id`. A fresh cancellation request for an already completed or already canceled broadcast returns an error.

## Related resources

- [Broadcast Chimes](https://studio.inttegro.com/machine/php/api/chimes.md#broadcast-chimes) - Complete request and response contract
- [Lookup a broadcast](https://studio.inttegro.com/machine/php/api/chimes.md#lookup-a-broadcast) - Retrieve execution results
- [Cancel a broadcast](https://studio.inttegro.com/machine/php/api/chimes.md#cancel-a-broadcast) - Cancel before completion
- [Lookup Chime](https://studio.inttegro.com/machine/php/api/chimes.md#lookup-chime) - Inspect one recipient's delivery status
- [Message templates](https://studio.inttegro.com/machine/php/api/message-templates.md) - Publish reusable SMS and email content
- [Send scheduled notifications](https://studio.inttegro.com/machine/php/guides/send-scheduled-notifications.md) - Deliver at a future time