Skip to Content
API ReferenceBroadcasts

Broadcast APIs

Overview

Create, launch, and analyze outbound broadcasts.

Broadcast properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The broadcast ID.

namestring

The broadcast name.

integrationIdstring

The integration (Channel) ID.

statestring

The broadcast state, it can be 'draft', 'scheduled', 'inProgress', 'completed', or 'failed'.

templateNamestring

The WhatsApp template name used to send the broadcast.

templateLangstring

The WhatsApp template language.

templateComponentsjson

The WhatsApp template components.

clientTagsstring[]

The client tags used to target a specific group of clients.

clientStageIdstring

The client stage ID used to target a specific stage of clients.

countrystring

The country used to target clients.

scheduledAtDateTime

The scheduled timestamp. If it's empty, the broadcast will be sent in case it's launched.

startedAtDateTime

The started timestamp.

completedAtDateTime

The completed timestamp. If it's empty, the broadcast is still in progress.

createdAtDateTime

The created timestamp.

totalCountnumber

The total number of clients that will receive the broadcast.

failedCountnumber

The number of failed deliveries.

errorstring

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

The name.

integrationIdstring

The integration (Channel) ID.

stateBroadcastState

Filter by broadcast state.

templateNamestring

The template name.

createdFromDateTime

Return broadcasts created at or after this time (inclusive).

createdToDateTime

Return broadcasts created at or before this time (inclusive).

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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 } } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

Required. The name.

integrationIdstring

Required. The integration (Channel) ID.

clientTagsstring[]

Target tags.

clientStageIdstring

Target stage.

countrystring

Target country.

templateNamestring

Required. The template name.

templateLangstring

The template language.

templateComponentsJSON

The template component variables.

scheduledAtDateTime

Schedule date/time (optional).

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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" } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

integrationIdstring

The integration (Channel) ID.

startDateDateTime

Required. Range start (inclusive), interpreted as UTC start-of-day.

endDateDateTime

Required. Range end (inclusive), interpreted as UTC start-of-day.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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" } ] } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The broadcast ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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" } } }
ErrorCause
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:

StateMeaningMoves to
draftCreated by Create Broadcast API, or sent back by Cancel Broadcast API. Only drafts can be patched or launched.scheduled when launched.
scheduledLaunched 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.
inProgressMessages are being sent. startedAt is set when sending starts.completed or failed when sending ends.
completedSending ended and at most 10% of the broadcast’s messages failed. completedAt is set.inProgress when you retry failed targets.
failedSending 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 days
  • There 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
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

Case-insensitive substring match on the broadcast name.

integrationIdstring

The integration (Channel) ID.

stateBroadcastState

Only count broadcasts in this state: draft, scheduled, inProgress, completed, or failed.

templateNamestring

Exact template name.

createdFromDateTime

Lower bound (inclusive) on the broadcast createdAt. Omit to leave the range open.

createdToDateTime

Upper bound (inclusive) on the broadcast createdAt. Omit to leave the range open.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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 } ] } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

broadcastIdstring

Required. The broadcast ID.

failedMessagesLimitnumber

How many failed messages to return in failedMessages, newest first. Defaults to 50 and is capped at 200. Pass 0 to skip the list.

Response fields

FieldTypeDescription
broadcastIdstring

The broadcast ID.

totalnumber

All messages created for the broadcast, in any status.

sentnumber

Messages in sent status.

deliverednumber

Messages in delivered status.

readnumber

Messages in read status. played messages are only counted in total.

failednumber

Messages in failed status.

retryableFailednumber

Failed messages whose failure reason is transient. These are the targets that Retry Failed Broadcast Targets API re-sends.

pendingnumber

Messages in pending status.

failedMessagesMessage[]

The most recent failed messages, newest first, up to failedMessagesLimit. failedReason holds the error returned by the Channel.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

broadcastIdstring

Required. The broadcast ID.

countrystring

Filter by client country.

lifecyclestring

Filter by client lifecycle stage ID (the client's stageId).

statusMessageStatus

Filter by message status: pending, sent, delivered, read, played, or failed.

pageInfo argument

Optional second argument. See Pagination for the general rules.

AttributeTypeDescription
limitnumber

Messages per page. Defaults to 100.

cursortimestamp

The endCursor of the previous page. Returns messages created before it.

querystring

Search recipients. Digits, spaces, and + match the client phone. Any other text matches the client name, surname, code, or email (case-insensitive).

countboolean

When true, pageInfo.count holds the total number of matching messages, regardless of the cursor.

Node fields

FieldTypeDescription
messageIdstring

The message ID.

clientNamestring

The client name.

clientPhonestring

The client phone number (not masked).

clientEmailstring

The client email (not masked).

clientCountrystring

The client country.

clientTagsstring[]

The client tags.

clientLifecyclestring

The client lifecycle stage ID.

statusMessageStatus

The message status.

failureReasonstring

The error returned by the Channel. Set only when status is failed.

contentstring

The message content. For template messages it is the template JSON: name, language, and components.

broadcastIdstring

The broadcast the message belongs to, or null.

createdAtDateTime

When the message was created.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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 } } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

startDateDateTime

Required. Start of the range (inclusive), on message createdAt. Rounded down to the start of the UTC day.

endDateDateTime

Required. End of the range (inclusive), on message createdAt. Rounded up to the end of the UTC day.

countrystring

Filter by client country.

lifecyclestring

Filter by client lifecycle stage ID (the client's stageId).

statusMessageStatus

Filter by message status: pending, sent, delivered, read, played, or failed.

templateNamestring

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.

AttributeTypeDescription
limitnumber

Messages per page. Defaults to 100.

cursortimestamp

The endCursor of the previous page. Returns messages created before it.

querystring

Search recipients. Digits, spaces, and + match the client phone. Any other text matches the client name, surname, code, or email (case-insensitive).

countboolean

When true, pageInfo.count holds the total number of matching messages, regardless of the cursor.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The broadcast ID.

namestring

The new name. Ignored when empty.

integrationIdstring

The integration (Channel) ID. Ignored when empty.

clientTagsstring[]

Target tags. Pass null to remove the filter.

clientStageIdstring

Target stage ID. Pass null to remove the filter.

countrystring

Target country. Pass null to remove the filter.

templateNamestring

Required. The template name. Send the current name to keep it.

templateLangstring

The template language. Ignored when empty, so it cannot be cleared.

templateComponentsJSON

The template component variables, in the same format as Create Broadcast API. Pass null to clear them.

scheduledAtDateTime

When to send the broadcast once it is launched. Pass null to clear it, so the broadcast is sent at the next job run after launch.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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).

ErrorCause
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 existThe integration (Channel) ID does not match a Channel in the workspace.
No WhatsApp templates found for this integrationThe WhatsApp Channel has no templates.
Template "<name>" with language "<lang>" not foundThe 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 templatetemplateComponents does not fit the template’s parameters.
Broadcast target audience exceeds the maximum of 100000 clientsThe targeting filters match more than 100,000 clients.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The broadcast ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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.

ErrorCause
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.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The broadcast ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The broadcast ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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, or 429, or an HTTP status code 500, 502, 503, or 504;
  • 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. retriedCount is 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 error and completedAt. There is no limit on how many times you retry, but each call needs at least one transient failure.
ErrorCause
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 targetsNo failed message of this broadcast has a transient failure reason.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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}"}'