Automation APIs
Overview
Automations send a WhatsApp template to each contact a set time after one of the contact’s dates: when the contact was created, or when the contact last started a new conversation. Use them for follow-ups such as a welcome message 3 days after a contact is added, or a check-in 1 day after a conversation.
Conditions (tags, lifecycle stage, country) decide which contacts are messaged. They are checked when a contact becomes due, not when the automation is created, so contacts added later are messaged too. Every send to a contact is recorded as an occurrence, which you can list and summarize with the occurrence APIs.
To set up automations in the portal instead, see the Automations guide.
Automations are in beta and available on request. Until they are turned on for your workspace, Create Automation API and Activate Automation API fail with Automations are not enabled for this workspace, and no automation sends messages. Contact [email protected] to turn them on.
Automation properties
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The automation ID. |
name | string | The automation name. |
integrationId | string | The integration (Channel) ID used to send the template. |
state | string | The automation state: |
triggerType | string | The contact date the delay is counted from: |
delayMinutes | number | Minutes after the trigger date when the message is due. |
maxLatenessDays | number | The catch-up window in days. Contacts that became due longer ago are skipped. See Catch-up window. |
reentryPolicy | string | How often the same contact can receive the automation: |
reentryCooldownDays | number | Minimum days between two messages to the same contact when |
clientTags | string[] | Contacts must have at least one of these tags. |
clientStageId | string | Contacts must be in this lifecycle stage. |
country | string | Contacts must be from this country. |
timezone | string | The IANA timezone of the send window. Defaults to |
sendWindowStart | number | Start of the daily send window, in minutes from midnight. Empty means any time of day. |
sendWindowEnd | number | End of the daily send window, in minutes from midnight. Empty means any time of day. |
sendWeekdays | string[] | Days on which the automation sends: |
templateName | string | The WhatsApp template name. |
templateLang | string | The WhatsApp template language. |
templateComponents | json | The WhatsApp template components, in the same format as broadcasts. String values support placeholders such as |
activatedAt | DateTime | When the automation was first activated. |
lastRunAt | DateTime | When the last processing run finished. |
lastError | string | Why the automation stopped sending. Set when it was paused automatically or is blocked, for example by the usage limit. See Automatic pauses and errors. |
sentCount | number | The number of occurrences with status |
lastOccurrenceAt | DateTime | When the newest occurrence was created. |
createdAt | DateTime | The created timestamp. |
patchedAt | DateTime | The last updated timestamp. |
deletedAt | DateTime | Set when the automation was deleted. See Deleting an automation. |
Automation occurrence properties
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The occurrence ID. |
automationId | string | The automation ID. |
clientId | string | The contact ID. |
clientName | string | The contact's name and surname. |
clientPhone | string | The contact's phone number. |
anchorAt | DateTime | The trigger date of the contact that made it due. |
dueAt | DateTime | When the message became due: |
status | string | The send state: |
messageStatus | MessageStatus | The delivery status of the sent message: |
failedReason | string | Why the send failed. When the channel rejected the message after it was sent, this is the message's failure reason. |
messageId | string | The ID of the sent message. |
conversationId | string | The conversation the contact replied in. |
repliedAt | DateTime | When the contact first replied. See Replies. |
createdAt | DateTime | When the contact was picked and the send started. |
How automations work
Trigger and delay
triggerType | Trigger date |
|---|---|
clientCreated | When the contact was created in the workspace. |
lastConversationStarted | When the contact last started a new conversation. A message inside a conversation that is already open doesn’t change this date. Contacts who never started a conversation are not messaged. |
A contact becomes due delayMinutes after its trigger date. The delay can be 0 minutes to 365 days (525600 minutes). With lastConversationStarted and the 90-day rule, the delay must be less than 90 days (129600 minutes), because a contact whose last conversation started more than 90 days ago drops out of the audience before it becomes due.
A background job checks active automations every 5 minutes. It picks up contacts about 10 minutes after they become due, oldest due date first, so expect the message 10 to 15 minutes after the due time. Large backlogs are sent in batches.
Conditions
clientTags: the contact has at least one of these tags.clientStageId: the contact is in this lifecycle stage.country: the contact’s country contains this text (case-insensitive).
Leave them all empty to message every contact. Conditions are checked when a contact becomes due, so a contact that gets a tag after it was created is messaged if it has the tag by then. Archived contacts, including contacts who opted out with the opt-out keyword, and blacklisted contacts are never messaged.
As with broadcasts, by default only contacts who started a conversation in the last 90 days are included. This applies to both triggers: with clientCreated, an imported contact that never messaged you is not messaged. When the 90-day rule is off for the workspace, every matching contact is included.
Use Automation Audience Preview API to count the matching contacts before you activate an automation.
Catch-up window
maxLatenessDays (1 to 30 days, default 1) is how long after its due time a contact can still be messaged. Contacts that became due longer ago are skipped. The window matters in three cases:
- First activation. Contacts that are already due within the window are messaged on the first run. Older ones are skipped. The audience preview returns this number as
dueCount. - Resuming. Activating a paused automation continues where it stopped. Contacts that became due while it was paused are messaged if they are still within the window. Changing the trigger of a paused automation starts it over, so the next activation works like a first activation.
- Send window. Contacts that become due outside the send window wait for the next window, and are skipped if the catch-up window ends first. Make the catch-up window at least as long as the longest gap between two send windows. For example, a Monday to Friday window from 09:00 to 18:00 needs at least 3 days to cover the weekend.
Re-entry policies
reentryPolicy | Behavior |
|---|---|
once | The default. A contact receives the automation at most once, even if its trigger date changes later. |
cooldown | Every new trigger date can message the contact again, but not within reentryCooldownDays (1 to 365) of the last message the contact got from this automation. A trigger date inside the cooldown is skipped, not postponed. |
everyOccurrence | Every new trigger date messages the contact again. |
cooldown and everyOccurrence need the lastConversationStarted trigger, because the date a contact was created never changes.
Send window
timezone, sendWindowStart, sendWindowEnd, and sendWeekdays limit when the automation sends. Leave them empty to send at any time.
sendWindowStartandsendWindowEndare minutes from midnight (0 to 1440) intimezone, for example540for 09:00 and1080for 18:00. Set both or neither. The start must be before the end, so a window can’t cross midnight. The automation sends from the start up to, but not including, the end.sendWeekdayslists the days to send on, asSUN,MON,TUE,WED,THU,FRI, orSAT. Empty means every day.timezonedefaults toUTC. The supported timezones areUTC,America/New_York,America/Chicago,America/Denver,America/Los_Angeles,America/Phoenix,America/Sao_Paulo,America/Manaus,America/Fortaleza,Europe/London,Europe/Paris,Europe/Berlin,Europe/Madrid,Europe/Rome,Europe/Amsterdam,Europe/Istanbul,Asia/Amman,Asia/Riyadh,Asia/Dubai,Asia/Beirut,Asia/Kuwait,Asia/Qatar,Asia/Bahrain,Asia/Baghdad,Asia/Jerusalem,Africa/Cairo,Africa/Casablanca,Africa/Algiers,Africa/Tunis,Africa/Tripoli.
Contacts that become due outside the window are messaged when the next window opens, if they are still within the catch-up window.
Automation states
| State | Meaning | Moves to |
|---|---|---|
draft | Created by Create Automation API. Sends nothing. | active when activated. |
active | Messages contacts as they become due. A workspace can have at most 20 active automations. | paused when paused, deleted, or paused automatically. |
paused | Sends nothing. Activating it again continues where it stopped, within the catch-up window. | active when activated. |
You can patch an automation in any state. Changes to an active automation apply from its next run. The trigger can only change while the automation is draft or paused.
Automatic pauses and errors
When a run can’t send, the automation saves the reason in lastError. Some problems need you to act, so the automation is also paused:
- The channel or template can’t be used any more. For example the channel was deleted, the template no longer exists or no longer matches
templateComponents, or WhatsApp rejects it because it was paused or disabled (Meta error codes132xxx). - More than half of the sends in a batch failed, with at least 4 sends in the batch.
Fix the cause, then activate the automation again. Other problems are temporary. The automation stays active, keeps the reason in lastError, and tries again on the next run:
- The workspace reached its broadcast usage limit (
USAGE_LIMIT_REACHED: ...) or ran out of credits. - The template couldn’t be checked, for example during a WhatsApp outage.
Contacts that weren’t sent because of one of these problems are not marked as failed. They are tried again once the problem is gone, if they are still within the catch-up window. lastError is cleared when a later run sends without problems, and when the automation is activated.
A send that fails for one contact only, for example because of an invalid number, is saved as a failed occurrence and the run goes on.
Deleting an automation
Delete Automation API stops the automation and soft-deletes it: its state becomes paused and deletedAt is set. A deleted automation is left out of List Automations API and Automation State Counts API, and patching, activating, pausing, or deleting it again fails with Target automation is not found!. Its history is kept: Get Automation API still returns it, and its occurrences and stats stay available.
Occurrences
Every time the automation picks a contact, it creates an occurrence.
status | Meaning |
|---|---|
queued | The contact was picked and the message is being sent. An occurrence still queued after an hour is marked failed on the next run, with Interrupted before the message was sent. |
sent | The message was handed to the channel. messageStatus follows its delivery. |
failed | The message couldn’t be sent to this contact. failedReason says why. |
WhatsApp can still reject a message after its occurrence is sent. Then messageStatus becomes failed and failedReason holds the message’s failure reason.
Automation Occurrence Stats API counts:
delivered: messages that were delivered, including the ones read since. The number never drops as messages move on to read.read: messages that were read or played.failed:failedoccurrences, plussentmessages that WhatsApp rejected later. Such a message counts in bothsentandfailed.replied: occurrences the contact replied to.
Replies
A message from the contact counts as a reply to an occurrence when:
- the occurrence was sent within the last 7 days (the reply window),
- the occurrence has no reply yet, and
- the newest broadcast or automation message the contact received came from this automation.
The reply can start a new conversation or arrive in a conversation that is already open. Only the first reply counts. It sets repliedAt and conversationId. If several occurrences of the automation wait for a reply from the same contact, the newest one gets it.
List Automations API
List the automations in a workspace, newest first. Deleted automations are not returned.
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. |
state | AutomationState | Filter by state: |
name | string | Case-insensitive substring match on the automation name. |
pageInfo argument
Optional second argument. See Pagination for the general rules.
| Attribute | Type | Description |
|---|---|---|
limit | number | Automations per page. Defaults to 100. |
cursor | timestamp | The |
pageInfo.query and pageInfo.count are not used. Filter by name with the name input instead.
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery automations($input: AutomationsInput!, $pageInfo: PageInfoInput) {
automations(input: $input, pageInfo: $pageInfo) {
nodes {
id
name
state
triggerType
delayMinutes
templateName
sentCount
lastOccurrenceAt
lastError
createdAt
}
pageInfo {
hasNextPage
endCursor
}
}
}
input AutomationsInput {
workspaceId: Int! # Workspace ID.
state: AutomationState # Filter by state.
name: String # Filter by name (case-insensitive contains).
}The query above returns JSON structured like this:
{
"data": {
"automations": {
"nodes": [
{
"id": "automation_123",
"name": "Welcome follow-up",
"state": "active",
"triggerType": "clientCreated",
"delayMinutes": 4320,
"templateName": "welcome_followup",
"sentCount": 182,
"lastOccurrenceAt": "2026-10-28T09:12:40.000Z",
"lastError": null,
"createdAt": "2026-10-01T08:30:00.000Z"
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "2026-10-01T08:30: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":"automations","variables":{"input":{"workspaceId":12,"state":"active","name":"welcome"},"pageInfo":{"limit":20}},"query":"query automations($input: AutomationsInput!, $pageInfo: PageInfoInput) {\n automations(input: $input, pageInfo: $pageInfo) {\n nodes {\n id\n name\n state\n triggerType\n delayMinutes\n templateName\n sentCount\n lastOccurrenceAt\n lastError\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n }\n }\n}"}'Get Automation API
Get one automation by ID, with its settings, template, and send summary. Deleted automations are returned too, with deletedAt set, so their history stays available.
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 automation ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery automation($input: AutomationInput!) {
automation(input: $input) {
id
name
integrationId
state
triggerType
delayMinutes
maxLatenessDays
reentryPolicy
reentryCooldownDays
clientTags
clientStageId
country
timezone
sendWindowStart
sendWindowEnd
sendWeekdays
templateName
templateLang
templateComponents
activatedAt
lastRunAt
lastError
sentCount
lastOccurrenceAt
createdAt
deletedAt
}
}
input AutomationInput {
workspaceId: Int! # Workspace ID.
id: ID! # Automation ID.
}The query above returns JSON structured like this:
{
"data": {
"automation": {
"id": "automation_123",
"name": "Welcome follow-up",
"integrationId": "integration_123",
"state": "active",
"triggerType": "clientCreated",
"delayMinutes": 4320,
"maxLatenessDays": 3,
"reentryPolicy": "once",
"reentryCooldownDays": null,
"clientTags": [
"new-lead"
],
"clientStageId": null,
"country": null,
"timezone": "Asia/Riyadh",
"sendWindowStart": 540,
"sendWindowEnd": 1080,
"sendWeekdays": [
"SUN",
"MON",
"TUE",
"WED",
"THU"
],
"templateName": "welcome_followup",
"templateLang": "en",
"templateComponents": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "{{name}}"
}
]
}
],
"activatedAt": "2026-10-01T09:00:00.000Z",
"lastRunAt": "2026-10-28T09:15:02.000Z",
"lastError": null,
"sentCount": 182,
"lastOccurrenceAt": "2026-10-28T09:12:40.000Z",
"createdAt": "2026-10-01T08:30:00.000Z",
"deletedAt": null
}
}
}| Error | Cause |
|---|---|
Target automation is not found! | No automation with this ID in the workspace. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"automation","variables":{"input":{"workspaceId":12,"id":"automation_123"}},"query":"query automation($input: AutomationInput!) {\n automation(input: $input) {\n id\n name\n integrationId\n state\n triggerType\n delayMinutes\n maxLatenessDays\n reentryPolicy\n reentryCooldownDays\n clientTags\n clientStageId\n country\n timezone\n sendWindowStart\n sendWindowEnd\n sendWeekdays\n templateName\n templateLang\n templateComponents\n activatedAt\n lastRunAt\n lastError\n sentCount\n lastOccurrenceAt\n createdAt\n deletedAt\n }\n}"}'Automation State Counts API
Count the automations in a workspace per state, for example to show tab badges. The result always has one entry per state, in the order draft, active, paused, with 0 for states that have no automations. Deleted automations 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. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery automationStateCounts($input: AutomationStateCountsInput!) {
automationStateCounts(input: $input) {
state
count
}
}
input AutomationStateCountsInput {
workspaceId: Int! # Workspace ID.
}The query above returns JSON structured like this:
{
"data": {
"automationStateCounts": [
{
"state": "draft",
"count": 2
},
{
"state": "active",
"count": 3
},
{
"state": "paused",
"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":"automationStateCounts","variables":{"input":{"workspaceId":12}},"query":"query automationStateCounts($input: AutomationStateCountsInput!) {\n automationStateCounts(input: $input) {\n state\n count\n }\n}"}'Automation Audience Preview API
Count the contacts an automation would reach with the given trigger and conditions, before you save or activate it. Nothing is saved or sent, and the settings are not validated.
matchingCountis the number of contacts that match the conditions now.dueCountis the number of those contacts that are already due within the catch-up window. They are messaged on the first run after activation.
Pass automationId when you preview changes to an existing automation. Contacts it already messaged, and would not message again under reentryPolicy, are then left out of dueCount.
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. |
automationId | string | The automation being edited, if any. |
triggerType | AutomationTriggerType | Required. |
delayMinutes | number | Required. Minutes after the trigger date when the message is due. |
maxLatenessDays | number | The catch-up window in days. Defaults to 1. |
reentryPolicy | AutomationReentryPolicy |
|
reentryCooldownDays | number | The cooldown in days when |
clientTags | string[] | Contacts must have at least one of these tags. |
clientStageId | string | Contacts must be in this lifecycle stage. |
country | string | Contacts must be from this country. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery automationAudiencePreview($input: AutomationAudiencePreviewInput!) {
automationAudiencePreview(input: $input) {
matchingCount
dueCount
}
}
input AutomationAudiencePreviewInput {
workspaceId: Int! # Workspace ID.
automationId: ID # The automation being edited.
triggerType: AutomationTriggerType! # clientCreated or lastConversationStarted.
delayMinutes: Int! # Minutes after the trigger date.
maxLatenessDays: Int # Catch-up window in days. Defaults to 1.
reentryPolicy: AutomationReentryPolicy # Only used with automationId.
reentryCooldownDays: Int # Only used with automationId.
clientTags: [String!] # Contacts must have any of these tags.
clientStageId: String # Contacts must be in this stage.
country: String # Contacts must be from this country.
}The query above returns JSON structured like this:
{
"data": {
"automationAudiencePreview": {
"matchingCount": 1240,
"dueCount": 37
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"automationAudiencePreview","variables":{"input":{"workspaceId":12,"triggerType":"clientCreated","delayMinutes":4320,"maxLatenessDays":3,"clientTags":["new-lead"]}},"query":"query automationAudiencePreview($input: AutomationAudiencePreviewInput!) {\n automationAudiencePreview(input: $input) {\n matchingCount\n dueCount\n }\n}"}'Create Automation API
Create an automation in draft state. A draft sends nothing until you activate it with Activate Automation API. The settings are validated, and the template is checked against the WhatsApp Channel as in broadcasts.
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 | Required. The automation name. It can't be empty. |
integrationId | string | Required. The integration (Channel) ID used to send the template. |
triggerType | AutomationTriggerType | Required. |
delayMinutes | number | Required. Minutes after the trigger date when the message is due, from 0 to |
maxLatenessDays | number | The catch-up window in days, from 1 to 30. Defaults to 1. See Catch-up window. |
reentryPolicy | AutomationReentryPolicy |
|
reentryCooldownDays | number | Required when |
clientTags | string[] | Contacts must have at least one of these tags. |
clientStageId | string | Contacts must be in this lifecycle stage. |
country | string | Contacts must be from this country. |
timezone | string | The timezone of the send window. Defaults to |
sendWindowStart | number | Start of the daily send window, in minutes from midnight (0 to 1440). Set it together with |
sendWindowEnd | number | End of the daily send window, in minutes from midnight (0 to 1440). Must be after |
sendWeekdays | string[] | Days to send on: |
templateName | string | Required. The template name. |
templateLang | string | The template language. |
templateComponents | JSON | The template component variables, in the same format as broadcasts. String values support placeholders such as |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation createAutomation($input: AutomationCreateInput!) {
createAutomation(input: $input) {
id
name
state
triggerType
delayMinutes
maxLatenessDays
reentryPolicy
templateName
integrationId
createdAt
}
}
input AutomationCreateInput {
workspaceId: Int! # Workspace ID.
name: String! # Automation name.
integrationId: ID! # Integration/channel ID.
triggerType: AutomationTriggerType! # clientCreated or lastConversationStarted.
delayMinutes: Int! # Minutes after the trigger date, 0 to 525600.
maxLatenessDays: Int # Catch-up window in days, 1 to 30. Defaults to 1.
reentryPolicy: AutomationReentryPolicy # once, cooldown or everyOccurrence. Defaults to once.
reentryCooldownDays: Int # 1 to 365. Required with cooldown.
clientTags: [String!] # Contacts must have any of these tags.
clientStageId: String # Contacts must be in this stage.
country: String # Contacts must be from this country.
timezone: String # Send window timezone. Defaults to UTC.
sendWindowStart: Int # Minutes from midnight.
sendWindowEnd: Int # Minutes from midnight.
sendWeekdays: [String!] # SUN to SAT. Empty means every day.
templateName: String! # Template name.
templateLang: String # Template language.
templateComponents: JSON # Template component variables.
}The mutation above returns JSON structured like this:
{
"data": {
"createAutomation": {
"id": "automation_123",
"name": "Welcome follow-up",
"state": "draft",
"triggerType": "clientCreated",
"delayMinutes": 4320,
"maxLatenessDays": 3,
"reentryPolicy": "once",
"templateName": "welcome_followup",
"integrationId": "integration_123",
"createdAt": "2026-10-01T08:30:00.000Z"
}
}
}| Error | Cause |
|---|---|
Automations are not enabled for this workspace | Automations are in beta and not turned on for this workspace yet. Contact support to turn them on. |
The automation name is required | name is empty or only spaces. |
The delay must be between 0 minutes and 365 days | delayMinutes is below 0 or above 525600. |
The catch-up window must be between 1 and 30 days | maxLatenessDays is below 1 or above 30. |
The delay after the last conversation must be less than 90 days | The trigger is lastConversationStarted, the 90-day rule is on, and delayMinutes is 129600 or more. |
Repeating an automation is only possible with the last conversation trigger | reentryPolicy is cooldown or everyOccurrence with the clientCreated trigger. |
The cooldown must be between 1 and 365 days | reentryPolicy is cooldown and reentryCooldownDays is missing or out of range. |
The timezone is not supported | timezone is not one of the supported timezones. |
The send days are not valid | sendWeekdays has a value other than SUN, MON, TUE, WED, THU, FRI, or SAT. |
The send window start must be before its end | Only one of sendWindowStart and sendWindowEnd is set, a value is outside 0 to 1440, or the start is not before the end. |
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. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"createAutomation","variables":{"input":{"workspaceId":12,"name":"Welcome follow-up","integrationId":"integration_123","triggerType":"clientCreated","delayMinutes":4320,"maxLatenessDays":3,"clientTags":["new-lead"],"timezone":"Asia/Riyadh","sendWindowStart":540,"sendWindowEnd":1080,"sendWeekdays":["SUN","MON","TUE","WED","THU"],"templateName":"welcome_followup","templateLang":"en","templateComponents":[{"type":"body","parameters":[{"type":"text","text":"{{name}}"}]}]}},"query":"mutation createAutomation($input: AutomationCreateInput!) {\n createAutomation(input: $input) {\n id\n name\n state\n triggerType\n delayMinutes\n maxLatenessDays\n reentryPolicy\n templateName\n integrationId\n createdAt\n }\n}"}'Patch Automation API
Update an automation in any state. Fields you leave out keep their current values. The settings are validated again with the merged values, and the template is checked again when you change integrationId, templateName, templateLang, or templateComponents. Changes to an active automation apply from its next run.
triggerType can only change while the automation is draft or paused. Changing it starts the automation over: the next activation works like a first activation (see Catch-up window).
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 automation ID. |
name | string | The new name. Ignored when |
integrationId | string | The integration (Channel) ID. Ignored when |
triggerType | AutomationTriggerType | The trigger. Only while the automation is |
delayMinutes | number | The delay in minutes. Ignored when |
maxLatenessDays | number | The catch-up window in days. Ignored when |
reentryPolicy | AutomationReentryPolicy | The re-entry policy. Ignored when |
reentryCooldownDays | number | The cooldown in days. Pass |
clientTags | string[] | Target tags. Pass |
clientStageId | string | Target stage ID. Pass |
country | string | Target country. Pass |
timezone | string | The send window timezone. Ignored when |
sendWindowStart | number | Start of the send window. Pass |
sendWindowEnd | number | End of the send window. Pass |
sendWeekdays | string[] | Days to send on. Pass |
templateName | string | The template name. Ignored when |
templateLang | string | The template language. Pass |
templateComponents | JSON | The template component variables. Ignored when |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation patchAutomation($input: AutomationPatchInput!) {
patchAutomation(input: $input) {
id
name
state
triggerType
delayMinutes
maxLatenessDays
reentryPolicy
templateName
integrationId
clientStageId
patchedAt
}
}
input AutomationPatchInput {
workspaceId: Int! # Workspace ID.
id: ID! # Automation ID.
name: String
integrationId: ID
triggerType: AutomationTriggerType # Only while draft or paused.
delayMinutes: Int
maxLatenessDays: Int
reentryPolicy: AutomationReentryPolicy
reentryCooldownDays: Int # null clears it.
clientTags: [String!] # [] removes the filter.
clientStageId: String # null clears it.
country: String # null clears it.
timezone: String
sendWindowStart: Int # null clears it.
sendWindowEnd: Int # null clears it.
sendWeekdays: [String!] # [] means every day.
templateName: String
templateLang: String # null clears it.
templateComponents: JSON
}The mutation above returns JSON structured like this:
{
"data": {
"patchAutomation": {
"id": "automation_123",
"name": "Welcome follow-up",
"state": "active",
"triggerType": "clientCreated",
"delayMinutes": 2880,
"maxLatenessDays": 3,
"reentryPolicy": "once",
"templateName": "welcome_followup",
"integrationId": "integration_123",
"clientStageId": null,
"patchedAt": "2026-10-28T11:04:19.000Z"
}
}
}| Error | Cause |
|---|---|
Target automation is not found! | No automation with this ID in the workspace, or it was deleted. |
Pause the automation before changing its trigger | triggerType changes while the automation is active. |
The automation name is required | name is empty or only spaces. |
The delay must be between 0 minutes and 365 days | delayMinutes is below 0 or above 525600. |
The catch-up window must be between 1 and 30 days | maxLatenessDays is below 1 or above 30. |
The delay after the last conversation must be less than 90 days | The trigger is lastConversationStarted, the 90-day rule is on, and delayMinutes is 129600 or more. |
Repeating an automation is only possible with the last conversation trigger | reentryPolicy is cooldown or everyOccurrence with the clientCreated trigger. |
The cooldown must be between 1 and 365 days | reentryPolicy is cooldown and reentryCooldownDays is missing or out of range. |
The timezone is not supported | timezone is not one of the supported timezones. |
The send days are not valid | sendWeekdays has a value other than SUN, MON, TUE, WED, THU, FRI, or SAT. |
The send window start must be before its end | Only one of sendWindowStart and sendWindowEnd is set, a value is outside 0 to 1440, or the start is not before the end. |
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. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"patchAutomation","variables":{"input":{"workspaceId":12,"id":"automation_123","delayMinutes":2880,"clientStageId":null}},"query":"mutation patchAutomation($input: AutomationPatchInput!) {\n patchAutomation(input: $input) {\n id\n name\n state\n triggerType\n delayMinutes\n maxLatenessDays\n reentryPolicy\n templateName\n integrationId\n clientStageId\n patchedAt\n }\n}"}'Activate Automation API
Activate a draft or paused automation. Activating an automation that is already active returns it unchanged.
On the first activation, contacts that are already due within the catch-up window are messaged on the first run. A paused automation continues where it stopped. Activation also clears lastError.
Before activating, the API checks that automations are turned on for the workspace, that the workspace is within its broadcast usage limit, that fewer than 20 automations are active, that the settings are valid, and that the template still exists on the Channel.
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 automation ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation activateAutomation($input: AutomationStateInput!) {
activateAutomation(input: $input) {
id
state
activatedAt
lastError
}
}
input AutomationStateInput {
workspaceId: Int! # Workspace ID.
id: ID! # Automation ID.
}The mutation above returns JSON structured like this:
{
"data": {
"activateAutomation": {
"id": "automation_123",
"state": "active",
"activatedAt": "2026-10-01T09:00:00.000Z",
"lastError": null
}
}
}| Error | Cause |
|---|---|
Target automation is not found! | No automation with this ID in the workspace, or it was deleted. |
Automations are not enabled for this workspace | Automations are in beta and not turned on for this workspace yet. Contact support to turn them on. |
USAGE_LIMIT_REACHED: Broadcast usage exceeded 120% of the plan limit for this period. | The workspace is over its broadcast usage limit. Upgrade the plan or wait for the next period. |
A workspace can have at most 20 active automations | The workspace already has 20 active automations. Pause one first. |
The automation has no template | The automation has no templateName. |
A settings error, for example The delay after the last conversation must be less than 90 days | The saved settings are no longer valid. See Create Automation API for the list. |
A template error, for example Target integration does not exist | The Channel or template can’t be used. See Create Automation API for the list. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"activateAutomation","variables":{"input":{"workspaceId":12,"id":"automation_123"}},"query":"mutation activateAutomation($input: AutomationStateInput!) {\n activateAutomation(input: $input) {\n id\n state\n activatedAt\n lastError\n }\n}"}'Pause Automation API
Pause an active automation. It stops sending, and a run that is in progress stops before its next batch. Pausing an automation that is not active returns it unchanged. Activate it again with Activate Automation API to continue where it stopped.
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 automation ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation pauseAutomation($input: AutomationStateInput!) {
pauseAutomation(input: $input) {
id
state
patchedAt
}
}
input AutomationStateInput {
workspaceId: Int! # Workspace ID.
id: ID! # Automation ID.
}The mutation above returns JSON structured like this:
{
"data": {
"pauseAutomation": {
"id": "automation_123",
"state": "paused",
"patchedAt": "2026-10-28T11:20:00.000Z"
}
}
}| Error | Cause |
|---|---|
Target automation is not found! | No automation with this ID in the workspace, or it was deleted. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"pauseAutomation","variables":{"input":{"workspaceId":12,"id":"automation_123"}},"query":"mutation pauseAutomation($input: AutomationStateInput!) {\n pauseAutomation(input: $input) {\n id\n state\n patchedAt\n }\n}"}'Delete Automation API
Delete an automation in any state. It stops sending and is soft-deleted: its state becomes paused and deletedAt is set. Its occurrence history is kept. See Deleting an automation. Managers can create and activate automations 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 automation ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation deleteAutomation($input: AutomationStateInput!) {
deleteAutomation(input: $input) {
id
state
deletedAt
}
}
input AutomationStateInput {
workspaceId: Int! # Workspace ID.
id: ID! # Automation ID.
}The mutation above returns JSON structured like this:
{
"data": {
"deleteAutomation": {
"id": "automation_123",
"state": "paused",
"deletedAt": "2026-10-28T11:30:00.000Z"
}
}
}| Error | Cause |
|---|---|
Target automation is not found! | No automation with this ID in the workspace, or it was deleted. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"deleteAutomation","variables":{"input":{"workspaceId":12,"id":"automation_123"}},"query":"mutation deleteAutomation($input: AutomationStateInput!) {\n deleteAutomation(input: $input) {\n id\n state\n deletedAt\n }\n}"}'List Automation Occurrences API
List the occurrences of one automation, newest first. Each occurrence is one send to one contact, with the contact, the trigger and due dates, the send status, the delivery status, and the reply. Occurrences of deleted automations are returned too.
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. |
automationId | string | Required. The automation ID. |
status | AutomationOccurrenceStatus | Filter by status: |
from | DateTime | Lower bound (inclusive) on the occurrence |
to | DateTime | Upper bound (inclusive) on the occurrence |
pageInfo argument
Optional second argument. See Pagination for the general rules.
| Attribute | Type | Description |
|---|---|---|
limit | number | Occurrences per page. Defaults to 100. |
cursor | timestamp | The |
query | string | Search contacts. Digits, spaces, and |
count | boolean | When |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery automationOccurrences($input: AutomationOccurrencesInput!, $pageInfo: PageInfoInput) {
automationOccurrences(input: $input, pageInfo: $pageInfo) {
nodes {
id
clientId
clientName
clientPhone
anchorAt
dueAt
status
messageStatus
failedReason
conversationId
repliedAt
createdAt
}
pageInfo {
hasNextPage
endCursor
count
}
}
}
input AutomationOccurrencesInput {
workspaceId: Int! # Workspace ID.
automationId: ID! # Automation ID.
status: AutomationOccurrenceStatus # queued, sent or failed.
from: DateTime # Lower bound (inclusive) on createdAt.
to: DateTime # Upper bound (inclusive) on createdAt.
}The query above returns JSON structured like this:
{
"data": {
"automationOccurrences": {
"nodes": [
{
"id": "occurrence_456",
"clientId": "client_456",
"clientName": "Sara Ahmad",
"clientPhone": "966500000002",
"anchorAt": "2026-10-25T09:05:00.000Z",
"dueAt": "2026-10-28T09:05:00.000Z",
"status": "sent",
"messageStatus": "read",
"failedReason": null,
"conversationId": "conversation_456",
"repliedAt": "2026-10-28T10:41:07.000Z",
"createdAt": "2026-10-28T09:15:02.000Z"
},
{
"id": "occurrence_123",
"clientId": "client_123",
"clientName": "Omar Khaled",
"clientPhone": "966500000001",
"anchorAt": "2026-10-25T08:50:00.000Z",
"dueAt": "2026-10-28T08:50:00.000Z",
"status": "failed",
"messageStatus": null,
"failedReason": "Invalid phone number",
"conversationId": null,
"repliedAt": null,
"createdAt": "2026-10-28T09:00:03.000Z"
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "2026-10-28T09:00:03.000Z",
"count": 2
}
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"automationOccurrences","variables":{"input":{"workspaceId":12,"automationId":"automation_123","from":"2026-10-01T00:00:00.000Z","to":"2026-10-31T23:59:59.999Z"},"pageInfo":{"limit":20,"count":true}},"query":"query automationOccurrences($input: AutomationOccurrencesInput!, $pageInfo: PageInfoInput) {\n automationOccurrences(input: $input, pageInfo: $pageInfo) {\n nodes {\n id\n clientId\n clientName\n clientPhone\n anchorAt\n dueAt\n status\n messageStatus\n failedReason\n conversationId\n repliedAt\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'Automation Occurrence Stats API
Get the totals of one automation’s occurrences, for example to show a funnel from sent to replied. See Occurrences for what each number counts and Replies for the reply window. Leave out from and to to count all time.
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. |
automationId | string | Required. The automation ID. |
from | DateTime | Lower bound (inclusive) on the occurrence and message |
to | DateTime | Upper bound (inclusive) on the occurrence and message |
Response fields
| Field | Type | Description |
|---|---|---|
total | number | All occurrences: |
queued | number | Occurrences still being sent. |
sent | number | Occurrences whose message was handed to the channel. |
delivered | number | Messages delivered, including the ones read since. |
read | number | Messages read or played. |
failed | number | Failed occurrences, plus sent messages that WhatsApp rejected later. |
replied | number | Occurrences the contact replied to within 7 days of the send. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery automationOccurrenceStats($input: AutomationOccurrenceStatsInput!) {
automationOccurrenceStats(input: $input) {
total
queued
sent
delivered
read
failed
replied
}
}
input AutomationOccurrenceStatsInput {
workspaceId: Int! # Workspace ID.
automationId: ID! # Automation ID.
from: DateTime # Lower bound (inclusive) on createdAt.
to: DateTime # Upper bound (inclusive) on createdAt.
}The query above returns JSON structured like this:
{
"data": {
"automationOccurrenceStats": {
"total": 190,
"queued": 0,
"sent": 182,
"delivered": 175,
"read": 131,
"failed": 11,
"replied": 46
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"automationOccurrenceStats","variables":{"input":{"workspaceId":12,"automationId":"automation_123","from":"2026-10-01T00:00:00.000Z","to":"2026-10-31T23:59:59.999Z"}},"query":"query automationOccurrenceStats($input: AutomationOccurrenceStatsInput!) {\n automationOccurrenceStats(input: $input) {\n total\n queued\n sent\n delivered\n read\n failed\n replied\n }\n}"}'