Update a broadcast

PUT

broadcasts

{id}

cURL

curl --request PUT \
  --url https://api.vobiz.ai/api/v1/sms/broadcasts/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "template": "Hi {{name}}, your refund of {{amount}} has been issued."
}
'

from vobiz import Vobiz

client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")

client.sms.broadcasts.update_broadcast(
    id="3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
    template="Hi {{name}}, your refund of {{amount}} has been issued.",
)

const options = {
  method: 'PUT',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({template: 'Hi {{name}}, your refund of {{amount}} has been issued.'})
};

fetch('https://api.vobiz.ai/api/v1/sms/broadcasts/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
  "accountId": "MA_XXXXXXXX",
  "name": "October pricing update",
  "from": "+14155550100",
  "channel": "sms",
  "template": "Hi {{name}}, your refund of {{amount}} has been issued.",
  "status": "draft",
  "scheduledAt": null,
  "ratePerSecond": 5,
  "tag": "pricing-oct",
  "dltEntityId": "",
  "dltHeaderId": "",
  "dltTemplateId": "",
  "columns": [
    "phone",
    "name",
    "amount"
  ],
  "stats": {
    "total": 3,
    "pending": 3,
    "sent": 0,
    "delivered": 0,
    "failed": 0,
    "optedOut": 0,
    "skipped": 0
  },
  "createdAt": "2026-10-12T10:30:00Z",
  "updatedAt": "2026-10-12T10:42:00Z",
  "startedAt": null,
  "completedAt": null
}

{
  "error": "ratePerSecond must be between 1 and 50"
}

{
  "error": "missing or invalid credentials"
}

{
  "error": "broadcast not found"
}

{
  "error": "cannot edit a broadcast that is running"
}

Authorizations

X-Auth-ID

string

header

required

Your Vobiz account Auth ID (MA_XXXXXXXX).

X-Auth-Token

string

header

required

Your Vobiz account Auth Token.

Path Parameters

string<uuid>

required

The broadcast's id (UUID), as returned by POST /broadcasts or GET /broadcasts. An id that is not a UUID, or that belongs to another account, returns 404 with broadcast not found.

Body

application/json

Broadcast fields you can change on a draft. Every field is optional; fields you leave out keep their value, and the same validation as create applies.

name

string

A label for the broadcast in the console and in listings, 1 to 255 characters. Required on create; on update it cannot be set to an empty string.

Maximum string length: 255

Example:

"October pricing update"

from

string

The sender every message goes out from: an SMS number on your account in E.164 format, a short code of up to 8 digits, or an alphanumeric sender ID of 1 to 11 letters, digits and spaces that starts with a letter or digit. Spaces, hyphens and brackets in phone numbers are removed before storing. Launch checks that a phone-number sender is an SMS number on your account. Required on create.

Example:

"+14155550100"

channel

enum<string>

default:sms

The channel the broadcast sends on. Broadcasts send SMS, so the only value is sms (matched case-insensitively), which is also the default.

Available options:

sms

template

string

Message body, up to 5,000 characters, with {{variable}} placeholders filled per recipient from the columns of your upload. Placeholder names are matched case-insensitively and trimmed, so {{ Name }} matches a name column. Launch requires a non-empty template.

Maximum string length: 5000

Example:

"Hi {{name}}, your refund of {{amount}} is on its way."

scheduledAt

string<date-time> | null

RFC 3339 timestamp at which sending starts after you launch, for example 2026-11-01T09:00:00Z; offsets are converted to UTC. Omit it, or pass null or "", to send as soon as you launch. On update, null clears a previous value.

Example:

"2026-10-15T09:00:00Z"

ratePerSecond

integer

default:5

Maximum messages sent per second while the broadcast runs, an integer from 1 to 50. Defaults to 5, and 0 also selects the default. Lower it to spread load on your own systems or replies.

Required range: 1 <= x <= 50

Example:

5

tag

string

Your own label of up to 255 characters, copied onto every message the broadcast sends so you can find them with the tag filter on GET /messages.

Maximum string length: 255

Example:

"pricing-oct"

dltEntityId

string

India (TRAI DLT). The Principal Entity ID you registered on a TRAI DLT portal, up to 64 characters. Pass it when the list contains Indian numbers; it is copied onto every message.

Maximum string length: 64

dltHeaderId

string

India (TRAI DLT). The sender header ID you registered on a TRAI DLT portal, up to 64 characters. Copied onto every message.

Maximum string length: 64

dltTemplateId

string

India (TRAI DLT). The content template ID you registered on a TRAI DLT portal, up to 64 characters. Your template text must match the registered template with the variables filled.

Maximum string length: 64

Response

The updated broadcast.

A bulk SMS send that renders one template for every recipient of an uploaded list and sends at a controlled rate. Its status moves from draft through scheduled or running to completed, cancelled or failed, and stats counts recipients by state.

string<uuid>

Unique identifier of the broadcast (UUID). Use it in every /broadcasts/{id} path.

Example:

"3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35"

accountId

string

Your Vobiz account ID (MA_...) that owns the broadcast.

Example:

"MA_XXXXXXXX"

name

string

The label you gave the broadcast, shown in the console and in listings.

Example:

"October pricing update"

from

string

The sender every message goes out from, as stored: an E.164 number, a short code or an alphanumeric sender ID.

Example:

"+14155550100"

channel

enum<string>

The channel the broadcast sends on. Always sms.

Available options:

sms

Example:

"sms"

template

string

The message body with {{variable}} placeholders, filled per recipient from the columns of the upload. Empty until you set it.

Example:

"Hi {{name}}, your refund of {{amount}} is on its way."

status

enum<string>

Lifecycle state. draft until you launch, then scheduled (waiting for scheduledAt) or running. paused after a pause call or when pauseReason is set; completed once every recipient is processed; cancelled after a cancel call; failed when the run stopped on an error.

Available options:

draft,

scheduled,

running,

paused,

completed,

cancelled,

failed

Example:

"draft"

pauseReason

enum<string>

Present only while the broadcast is paused for a reason other than your own pause call. insufficient_balance means the balance ran out; top up and call POST /broadcasts/{id}/resume.

Available options:

insufficient_balance

scheduledAt

string<date-time> | null

When sending starts after launch, in UTC (ISO 8601). null means sending starts as soon as you launch.

Example:

null

ratePerSecond

integer

Maximum messages sent per second while running, from 1 to 50.

Example:

5

tag

string

Your label, copied onto every message the broadcast sends. Empty string when not set.

Example:

""

dltEntityId

string

India (TRAI DLT). The Principal Entity ID copied onto every message. Empty string when not set.

Example:

""

dltHeaderId

string

India (TRAI DLT). The registered sender header ID copied onto every message. Empty string when not set.

Example:

""

dltTemplateId

string

India (TRAI DLT). The registered content template ID copied onto every message. Empty string when not set.

Example:

""

columns

string[] | null

Column names from the latest recipient upload, as written in your file header. The first is the phone column and the rest are available as template variables. Empty until you upload recipients.

Example:

null

stats

object

Recipient counts by state, recounted on every read.

Show child attributes

createdAt

string<date-time>

When the broadcast was created (ISO 8601, UTC).

Example:

"2026-10-12T10:30:00Z"

updatedAt

string<date-time>

When the broadcast last changed, including status changes (ISO 8601, UTC).

Example:

"2026-10-12T10:30:00Z"

startedAt

string<date-time> | null

When sending began (ISO 8601, UTC). null until the broadcast runs.

Example:

null

completedAt

string<date-time> | null

When the broadcast finished, either because the last recipient was processed or because it was cancelled (ISO 8601, UTC). null until then.

Example:

null

⌘I

cURL

curl --request PUT \
  --url https://api.vobiz.ai/api/v1/sms/broadcasts/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "template": "Hi {{name}}, your refund of {{amount}} has been issued."
}
'

from vobiz import Vobiz

client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")

client.sms.broadcasts.update_broadcast(
    id="3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
    template="Hi {{name}}, your refund of {{amount}} has been issued.",
)

const options = {
  method: 'PUT',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({template: 'Hi {{name}}, your refund of {{amount}} has been issued.'})
};

fetch('https://api.vobiz.ai/api/v1/sms/broadcasts/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35",
  "accountId": "MA_XXXXXXXX",
  "name": "October pricing update",
  "from": "+14155550100",
  "channel": "sms",
  "template": "Hi {{name}}, your refund of {{amount}} has been issued.",
  "status": "draft",
  "scheduledAt": null,
  "ratePerSecond": 5,
  "tag": "pricing-oct",
  "dltEntityId": "",
  "dltHeaderId": "",
  "dltTemplateId": "",
  "columns": [
    "phone",
    "name",
    "amount"
  ],
  "stats": {
    "total": 3,
    "pending": 3,
    "sent": 0,
    "delivered": 0,
    "failed": 0,
    "optedOut": 0,
    "skipped": 0
  },
  "createdAt": "2026-10-12T10:30:00Z",
  "updatedAt": "2026-10-12T10:42:00Z",
  "startedAt": null,
  "completedAt": null
}

{
  "error": "ratePerSecond must be between 1 and 50"
}

{
  "error": "missing or invalid credentials"
}

{
  "error": "broadcast not found"
}

{
  "error": "cannot edit a broadcast that is running"
}

Getting Started

API Reference

Guides

Update a broadcast

Authorizations

Path Parameters

Body

Response