Skip to main content
View as Markdown

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.

Use MCP after a broadcast is accepted

An authenticated AI agent can inspect generated Chime records and summarize delivery status after your API accepts a broadcast. Submitting or canceling broadcasts still uses the Chime API.

MCP tools: list_messages or get_message

Note

Do not use broadcasts for verification codes. The OTP API 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 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

{
  recipients: [
    {
      type: "phone",
      phone: {
        number: "+233544998605",
      },
      name: "Gloria Kesewaa",
    },
  ],
}

Saved customer

{
  recipients: [
    {
      customerId: "cu_gloria_k",
      transport: "sms",
    },
  ],
}

For SMS, set messageTemplate to either raw message text or a stored SMS template reference. For email, provide either email or a stored email template reference in messageTemplate. 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 before using customer or catalog data in a campaign.

Submit the broadcast

Call Broadcast Chimes. A successful request returns 202 Accepted with a id; 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
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.chimes.broadcast({
  messageTemplate: "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 messageTemplate 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 messageTemplate.

Track execution and delivery

Store the returned broadcast ID and retrieve it with Lookup a broadcast. The response changes as processing progresses:

  • executedAt is omitted until processing has run.
  • chimeIds is omitted until individual Chimes are created; each ID can be passed to Lookup Chime for transmission-level status.
  • errors is omitted when there are no recipient-level execution failures. When present, each item identifies the affected recipient and includes machine-readable errors[].type and errors[].fixCode 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 transmission object as the delivery record.

Cancel before completion

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 broadcastId. A fresh cancellation request for an already completed or already canceled broadcast returns an error.