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:

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

{
  "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 before using customer or catalog data in a campaign.

Submit the broadcast

Call Broadcast Chimes. A successful request returns 202 Accepted with a broadcast.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

cURL

curl https://api.inttegro.com/chimes/broadcast \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-or-12345-shipped" \
  -d '{
    "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"
  }'

TypeScript

SDK versionv8.2.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",
})

Go

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.BroadcastChimeParams{
    MessageTemplate: "Your order OR-12345 has shipped. Track it at https://yourstore.example/track/or-12345.",
    Purpose: "shipping_update",
    Recipients: []string{
      "",
      "",
      "",
    },
    Sender: "YourStore",
  }
  result, err := client.Chimes.Broadcast(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

Python

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.chimes.broadcast(inttegro.chimes.BroadcastRequest(
  message_template="Your order OR-12345 has shipped. Track it at https://yourstore.example/track/or-12345.",
  purpose="shipping_update",
  recipients=[
    inttegro.chimes.PhoneRecipient(
      type="phone",
      phone=inttegro.chimes.Phone(
        number="+233544998605",
      ),
    ),
    inttegro.chimes.PhoneRecipient(
      type="phone",
      phone=inttegro.chimes.Phone(
        number="+233501234567",
      ),
    ),
    inttegro.chimes.PhoneRecipient(
      type="phone",
      phone=inttegro.chimes.Phone(
        number="+233208765432",
      ),
    ),
  ],
  sender="YourStore",
))

PHP

SDK versionv5.3.0

<?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',
]);

Ruby

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("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"
)

Java

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.chimes.BroadcastChimeParams;
import java.util.List;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = BroadcastChimeParams.builder()
      .messageTemplate("Your order OR-12345 has shipped. Track it at https://yourstore.example/track/or-12345.")
      .purpose("shipping_update")
      .recipients(List.of(
          "",
          "",
          ""
        ))
      .sender("YourStore")
      .build();
    var result = client.chimes().broadcast(params);
  }
}

C#

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Chimes.BroadcastAsync(new {
  message_template = "Your order OR-12345 has shipped. Track it at https://yourstore.example/track/or-12345.",
  purpose = "shipping_update",
  recipients = new[] {
    new {
      type = "phone",
      phone = new {
        number = "+233544998605",
      },
    },
    new {
      type = "phone",
      phone = new {
        number = "+233501234567",
      },
    },
    new {
      type = "phone",
      phone = new {
        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 from, subject, and text. Optional headers and 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. The response changes as processing progresses:

• executed_at is omitted until processing has run.
• chime_ids 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 type and fix_code 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 broadcast_id. A fresh cancellation request for an already completed or already canceled broadcast returns an error.

Related resources

• Broadcast Chimes - Complete request and response contract
• Lookup a broadcast - Retrieve execution results
• Cancel a broadcast - Cancel before completion
• Lookup Chime - Inspect one recipient's delivery status
• Message templates - Publish reusable SMS and email content
• Send scheduled notifications - Deliver at a future time