Skip to Content
API ReferenceAutomations

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

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The automation ID.

namestring

The automation name.

integrationIdstring

The integration (Channel) ID used to send the template.

statestring

The automation state: draft, active, or paused. See Automation states.

triggerTypestring

The contact date the delay is counted from: clientCreated or lastConversationStarted. See Trigger and delay.

delayMinutesnumber

Minutes after the trigger date when the message is due.

maxLatenessDaysnumber

The catch-up window in days. Contacts that became due longer ago are skipped. See Catch-up window.

reentryPolicystring

How often the same contact can receive the automation: once, cooldown, or everyOccurrence. See Re-entry policies.

reentryCooldownDaysnumber

Minimum days between two messages to the same contact when reentryPolicy is cooldown.

clientTagsstring[]

Contacts must have at least one of these tags.

clientStageIdstring

Contacts must be in this lifecycle stage.

countrystring

Contacts must be from this country.

timezonestring

The IANA timezone of the send window. Defaults to UTC.

sendWindowStartnumber

Start of the daily send window, in minutes from midnight. Empty means any time of day.

sendWindowEndnumber

End of the daily send window, in minutes from midnight. Empty means any time of day.

sendWeekdaysstring[]

Days on which the automation sends: SUN, MON, TUE, WED, THU, FRI, SAT. Empty means every day.

templateNamestring

The WhatsApp template name.

templateLangstring

The WhatsApp template language.

templateComponentsjson

The WhatsApp template components, in the same format as broadcasts. String values support placeholders such as {{name}}, filled in per contact.

activatedAtDateTime

When the automation was first activated.

lastRunAtDateTime

When the last processing run finished.

lastErrorstring

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.

sentCountnumber

The number of occurrences with status sent.

lastOccurrenceAtDateTime

When the newest occurrence was created.

createdAtDateTime

The created timestamp.

patchedAtDateTime

The last updated timestamp.

deletedAtDateTime

Set when the automation was deleted. See Deleting an automation.

Automation occurrence properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The occurrence ID.

automationIdstring

The automation ID.

clientIdstring

The contact ID.

clientNamestring

The contact's name and surname.

clientPhonestring

The contact's phone number.

anchorAtDateTime

The trigger date of the contact that made it due.

dueAtDateTime

When the message became due: anchorAt plus the automation delay.

statusstring

The send state: queued, sent, or failed. See Occurrences.

messageStatusMessageStatus

The delivery status of the sent message: pending, sent, delivered, read, played, or failed. Empty until the message exists.

failedReasonstring

Why the send failed. When the channel rejected the message after it was sent, this is the message's failure reason.

messageIdstring

The ID of the sent message.

conversationIdstring

The conversation the contact replied in.

repliedAtDateTime

When the contact first replied. See Replies.

createdAtDateTime

When the contact was picked and the send started.

How automations work

Trigger and delay

triggerTypeTrigger date
clientCreatedWhen the contact was created in the workspace.
lastConversationStartedWhen 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

reentryPolicyBehavior
onceThe default. A contact receives the automation at most once, even if its trigger date changes later.
cooldownEvery 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.
everyOccurrenceEvery 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.

  • sendWindowStart and sendWindowEnd are minutes from midnight (0 to 1440) in timezone, for example 540 for 09:00 and 1080 for 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.
  • sendWeekdays lists the days to send on, as SUN, MON, TUE, WED, THU, FRI, or SAT. Empty means every day.
  • timezone defaults to UTC. The supported timezones are UTC, 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

StateMeaningMoves to
draftCreated by Create Automation API. Sends nothing.active when activated.
activeMessages contacts as they become due. A workspace can have at most 20 active automations.paused when paused, deleted, or paused automatically.
pausedSends 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 codes 132xxx).
  • 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.

statusMeaning
queuedThe 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.
sentThe message was handed to the channel. messageStatus follows its delivery.
failedThe 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: failed occurrences, plus sent messages that WhatsApp rejected later. Such a message counts in both sent and failed.
  • 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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

stateAutomationState

Filter by state: draft, active, or paused.

namestring

Case-insensitive substring match on the automation name.

pageInfo argument

Optional second argument. See Pagination for the general rules.

AttributeTypeDescription
limitnumber

Automations per page. Defaults to 100.

cursortimestamp

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

pageInfo.query and pageInfo.count are not used. Filter by name with the name input instead.

Request & Response

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

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The automation ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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 } } }
ErrorCause
Target automation is not found!No automation with this ID in the workspace.
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":"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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

Request & Response

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

  • matchingCount is the number of contacts that match the conditions now.
  • dueCount is 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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

automationIdstring

The automation being edited, if any.

triggerTypeAutomationTriggerType

Required. clientCreated or lastConversationStarted.

delayMinutesnumber

Required. Minutes after the trigger date when the message is due.

maxLatenessDaysnumber

The catch-up window in days. Defaults to 1.

reentryPolicyAutomationReentryPolicy

once, cooldown, or everyOccurrence. Only used with automationId.

reentryCooldownDaysnumber

The cooldown in days when reentryPolicy is cooldown. Only used with automationId.

clientTagsstring[]

Contacts must have at least one of these tags.

clientStageIdstring

Contacts must be in this lifecycle stage.

countrystring

Contacts must be from this country.

Request & Response

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

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

Required. The automation name. It can't be empty.

integrationIdstring

Required. The integration (Channel) ID used to send the template.

triggerTypeAutomationTriggerType

Required. clientCreated or lastConversationStarted. See Trigger and delay.

delayMinutesnumber

Required. Minutes after the trigger date when the message is due, from 0 to 525600 (365 days).

maxLatenessDaysnumber

The catch-up window in days, from 1 to 30. Defaults to 1. See Catch-up window.

reentryPolicyAutomationReentryPolicy

once, cooldown, or everyOccurrence. Defaults to once. See Re-entry policies.

reentryCooldownDaysnumber

Required when reentryPolicy is cooldown. From 1 to 365.

clientTagsstring[]

Contacts must have at least one of these tags.

clientStageIdstring

Contacts must be in this lifecycle stage.

countrystring

Contacts must be from this country.

timezonestring

The timezone of the send window. Defaults to UTC. See Send window.

sendWindowStartnumber

Start of the daily send window, in minutes from midnight (0 to 1440). Set it together with sendWindowEnd.

sendWindowEndnumber

End of the daily send window, in minutes from midnight (0 to 1440). Must be after sendWindowStart.

sendWeekdaysstring[]

Days to send on: SUN, MON, TUE, WED, THU, FRI, SAT. Empty means every day.

templateNamestring

Required. The template name.

templateLangstring

The template language.

templateComponentsJSON

The template component variables, in the same format as broadcasts. String values support placeholders such as {{name}}.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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" } } }
ErrorCause
Automations are not enabled for this workspaceAutomations are in beta and not turned on for this workspace yet. Contact support to turn them on.
The automation name is requiredname is empty or only spaces.
The delay must be between 0 minutes and 365 daysdelayMinutes is below 0 or above 525600.
The catch-up window must be between 1 and 30 daysmaxLatenessDays is below 1 or above 30.
The delay after the last conversation must be less than 90 daysThe 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 triggerreentryPolicy is cooldown or everyOccurrence with the clientCreated trigger.
The cooldown must be between 1 and 365 daysreentryPolicy is cooldown and reentryCooldownDays is missing or out of range.
The timezone is not supportedtimezone is not one of the supported timezones.
The send days are not validsendWeekdays has a value other than SUN, MON, TUE, WED, THU, FRI, or SAT.
The send window start must be before its endOnly 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 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.
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":"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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The automation ID.

namestring

The new name. Ignored when null.

integrationIdstring

The integration (Channel) ID. Ignored when null.

triggerTypeAutomationTriggerType

The trigger. Only while the automation is draft or paused. Ignored when null.

delayMinutesnumber

The delay in minutes. Ignored when null.

maxLatenessDaysnumber

The catch-up window in days. Ignored when null.

reentryPolicyAutomationReentryPolicy

The re-entry policy. Ignored when null.

reentryCooldownDaysnumber

The cooldown in days. Pass null to clear it.

clientTagsstring[]

Target tags. Pass [] to remove the filter. Ignored when null.

clientStageIdstring

Target stage ID. Pass null or "" to remove the filter.

countrystring

Target country. Pass null or "" to remove the filter.

timezonestring

The send window timezone. Ignored when null.

sendWindowStartnumber

Start of the send window. Pass null together with sendWindowEnd to send at any time of day.

sendWindowEndnumber

End of the send window. Pass null together with sendWindowStart to send at any time of day.

sendWeekdaysstring[]

Days to send on. Pass [] to send every day. Ignored when null.

templateNamestring

The template name. Ignored when null.

templateLangstring

The template language. Pass null to clear it.

templateComponentsJSON

The template component variables. Ignored when null. Send them again when you change the template.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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" } } }
ErrorCause
Target automation is not found!No automation with this ID in the workspace, or it was deleted.
Pause the automation before changing its triggertriggerType changes while the automation is active.
The automation name is requiredname is empty or only spaces.
The delay must be between 0 minutes and 365 daysdelayMinutes is below 0 or above 525600.
The catch-up window must be between 1 and 30 daysmaxLatenessDays is below 1 or above 30.
The delay after the last conversation must be less than 90 daysThe 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 triggerreentryPolicy is cooldown or everyOccurrence with the clientCreated trigger.
The cooldown must be between 1 and 365 daysreentryPolicy is cooldown and reentryCooldownDays is missing or out of range.
The timezone is not supportedtimezone is not one of the supported timezones.
The send days are not validsendWeekdays has a value other than SUN, MON, TUE, WED, THU, FRI, or SAT.
The send window start must be before its endOnly 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 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.
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":"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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The automation ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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 } } }
ErrorCause
Target automation is not found!No automation with this ID in the workspace, or it was deleted.
Automations are not enabled for this workspaceAutomations 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 automationsThe workspace already has 20 active automations. Pause one first.
The automation has no templateThe automation has no templateName.
A settings error, for example The delay after the last conversation must be less than 90 daysThe saved settings are no longer valid. See Create Automation API for the list.
A template error, for example Target integration does not existThe Channel or template can’t be used. See Create Automation API for the list.
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":"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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The automation ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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" } } }
ErrorCause
Target automation is not found!No automation with this ID in the workspace, or it was deleted.
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":"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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The automation ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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" } } }
ErrorCause
Target automation is not found!No automation with this ID in the workspace, or it was deleted.
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":"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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

automationIdstring

Required. The automation ID.

statusAutomationOccurrenceStatus

Filter by status: queued, sent, or failed.

fromDateTime

Lower bound (inclusive) on the occurrence createdAt.

toDateTime

Upper bound (inclusive) on the occurrence createdAt.

pageInfo argument

Optional second argument. See Pagination for the general rules.

AttributeTypeDescription
limitnumber

Occurrences per page. Defaults to 100.

cursortimestamp

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

querystring

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

countboolean

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

Request & Response

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

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

automationIdstring

Required. The automation ID.

fromDateTime

Lower bound (inclusive) on the occurrence and message createdAt.

toDateTime

Upper bound (inclusive) on the occurrence and message createdAt.

Response fields

FieldTypeDescription
totalnumber

All occurrences: queued + sent + failed.

queuednumber

Occurrences still being sent.

sentnumber

Occurrences whose message was handed to the channel.

deliverednumber

Messages delivered, including the ones read since.

readnumber

Messages read or played.

failednumber

Failed occurrences, plus sent messages that WhatsApp rejected later.

repliednumber

Occurrences the contact replied to within 7 days of the send.

Request & Response

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