Broadcast APIs
Overview
Create, launch, and analyze outbound broadcasts.
Broadcast properties
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The broadcast ID. |
name | string | The broadcast name. |
integrationId | string | The integration (Channel) ID. |
state | string | The broadcast state, it can be 'draft', 'scheduled', 'inProgress', 'completed', or 'failed'. |
templateName | string | The WhatsApp template name used to send the broadcast. |
templateLang | string | The WhatsApp template language. |
templateComponents | json | The WhatsApp template components. |
clientTags | string[] | The client tags used to target a specific group of clients. |
clientStageId | string | The client stage ID used to target a specific stage of clients. |
country | string | The country used to target clients. |
scheduledAt | DateTime | The scheduled timestamp. If it's empty, the broadcast will be sent in case it's launched. |
startedAt | DateTime | The started timestamp. |
completedAt | DateTime | The completed timestamp. If it's empty, the broadcast is still in progress. |
createdAt | DateTime | The created timestamp. |
totalCount | number | The total number of clients that will receive the broadcast. |
failedCount | number | The number of failed deliveries. |
error | string | The error message if the broadcast failed. |
List Broadcasts API
List the broadcasts in a workspace using supported filters.
This endpoint supports pagination. See Pagination for more information.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
name | string | The name. |
integrationId | string | The integration (Channel) ID. |
state | BroadcastState | Filter by broadcast state. |
templateName | string | The template name. |
createdFrom | DateTime | Return broadcasts created at or after this time (inclusive). |
createdTo | DateTime | Return broadcasts created at or before this time (inclusive). |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery broadcasts($input: BroadcastsInput!) {
broadcasts(input: $input) {
nodes {
id
name
state
templateName
integrationId
createdAt
}
pageInfo {
hasNextPage
endCursor
count
}
}
}
input BroadcastsInput {
workspaceId: Int! # Workspace ID.
name: String # Filter by broadcast name.
integrationId: ID # Filter by integration/channel ID.
state: BroadcastState # Filter by broadcast state.
templateName: String # Filter by template name.
createdFrom: DateTime # Lower bound (inclusive) on createdAt.
createdTo: DateTime # Upper bound (inclusive) on createdAt.
}The query above returns JSON structured like this:
{
"data": {
"broadcasts": {
"nodes": [
{
"id": "broadcast_123",
"name": "Spring sale",
"state": "completed",
"templateName": "spring_sale",
"integrationId": "integration_123",
"createdAt": "2026-03-10T09:00:00.000Z"
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "2026-03-10T09:00:00.000Z",
"count": 1
}
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"broadcasts","variables":{"input":{"workspaceId":12,"name":"Spring sale","integrationId":"integration_123","state":"completed","templateName":"spring_sale","createdFrom":"2026-03-01T00:00:00.000Z","createdTo":"2026-03-31T23:59:59.999Z"}},"query":"query broadcasts($input: BroadcastsInput!) {\n broadcasts(input: $input) {\n nodes {\n id\n name\n state\n templateName\n integrationId\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'Create Broadcast API
Create a broadcast.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
name | string | Required. The name. |
integrationId | string | Required. The integration (Channel) ID. |
clientTags | string[] | Target tags. |
clientStageId | string | Target stage. |
country | string | Target country. |
templateName | string | Required. The template name. |
templateLang | string | The template language. |
templateComponents | JSON | The template component variables. |
scheduledAt | DateTime | Schedule date/time (optional). |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation createBroadcast($input: BroadcastCreateInput!) {
createBroadcast(input: $input) {
id
name
state
templateName
integrationId
createdAt
}
}
input BroadcastCreateInput {
workspaceId: Int! # Workspace ID.
name: String! # Broadcast name.
integrationId: ID! # Integration/channel ID.
clientTags: [String!] # Target tags.
clientStageId: String # Target stage.
country: String # Target country.
templateName: String! # Template name.
templateLang: String # Template language.
templateComponents: JSON # Template component variables.
scheduledAt: DateTime # Schedule date/time (optional).
}The mutation above returns JSON structured like this:
{
"data": {
"createBroadcast": {
"id": "broadcast_123",
"name": "Spring sale",
"state": "draft",
"templateName": "spring_sale",
"integrationId": "integration_123",
"createdAt": "2026-03-16T10:15:00.000Z"
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"createBroadcast","variables":{"input":{"workspaceId":12,"name":"Spring sale","integrationId":"integration_123","clientTags":["vip"],"clientStageId":"stage_123","country":"US","templateName":"spring_sale","templateLang":"en","templateComponents":[{"type":"body","parameters":[{"type":"text","text":"{{name}}"}]}],"scheduledAt":"2026-03-20T09:00:00.000Z"}},"query":"mutation createBroadcast($input: BroadcastCreateInput!) {\n createBroadcast(input: $input) {\n id\n name\n state\n templateName\n integrationId\n createdAt\n }\n}"}'Launch Broadcast API
Launch a broadcast.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation launchBroadcast($input: BroadcastLaunchInput!) {
launchBroadcast(input: $input) {
id
name
state
startedAt
completedAt
failedCount
}
}
input BroadcastLaunchInput {
workspaceId: Int! # Workspace ID.
id: ID! # Broadcast ID.
}The mutation above returns JSON structured like this:
{
"data": {
"launchBroadcast": {
"id": "broadcast_123",
"name": "Spring sale",
"state": "scheduled",
"startedAt": null,
"completedAt": null,
"failedCount": null
}
}
}Only a draft broadcast can be launched. Launching moves it to scheduled and sets scheduledAt to the current time when it was empty. Sending starts at scheduledAt: the broadcast then moves to inProgress and startedAt is set.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"launchBroadcast","variables":{"input":{"workspaceId":12,"id":"broadcast_123"}},"query":"mutation launchBroadcast($input: BroadcastLaunchInput!) {\n launchBroadcast(input: $input) {\n id\n name\n state\n startedAt\n completedAt\n failedCount\n }\n}"}'Broadcast Report API
Get daily broadcast usage per integration (UTC calendar days). Each node is one workspace + integration + reportDate. Counts aggregate messages for broadcasts that started that UTC day (with an edge case for immediate failures without startedAt). successCount equals sentCount + deliveredCount + readCount (read includes played).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
integrationId | string | The integration (Channel) ID. |
startDate | DateTime | Required. Range start (inclusive), interpreted as UTC start-of-day. |
endDate | DateTime | Required. Range end (inclusive), interpreted as UTC start-of-day. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery broadcastReport($input: BroadcastReportInput!) {
broadcastReport(input: $input) {
nodes {
id
reportDate
sentCount
deliveredCount
readCount
pendingCount
successCount
failedCount
integrationId
createdAt
}
}
}
input BroadcastReportInput {
workspaceId: Int! # Workspace ID.
integrationId: ID # Filter by integration/channel ID.
startDate: DateTime! # Start date of report range.
endDate: DateTime! # End date of report range.
}The query above returns JSON structured like this:
{
"data": {
"broadcastReport": {
"nodes": [
{
"id": "report_123",
"reportDate": "2026-03-16T00:00:00.000Z",
"sentCount": 5,
"deliveredCount": 30,
"readCount": 5,
"pendingCount": 0,
"successCount": 40,
"failedCount": 2,
"integrationId": "integration_123",
"createdAt": "2026-03-17T00:05:12.000Z"
}
]
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"broadcastReport","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","startDate":"2026-03-01T00:00:00.000Z","endDate":"2026-03-31T00:00:00.000Z"}},"query":"query broadcastReport($input: BroadcastReportInput!) {\n broadcastReport(input: $input) {\n nodes {\n id\n reportDate\n sentCount\n deliveredCount\n readCount\n pendingCount\n successCount\n failedCount\n integrationId\n createdAt\n }\n }\n}"}'Get Broadcast API
Get one broadcast by ID, with its state, targeting filters, template, and delivery counters. Deleted broadcasts are not returned.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The broadcast ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery broadcast($input: BroadcastInput!) {
broadcast(input: $input) {
id
name
integrationId
state
templateName
templateLang
clientTags
clientStageId
country
scheduledAt
startedAt
completedAt
totalCount
failedCount
error
createdAt
}
}
input BroadcastInput {
workspaceId: Int! # Workspace ID.
id: ID! # Broadcast ID.
}The query above returns JSON structured like this:
{
"data": {
"broadcast": {
"id": "broadcast_123",
"name": "October promo",
"integrationId": "integration_123",
"state": "completed",
"templateName": "october_promo",
"templateLang": "en",
"clientTags": [
"vip"
],
"clientStageId": null,
"country": "US",
"scheduledAt": "2026-10-17T09:30:00.000Z",
"startedAt": "2026-10-17T09:30:04.000Z",
"completedAt": "2026-10-17T09:41:12.000Z",
"totalCount": 1250,
"failedCount": 18,
"error": null,
"createdAt": "2026-10-16T14:02:45.000Z"
}
}
}| Error | Cause |
|---|---|
Target broadcast is not found! | No broadcast with this ID in the workspace, or it was deleted. |
Broadcast states
The state field moves through these states:
| State | Meaning | Moves to |
|---|---|---|
draft | Created by Create Broadcast API, or sent back by Cancel Broadcast API. Only drafts can be patched or launched. | scheduled when launched. |
scheduled | Launched and waiting for scheduledAt. Launching a broadcast without scheduledAt sets it to the launch time. A background job picks up due broadcasts every 10 minutes. | draft when cancelled, inProgress when sending starts, failed when no client qualifies. |
inProgress | Messages are being sent. startedAt is set when sending starts. | completed or failed when sending ends. |
completed | Sending ended and at most 10% of the broadcast’s messages failed. completedAt is set. | inProgress when you retry failed targets. |
failed | Sending ended with more than 10% of the messages failed, or the broadcast could not be sent at all. In the second case error holds the reason. | inProgress when you retry failed targets. |
When sending starts, the audience is resolved from clientTags, clientStageId, and country. By default only matching clients who messaged the business in the last 90 days are included. The error values set by the sending job are:
No matched clients have contacted the business in the last 90 daysThere are no clients matched with the broadcast filters(when the 90-day rule is off for the workspace)No messages were created for target clients
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"broadcast","variables":{"input":{"workspaceId":12,"id":"broadcast_123"}},"query":"query broadcast($input: BroadcastInput!) {\n broadcast(input: $input) {\n id\n name\n integrationId\n state\n templateName\n templateLang\n clientTags\n clientStageId\n country\n scheduledAt\n startedAt\n completedAt\n totalCount\n failedCount\n error\n createdAt\n }\n}"}'Broadcast State Counts API
Count the broadcasts in a workspace per state, for example to show tab badges. It takes the same filters as List Broadcasts API. The result always has one entry per state, in the order draft, scheduled, inProgress, completed, failed, with 0 for states that have no broadcasts. Deleted broadcasts are not counted.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
name | string | Case-insensitive substring match on the broadcast name. |
integrationId | string | The integration (Channel) ID. |
state | BroadcastState | Only count broadcasts in this state: |
templateName | string | Exact template name. |
createdFrom | DateTime | Lower bound (inclusive) on the broadcast |
createdTo | DateTime | Upper bound (inclusive) on the broadcast |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery broadcastStateCounts($input: BroadcastsInput!) {
broadcastStateCounts(input: $input) {
state
count
}
}
input BroadcastsInput {
workspaceId: Int! # Workspace ID.
name: String # Substring match on the broadcast name.
integrationId: ID # Filter by integration/channel ID.
state: BroadcastState # Filter by broadcast state.
templateName: String # Filter by template name.
createdFrom: DateTime # createdAt lower bound (inclusive).
createdTo: DateTime # createdAt upper bound (inclusive).
}
enum BroadcastState {
draft
scheduled
inProgress
completed
failed
}The query above returns JSON structured like this:
{
"data": {
"broadcastStateCounts": [
{
"state": "draft",
"count": 3
},
{
"state": "scheduled",
"count": 1
},
{
"state": "inProgress",
"count": 0
},
{
"state": "completed",
"count": 7
},
{
"state": "failed",
"count": 1
}
]
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"broadcastStateCounts","variables":{"input":{"workspaceId":12,"integrationId":"integration_123","createdFrom":"2026-10-01T00:00:00.000Z","createdTo":"2026-10-17T23:59:59.999Z"}},"query":"query broadcastStateCounts($input: BroadcastsInput!) {\n broadcastStateCounts(input: $input) {\n state\n count\n }\n}"}'Broadcast Delivery Report API
Get live message counts for one broadcast, grouped by message status, plus its most recent failed messages. Counts are read from the broadcast’s messages at request time, so you can poll this while the broadcast is inProgress. For daily totals per Channel, use Broadcast Report API.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
broadcastId | string | Required. The broadcast ID. |
failedMessagesLimit | number | How many failed messages to return in |
Response fields
| Field | Type | Description |
|---|---|---|
broadcastId | string | The broadcast ID. |
total | number | All messages created for the broadcast, in any status. |
sent | number | Messages in |
delivered | number | Messages in |
read | number | Messages in |
failed | number | Messages in |
retryableFailed | number | Failed messages whose failure reason is transient. These are the targets that Retry Failed Broadcast Targets API re-sends. |
pending | number | Messages in |
failedMessages | Message[] | The most recent failed messages, newest first, up to |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery broadcastDeliveryReport($input: BroadcastDeliveryReportInput!) {
broadcastDeliveryReport(input: $input) {
broadcastId
total
sent
delivered
read
failed
retryableFailed
pending
failedMessages {
messageId
status
failedReason
createdAt
}
}
}
input BroadcastDeliveryReportInput {
workspaceId: Int! # Workspace ID.
broadcastId: ID! # Broadcast ID.
failedMessagesLimit: Int # Failed messages to return (default 50, max 200).
}The query above returns JSON structured like this:
{
"data": {
"broadcastDeliveryReport": {
"broadcastId": "broadcast_123",
"total": 1250,
"sent": 140,
"delivered": 612,
"read": 476,
"failed": 18,
"retryableFailed": 5,
"pending": 4,
"failedMessages": [
{
"messageId": "message_124",
"status": "failed",
"failedReason": "[{\"code\":130429,\"title\":\"Rate limit hit\"}]",
"createdAt": "2026-10-17T09:38:51.000Z"
},
{
"messageId": "message_123",
"status": "failed",
"failedReason": "[{\"code\":131026,\"title\":\"Message undeliverable\"}]",
"createdAt": "2026-10-17T09:36:02.000Z"
}
]
}
}
}The report does not check that the broadcast exists. An unknown or deleted broadcast ID returns zero counts and an empty failedMessages list instead of an error.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"broadcastDeliveryReport","variables":{"input":{"workspaceId":12,"broadcastId":"broadcast_123","failedMessagesLimit":2}},"query":"query broadcastDeliveryReport($input: BroadcastDeliveryReportInput!) {\n broadcastDeliveryReport(input: $input) {\n broadcastId\n total\n sent\n delivered\n read\n failed\n retryableFailed\n pending\n failedMessages {\n messageId\n status\n failedReason\n createdAt\n }\n }\n}"}'List Broadcast Message Statuses API
List the messages of one broadcast with their delivery status and recipient details, newest first. Use it to see who received, read, or failed to get a broadcast. Only template messages are returned, and messages to deleted clients are left out.
This endpoint supports pagination. See Pagination for more information.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
broadcastId | string | Required. The broadcast ID. |
country | string | Filter by client country. |
lifecycle | string | Filter by client lifecycle stage ID (the client's |
status | MessageStatus | Filter by message status: |
pageInfo argument
Optional second argument. See Pagination for the general rules.
| Attribute | Type | Description |
|---|---|---|
limit | number | Messages per page. Defaults to 100. |
cursor | timestamp | The |
query | string | Search recipients. Digits, spaces, and |
count | boolean | When |
Node fields
| Field | Type | Description |
|---|---|---|
messageId | string | The message ID. |
clientName | string | The client name. |
clientPhone | string | The client phone number (not masked). |
clientEmail | string | The client email (not masked). |
clientCountry | string | The client country. |
clientTags | string[] | The client tags. |
clientLifecycle | string | The client lifecycle stage ID. |
status | MessageStatus | The message status. |
failureReason | string | The error returned by the Channel. Set only when |
content | string | The message content. For template messages it is the template JSON: |
broadcastId | string | The broadcast the message belongs to, or |
createdAt | DateTime | When the message was created. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery broadcastMessageStatuses($input: BroadcastMessageStatusesInput!, $pageInfo: PageInfoInput) {
broadcastMessageStatuses(input: $input, pageInfo: $pageInfo) {
nodes {
messageId
clientName
clientPhone
clientCountry
status
failureReason
createdAt
}
pageInfo {
hasNextPage
endCursor
count
}
}
}
input BroadcastMessageStatusesInput {
workspaceId: Int! # Workspace ID.
broadcastId: ID! # Broadcast ID.
country: String # Filter by client country.
lifecycle: String # Filter by client lifecycle/stage ID.
status: MessageStatus # Filter by message status.
}
enum MessageStatus {
pending
sent
delivered
read
played
failed
}
input PageInfoInput {
limit: Int # Items per page (default 100).
cursor: Timestamp # endCursor of the previous page.
query: String # Search recipients by phone, name, code or email.
count: Boolean # Return the total count in pageInfo.count.
}The query above returns JSON structured like this:
{
"data": {
"broadcastMessageStatuses": {
"nodes": [
{
"messageId": "message_124",
"clientName": "Jessica Miller",
"clientPhone": "+12025550123",
"clientCountry": "US",
"status": "failed",
"failureReason": "[{\"code\":130429,\"title\":\"Rate limit hit\"}]",
"createdAt": "2026-10-17T09:38:51.000Z"
},
{
"messageId": "message_123",
"clientName": "Omar Haddad",
"clientPhone": "+12025550187",
"clientCountry": "US",
"status": "failed",
"failureReason": "[{\"code\":131026,\"title\":\"Message undeliverable\"}]",
"createdAt": "2026-10-17T09:36:02.000Z"
}
],
"pageInfo": {
"hasNextPage": true,
"endCursor": "2026-10-17T09:36:02.000Z",
"count": 18
}
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"broadcastMessageStatuses","variables":{"input":{"workspaceId":12,"broadcastId":"broadcast_123","status":"failed"},"pageInfo":{"limit":2,"count":true}},"query":"query broadcastMessageStatuses($input: BroadcastMessageStatusesInput!, $pageInfo: PageInfoInput) {\n broadcastMessageStatuses(input: $input, pageInfo: $pageInfo) {\n nodes {\n messageId\n clientName\n clientPhone\n clientCountry\n status\n failureReason\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'List Workspace Broadcast Message Statuses API
List every outbound message of a workspace in a date range with its delivery status and recipient details, newest first. It covers broadcast messages and outbound messages that are not part of a broadcast, such as template messages sent through the API. Notes are excluded. broadcastId is null for messages outside a broadcast. The node fields are the same as in List Broadcast Message Statuses API.
This endpoint supports pagination. See Pagination for more information.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
startDate | DateTime | Required. Start of the range (inclusive), on message |
endDate | DateTime | Required. End of the range (inclusive), on message |
country | string | Filter by client country. |
lifecycle | string | Filter by client lifecycle stage ID (the client's |
status | MessageStatus | Filter by message status: |
templateName | string | Only return template messages whose content contains this text (case-insensitive). The content is the template JSON, so the text can also match the language code or parameter values. |
pageInfo argument
Optional second argument. See Pagination for the general rules.
| Attribute | Type | Description |
|---|---|---|
limit | number | Messages per page. Defaults to 100. |
cursor | timestamp | The |
query | string | Search recipients. Digits, spaces, and |
count | boolean | When |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery workspaceBroadcastMessageStatuses($input: WorkspaceBroadcastMessageStatusesInput!, $pageInfo: PageInfoInput) {
workspaceBroadcastMessageStatuses(input: $input, pageInfo: $pageInfo) {
nodes {
messageId
broadcastId
clientName
clientPhone
status
content
createdAt
}
pageInfo {
hasNextPage
endCursor
count
}
}
}
input WorkspaceBroadcastMessageStatusesInput {
workspaceId: Int! # Workspace ID.
startDate: DateTime! # Range start (UTC start of day, inclusive).
endDate: DateTime! # Range end (UTC end of day, inclusive).
country: String # Filter by client country.
lifecycle: String # Filter by client lifecycle/stage ID.
status: MessageStatus # Filter by message status.
templateName: String # Substring match on template message content.
}
enum MessageStatus {
pending
sent
delivered
read
played
failed
}
input PageInfoInput {
limit: Int # Items per page (default 100).
cursor: Timestamp # endCursor of the previous page.
query: String # Search recipients by phone, name, code or email.
count: Boolean # Return the total count in pageInfo.count.
}The query above returns JSON structured like this:
{
"data": {
"workspaceBroadcastMessageStatuses": {
"nodes": [
{
"messageId": "message_310",
"broadcastId": null,
"clientName": "Jessica Miller",
"clientPhone": "+12025550123",
"status": "read",
"content": "{\"name\":\"order_update\",\"language\":{\"code\":\"en\"},\"components\":[{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"A-1042\"}]}]}",
"createdAt": "2026-10-16T15:12:40.000Z"
},
{
"messageId": "message_287",
"broadcastId": "broadcast_456",
"clientName": "Omar Haddad",
"clientPhone": "+12025550187",
"status": "delivered",
"content": "{\"name\":\"order_update\",\"language\":{\"code\":\"en\"},\"components\":[{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"A-0998\"}]}]}",
"createdAt": "2026-10-09T10:00:07.000Z"
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "2026-10-09T10:00:07.000Z",
"count": 2
}
}
}
}Messages to deleted clients are included unless you also filter by country, lifecycle, or pageInfo.query.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"workspaceBroadcastMessageStatuses","variables":{"input":{"workspaceId":12,"startDate":"2026-10-01T00:00:00.000Z","endDate":"2026-10-17T00:00:00.000Z","templateName":"order_update"},"pageInfo":{"limit":25,"count":true}},"query":"query workspaceBroadcastMessageStatuses($input: WorkspaceBroadcastMessageStatusesInput!, $pageInfo: PageInfoInput) {\n workspaceBroadcastMessageStatuses(input: $input, pageInfo: $pageInfo) {\n nodes {\n messageId\n broadcastId\n clientName\n clientPhone\n status\n content\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'Patch Broadcast API
Update a broadcast. Only broadcasts in draft state can be patched. To change a scheduled broadcast, cancel it with Cancel Broadcast API, patch it, and launch it again. Fields you leave out keep their current values. The template and the audience size are checked again with the merged values, as in Create Broadcast API.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The broadcast ID. |
name | string | The new name. Ignored when empty. |
integrationId | string | The integration (Channel) ID. Ignored when empty. |
clientTags | string[] | Target tags. Pass |
clientStageId | string | Target stage ID. Pass |
country | string | Target country. Pass |
templateName | string | Required. The template name. Send the current name to keep it. |
templateLang | string | The template language. Ignored when empty, so it cannot be cleared. |
templateComponents | JSON | The template component variables, in the same format as Create Broadcast API. Pass |
scheduledAt | DateTime | When to send the broadcast once it is launched. Pass |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation patchBroadcast($input: BroadcastPatchInput!) {
patchBroadcast(input: $input) {
id
name
state
templateName
templateLang
clientTags
scheduledAt
}
}
input BroadcastPatchInput {
workspaceId: Int! # Workspace ID.
id: ID! # Broadcast ID.
name: String # Broadcast name.
integrationId: ID # Integration/channel ID.
clientTags: [String!] # Target tags.
clientStageId: String # Target stage.
country: String # Target country.
templateName: String! # Template name.
templateLang: String # Template language.
templateComponents: JSON # Template component variables.
scheduledAt: DateTime # Schedule date/time.
}The mutation above returns JSON structured like this:
{
"data": {
"patchBroadcast": {
"id": "broadcast_123",
"name": "October promo - VIP",
"state": "draft",
"templateName": "october_promo",
"templateLang": "en",
"clientTags": [
"vip"
],
"scheduledAt": "2026-10-20T09:30:00.000Z"
}
}
}Template checks run only for WhatsApp Channels (WhatsApp on Meta and WhatsApp on Gupshup).
| Error | Cause |
|---|---|
Target broadcast is not found! | No broadcast with this ID in the workspace. |
Only broadcasts in draft status can be updated. | The broadcast is not in draft state. |
Target integration does not exist | The integration (Channel) ID does not match a Channel in the workspace. |
No WhatsApp templates found for this integration | The WhatsApp Channel has no templates. |
Template "<name>" with language "<lang>" not found | The template is not on the WhatsApp Channel. Without a language the message is Template "<name>" not found. |
A component error, for example Body component is required for this template | templateComponents does not fit the template’s parameters. |
Broadcast target audience exceeds the maximum of 100000 clients | The targeting filters match more than 100,000 clients. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"patchBroadcast","variables":{"input":{"workspaceId":12,"id":"broadcast_123","name":"October promo - VIP","clientTags":["vip"],"templateName":"october_promo","scheduledAt":"2026-10-20T09:30:00.000Z"}},"query":"mutation patchBroadcast($input: BroadcastPatchInput!) {\n patchBroadcast(input: $input) {\n id\n name\n state\n templateName\n templateLang\n clientTags\n scheduledAt\n }\n}"}'Cancel Broadcast API
Cancel a launched broadcast before it starts sending. The broadcast goes from scheduled back to draft, so you can patch it or launch it again. Once sending has started (inProgress), a broadcast can no longer be cancelled.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The broadcast ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation cancelBroadcast($input: BroadcastCancelInput!) {
cancelBroadcast(input: $input) {
id
state
scheduledAt
}
}
input BroadcastCancelInput {
workspaceId: Int! # Workspace ID.
id: ID! # Broadcast ID.
}The mutation above returns JSON structured like this:
{
"data": {
"cancelBroadcast": {
"id": "broadcast_123",
"state": "draft",
"scheduledAt": "2026-10-20T09:30:00.000Z"
}
}
}Only state changes. scheduledAt keeps its value, including the launch time that Launch Broadcast API fills in when the broadcast had none. If you launch again while scheduledAt is in the past, the broadcast is sent at the next job run, so patch scheduledAt first to pick a new time.
| Error | Cause |
|---|---|
Target broadcast is not found! | No broadcast with this ID in the workspace. |
Only broadcasts in scheduled status can be cancelled. | The broadcast is draft, inProgress, completed, or failed. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"cancelBroadcast","variables":{"input":{"workspaceId":12,"id":"broadcast_123"}},"query":"mutation cancelBroadcast($input: BroadcastCancelInput!) {\n cancelBroadcast(input: $input) {\n id\n state\n scheduledAt\n }\n}"}'Delete Broadcast API
Delete a broadcast in any state. The broadcast is soft-deleted: it no longer appears in List Broadcasts API, Get Broadcast API, or Broadcast State Counts API, and the sending job skips it. Managers can create and launch broadcasts but cannot delete them.
Access: MANAGE_WORKSPACE (Owner, Admin). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The broadcast ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation deleteBroadcast($input: BroadcastDeleteInput!) {
deleteBroadcast(input: $input) {
id
name
state
}
}
input BroadcastDeleteInput {
workspaceId: Int! # Workspace ID.
id: ID! # Broadcast ID.
}The mutation above returns JSON structured like this:
{
"data": {
"deleteBroadcast": {
"id": "broadcast_123",
"name": "October promo",
"state": "scheduled"
}
}
}Deleting a scheduled broadcast stops it from being sent. Deleting an inProgress broadcast lets the running job finish the recipients it already picked up (up to 1,000), and then no more are sent. Messages already sent are not recalled. The broadcast’s messages stay available in Broadcast Delivery Report API and the message status APIs above.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"deleteBroadcast","variables":{"input":{"workspaceId":12,"id":"broadcast_123"}},"query":"mutation deleteBroadcast($input: BroadcastDeleteInput!) {\n deleteBroadcast(input: $input) {\n id\n name\n state\n }\n}"}'Retry Failed Broadcast Targets API
Re-send a finished broadcast to the clients whose message failed for a transient reason, such as a rate limit, a timeout, or a Meta server error. The broadcast must be completed or failed. It goes back to inProgress and the sending job starts right away. When the job ends, the broadcast becomes completed or failed again based on the new message counts. Check retryableFailed in Broadcast Delivery Report API to see how many targets qualify.
Access: MANAGE_CONVS (Owner, Admin, Manager). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The broadcast ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation retryFailedBroadcastTargets($input: RetryFailedBroadcastTargetsInput!) {
retryFailedBroadcastTargets(input: $input) {
retriedCount
broadcast {
id
state
startedAt
completedAt
error
}
}
}
input RetryFailedBroadcastTargetsInput {
workspaceId: Int! # Workspace ID.
id: ID! # Broadcast ID.
}The mutation above returns JSON structured like this:
{
"data": {
"retryFailedBroadcastTargets": {
"retriedCount": 5,
"broadcast": {
"id": "broadcast_123",
"state": "inProgress",
"startedAt": "2026-10-17T09:30:04.000Z",
"completedAt": null,
"error": null
}
}
}
}A failed message counts as transient when its failure reason:
- has a WhatsApp error code
130429,80007,131053, or429, or an HTTP status code500,502,503, or504; - mentions a rate limit (
too many requests,rate limit), an HTTP 5xx status, an HTTP 429 status, a timeout (ETIMEDOUT,timed out,timeout), a connection reset (ECONNRESET), or a DNS failure (ENOTFOUND,getaddrinfo,dns); - is
Meta did not return a clear delivery result., which is set when Meta answered with an empty server error.
Any other failure reason is not retried.
How the retry works:
- The failed messages being retried are deleted, and new messages are created when they are re-sent.
retriedCountis the number of deleted failed messages. - The audience is resolved again from the broadcast’s current filters, with the same rules as the first run. Every matching client that has no message in this broadcast is sent the template: the retried targets, plus any client that started matching the filters since the first run. Retried targets that no longer match are not sent again.
- The call clears
errorandcompletedAt. There is no limit on how many times you retry, but each call needs at least one transient failure.
| Error | Cause |
|---|---|
Target broadcast is not found! | No broadcast with this ID in the workspace. |
Only completed or failed broadcasts can retry failed targets. | The broadcast is draft, scheduled, or inProgress. |
No retryable failed targets | No failed message of this broadcast has a transient failure reason. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"retryFailedBroadcastTargets","variables":{"input":{"workspaceId":12,"id":"broadcast_123"}},"query":"mutation retryFailedBroadcastTargets($input: RetryFailedBroadcastTargetsInput!) {\n retryFailedBroadcastTargets(input: $input) {\n retriedCount\n broadcast {\n id\n state\n startedAt\n completedAt\n error\n }\n }\n}"}'