Action Flow Steps Reference
This article is focussed on steps you can add to an Action Flow after the 'start' point. It covers:
Triggers, which cause your Action Flow to start, are described in the Triggers article.
How steps run within Action Flow
Steps are run as soon as possible
Atomic always tries to run steps as soon as possible. After an Action Flow instance starts, the system immediately looks for the one (or more) steps directly connected to the start node, queues the tasks, then attempts to run them as quickly as possible.
- If the step is a Send a card step, the instruction will be processed immediately. The card will be created, respecting the delivery settings configured for the step, and once created, the step will be marked as completed. Atomic will then immediately look for steps directly connected to the Send a card step and attempt to run them.
- If the step being run is a wait step, Atomic will wait, respecting the configuration on the step. A wait step can pause and listen for a card event from a card sent by a parent step, only proceeding when a specific action has been tracked, or it can wait for a period of time.
All Action Flow activities are queued before processing, to ensure the scalability and resilience of the system. This can mean the elapsed time between steps being processed slows during times of heavy system load and may be worth bearing in mind as you design your flows.
Customers flow through all possible branches
To have more than one step run when the parent step has completed, you can simply add multiple steps directly connected to that parent step. Once the parent step is completed, all directly connected children steps will be run.
If you need to daisy-chain events so they happen one after the other, you can achieve this by only adding one child per step.
If a step fails, that instance of the Action Flow will stop
Each time an Action Flow is triggered for a customer we create a unique instance of the Action Flow for them. This means, while more than one customer may be targeted in the original trigger event, we still send each individual customer through the Action Flow alone.
- If any step fails to complete (for example if a send API request receives an error when running) then this unique instance of the Action Flow will be completely stopped.
- You can run your own steps in response to a failure, before the instance stops, by adding an error handler to your Action Flow.
- Any cards already created by the Action Flow will still be live. These can be canceled via the Cancel Cards tool, or by using an Action a card step within an error handler.
- Error events will be tracked in analytics, so you can be alerted.
See Errors within Action Flows for a full explanation of how errors are handled, the errors you might encounter, and how to set up an error handler.
Each step can only run once per Action Flow instance
When Atomic evaluates a step, it will look for the first opportunity to complete the step, then move on. For example, if you configure a Wait for Card Event step to wait for a card sent in the previous step to be snoozed or completed or dismissed, then when Atomic detects the first one of these, it will complete the step and move on.
If for example, you want to listen for card events independently, you can achieve this by adding multiple wait steps as children of the send card step. This way, each branch will wait independently of the others.
Steps can access Context data from steps before them
The data available to a running Action Flow instance builds as the flow steps are run.
- When the Action Flow starts, a snapshot of the data from the originating trigger event (if any) is added to the data context.
- Any variables defined in the Action Flow will have their values resolved when the flow starts, and those resolved variables are added to the data context.
- The customer profile values for the current target customer are also available in the data context (the latest values are always used, not a snapshot).
- As each step completes, analytics events are emitted within the platform capturing details of the step and these too are added to the data context for the flow instance, including any outputs from cards, or API requests along the way.
The Action Flow context article explains how context works and how to use it, but the headline is that each step in an Action Flow can access the full context data from the steps above it (not in adjacent branches).
Action Flow Step Types
You can control which step types are available in your environment from the Action Flow Step Types configuration page.
Send a card
Sends your customer an in-app action card.
- Configure delivery settings, including which streams it will be visible in, priority and card lifecycle details by selecting the step from the canvas
- When you click Send card in the add-step menu, an inline picker lets you choose how this step should get its card template. The four options are described in the Send card step picker section below.
- You can still switch a step to a different template later from the properties panel on the right, and you can delete unlinked card templates from the left side menu
- If you want Atomic to also send a push notification when this card is created, you can configure this alongside the card template
If you are migrating legacy cards to Action Flows, we strongly recommend updating any trigger events to no longer send card delivery metadata in the event payload. Read the migration guide for more information.
Send card step picker
After clicking Send card in the add-step menu, you'll see a picker with four ways to provide the card template for the new step.
- Create new card template - starts a blank card template, attaches it to the new step.
- Reuse a card from this Action Flow - points the new step at a card template that already exists in this Action Flow. The template is shared, so edits made in any step that uses it affect all of them.
- Copy a card from this Action Flow - duplicates an existing template in this Action Flow and attaches the copy to the new step. The new step can be edited independently of the original.
- Copy a card from another Action Flow - imports a card template definition from any other Action Flow in the environment into this one and attaches the copy to the new step. The copy is independent of the source; future changes to the original do not flow through.
Imported templates carry their layout, content, actions, and subviews - but not the source flow's variables or step context. References inside the template to flow variables or context paths that don't exist in the destination Action Flow will not resolve and may need rewiring after the copy.
Send a notification
Sends your customers a mobile push notification (without sending an in-app action card).
- Configure the notification by selecting the step from the canvas
- Enable background notifications if required
When delivering push notifications, any push notification that would normally be sent during a customer's do not disturb windows (if set by your apps) will be automatically rescheduled to go out after the do-no-disturb window ends.
Send a request
Sends an API request to a third-party system.
- The destination URL can be static, or contain context placeholders to construct some or all of the URL dynamically with context data
- The send a request step supports making
POST,PUT,GET,PATCHandDELETErequests - credentials can be used to authenticate the outgoing requests
- You can provide static header values for the request, however credentials are the preferred method of authentication
- If your endpoint requires a certificate for mutual TLS, client certificates can be added in the Configuration section
- Requests will originate from a static IP address
Mapping the request and response
- The body of the request can be a static payload, or a dynamic payload you define using either JavaScript or a no-code mapping, that can customize each request using some or all of the data available to this step in context.
- Data from the responses can be added back into the context of the flow, to be used downstream by child steps. To do this, you'll create a mapping, providing an example of a typical response, then define a mapping which outputs key/value pairs.
Handling failure
- Responses to the outgoing request need to return an acceptable status code, otherwise the Send a request step will error, causing an action flow instance to stop
- You can run steps in response to the failure, such as notifying an external system, by adding an error handler to your Action Flow
- Which status codes are acceptable for the Action Flow to proceed are configurable under the "Acceptable response codes" settings on the step. By default, any response code in the 200 - 299 range is successful and any other will cause a failure. The "acceptable response codes" setting does not apply to any requests made to generate authorization headers (via the use of credentials), these must always return a successful response.
- The response status code is included in the Action Flow context as
statusCodeafter a send-request step, and is also available within the response mapping context - this allows branching and graceful handling on failure of the request.
When testing or debugging your action flow, having Atomic send flow context data to a webhook provided by a service like webhook.site can help save time. However, be sure to follow your organization's security practices before sending any test or live customer data to a third-party service.
Pre-configured send-request steps
A suite of integrations are available for third-party services. These pre-configured send-request steps take the hard work out of integrating Action Flows with key services. Under the hood these steps are send-request steps with the configuration already set, surfacing only the key configurations to set in the Atomic workbench.
- After choosing and configuring a pre-configured step, it is possible to configure the underlying settings on a case-by-case basis. To do so, choose the "advanced" option in the step editor. Note that once you choose to look at the advanced settings you will not be able to revert to the simpler preconfigured view for that step.
- The preconfigured steps are handled just like a send-request step, instances of them in your Action Flows are not automatically updated should the third party API change in some way.
- As with send-request steps, be mindful of where these steps are used in an Action Flow. If the Action Flow is high volume then the endpoint that these steps connect to can also receive a lot of traffic.
Currently supported services for pre-configured steps are:
Is there a third-party service you'd like to see included as a pre-configured step? Get in touch with us and let us know.
The Atomic.io API
- Start Action Flow
- Update customer profile
- Emit custom event
- Cancel cards
- Look up cards
- Check card cancel status
Adobe Marketo
- Track custom activity
- Sync leads
Google Analytics
- Track custom event
OpenAI
- Prompt completion
- Moderation
Snowflake
- Execute SQL statement
Gemini
- Generate content
Twilio
- Send SMS
Google Calendar
- List events
Google Sheets
- Add a row
Amazon Bedrock
- Generate content
Amazon Connect
- Get realtime contact analysis
Customer.io
- Track event
- Identify user
- Search customers
- Fetch customer attributes
- Fetch customer segments
- Find customer by email
WhatsApp
- Send text message
- Send image message
Slack
- Send webhook message
Notion
- Add a page
- Add to a database
Sinch
Note: these steps are authenticated with a Basic auth credential (your MessageMedia API key as the username and API secret as the password)
- Send SMS
- Get message status
- Get replies
- Confirm reply
Wait for a period of time
Pauses the current branch for a set amount of time.
- This step provides a way to prevent Atomic from moving immediately from a completed step to a child step, by making it pause for a set time.
- You can use these steps to pace out a complex multi-step interaction, add delays to allow other systems to be updated, or any other situation where you need to wait for a predetermined time before continuing.
- After Atomic starts a wait for a period of time step it will pause, then resume and complete at the end of the specified time.
Wait for a card event
An event listener for card events. Pauses the current branch until a specific card-event is detected.
- This step can only be added to your flow immediately following a send a card step, and it will only listen for card events relating to the card instance created by that parent step.
- It provides a way to prevent Atomic from moving immediately from a completed step to a child step, by making it pause until it detects a specific event relating to the action card sent by its parent step.
- The events this step can listen for include are published, displayed, completed, dismissed and more (the full list of card events this step can listen for is below).
- You can configure the step to listen for one or more events, but the first event detected will satisfy the wait rule and complete the step.
- After Atomic starts a wait for a card event step it will pause, then resume and complete when the first event it is listening for occurs.
Because customers will flow through all branches you may choose to add more than one of these wait for a card steps to the same parent step, in situations where you want to independently respond to create different branches for different events. For example, you may want to create a branch to send customers down if they complete the card, and a separate branch if they dismiss it.
Wait for a custom event
An event listener for your custom events sent to Atomic via API or SDK. Pauses the current branch until a custom-event is detected.
- Custom event steps will listen for incoming custom events before resuming the flow.
- The payload of the custom event can be used to pass data to subsequent steps in the flow.
Custom events need to include the flowInstanceId in the event payload, read more about sending custom events.
An example use-case of Atomic Action Flow custom event resumption
Track a goal
Records that a customer has made it to this point in the Action Flow.
- This step enables you to explicitly track when users reach key moments in your Action Flow
- When configuring the step, you'll provide a name for the goal, and optionally assign a value to each conversion event
- Goal values can be recorded as points, currency, or time and the values can be static, or set dynamically based on context data
- When track a goal steps complete, the action-flow-step-completed analytics event is generated. Within this analytic event there are two attributes which you can use in your analysis and system outside of Atomic -
properties.goalValueandproperties.goalValueMeasure. - Tracked goal values can also be used when making a send a request step, if you want to use an action flow step to pass this information out after the goal step is completed
- Action Flow reports in the Workbench will also use goal data to show you how your Action Flows are performing
We recommend always assigning values to your track a goal steps, to make the most of the reporting in Atomic, and to assist in capturing and communicating the business impact of your Action Flows
Action a card
Complete or cancel one of the cards created by a previous step
- This step lets you cancel or complete a card that you send in an earlier step
- This can be used to dynamically recall other cards if the user has completed certain actions or it's no longer desirable to show the card
Run a script
Transform context data with a small piece of JavaScript.
- This step runs a JavaScript snippet you write, and returns the result back into the Action Flow so that later steps can use it.
- Use it to reshape, combine, or derive new values from the context data available at this point in the Action Flow, for example formatting a date, building a message string, or choosing a value based on the output of earlier steps.
- The context available at this step is passed to your script, and a sample of it is shown alongside the editor so you can preview your output as you write it.
Branch flow
Conditionally branch your flow based on input from previous steps
- The branch step allows you to configure different branches that your Action Flow can traverse
- When setting up a branch step you provide the criteria for a user to enter one of the branches, this can be done through simple comparisons or complex scripts
- This step type can be used to set up A/B testing or conditionally send a user different cards based on their input in previous ones - among many other possibilities
Stop the Action Flow
Halt further execution of the Action Flow for the current customer
- Any existing cards will remain published and will be allowed to complete.
- No further steps will be run for this customer in any branch of the Action Flow. As soon as any stop step is hit the entire Action Flow instance will halt execution.
An example use-case of the Atomic Action Flow stop step
Atomic AI
Atomic AI steps are in preview and may be subject to change. Please contact us to provide feedback.
Run an AI-powered task with the output available as context for subsequent steps.
Atomic AI steps let you perform AI tasks directly inside an Action Flow without needing an external AI service or API keys, such as classifying users, analyzing user sentiment, summarizing text, or translating content.
The AI's output can be used in other steps, so you can branch on a classification result, personalize a card with a summary, or pass AI-generated data to a third-party system or CRM.
Atomic AI is enabled in all environments, regardless of your plan. If required by your organization, the Atomic AI step can be disabled for an environment to prevent it being used in Action Flows.
Cost
Atomic AI usage is measured in tokens. A token is a chunk of text of roughly four characters that the underlying AI model reads or writes. Both the text going in (your system prompt and instructions) and the text coming back are made up of tokens.
Your Atomic environment has a bundled monthly token allowance for your Atomic AI steps. Each time an Atomic AI step is run within an Action Flow, the total number of input and output tokens used are deducted from the environment's monthly allowance.
- Your token allowance for the month is shown when viewing an Atomic AI step.
- Once the environment's token allowance has been used up, Atomic AI steps can be configured to either return no output, or cause the Action Flow to fail.
- If an Atomic AI response cannot be returned, no tokens are deducted.
If you require additional tokens or your monthly allowance increased, please contact us with your Atomic AI use-cases.
Capabilities
Three capabilities are available, trading off speed and usage against the quality of the Atomic AI output. Each capability is backed by an AI model managed by Atomic. Advanced capabilities consume more tokens by applying a multiplier to the total tokens used.
| Capability | Token multiplier | Description |
|---|---|---|
| Fast | 1x | Fastest responses and least token usage. Best for high-volume tasks like classification, data extraction, and simple transformations. |
| Balanced | 1.5x | Moderate speed and token usage. Ideal for most tasks, including summarization, sentiment analysis, and content generation. |
| Advanced | 2x | Most capable but slower and most token-intensive. Best for complex reasoning, nuanced analysis, and tasks requiring deep understanding. |
For high-volume Action Flows, Fast uses significantly fewer tokens than the other capabilities for the same task. Start with Fast and only step up to Balanced or Advanced if the output quality isn't meeting your needs.
Using Atomic AI
After adding an Atomic AI step to your Action Flow, the quickest way to get started is choosing one of several templates to get started, offering a range of pre-built instructions designed for use-cases such as:
- classifying and summarizing text
- analyzing user sentiment
- translating text into a different language
- redacting personally-identifiable information
Within your Atomic AI step:
- the Instructions provide the main task you want the AI to perform. Your instructions can include variables and outputs from other steps to act as context.
- the optional System prompt act as an outline or guidelines to how the AI should process your instructions.
- the Output section defines how the AI should respond, as either:
- Text - a single output variable of text, or
- Variables - one or more variables that the Atomic AI can pre-populate with a response. Each variable uses a description to help Atomic AI fill it in.
Additionally, you can fine-tune the Atomic AI response under the Model settings, including choosing a more advanced capability, setting a limit on the response length, and choosing whether to fail the Action Flow if Atomic AI can't respond to your instructions.
Be specific in your instructions and optional system prompt, as more specific instructions and context about what you're trying to achieve will consistently produce better results.
Poor instructions: Summarize this text
Excellent instructions: Summarize the following customer feedback in one sentence, focusing on the main topic and overall tone.
Testing an Atomic AI step
Once your Atomic AI step has been set up with the instructions and desired output, you can use the Test button to run your instructions and see its output.
You can make any adjustments to your instructions or other settings before applying the changes to your step, and see how your instructions perform on any of the capabilities by comparing them side-by-side.
Testing your Atomic AI step against each capability will consume tokens as part of your monthly token allowance for the environment.
Examples
Each example below shows the shape of the Action Flow, along with sample configuration for its Atomic AI step. In the instructions and system prompts, italics mark a context placeholder you'd insert with the variable picker rather than text you'd type, such as the output from a card.
Classifying a response, then branching on the result
A common pattern is to have Atomic AI turn something unstructured, like free-text feedback a customer typed into a card, into a value your Action Flow can make decisions with.
Using the Variables output, the step returns named values such as sentiment and topic, which a following Branch step can compare against just like any other context data.
| Setting | Sample configuration |
|---|---|
| Instructions | Classify the following customer feedback by topic and overall sentiment: Feedback response |
| System prompt | You are triaging feedback for a retail bank's mobile app. Only ever choose from the values described for each variable. If the feedback is too short or unclear to classify, use "unclear". |
| Output | Variables:sentiment (One of: positive, neutral, negative, unclear)topic (One of: fees, app experience, branch service, other) |
| Capability | Fast (a short classification with a fixed set of answers doesn't need a more capable model) |
| Maximum response length | 256 (the response is only ever two short values) |
Summarizing data to personalize a card
Atomic AI can turn data you've fetched earlier into something worth reading. Here a Send a Request step retrieves the customer's recent transactions, Atomic AI summarizes them, and the summary is inserted into the card the customer receives.
| Setting | Sample configuration |
|---|---|
| Instructions | Summarize this customer's spending over the last month in two sentences, calling out the category they spent the most in: Transactions response |
| System prompt | Write in a warm, plain-English tone, in second person. Only use figures present in the data. Never estimate or infer a number. Do not give financial advice or recommend products. |
| Output | Variables:summary (Two sentence summary of the month's spending)topCategory (The category with the highest total spend) |
| Capability | Balanced (generating readable prose benefits from a more capable model than classification does) |
Redacting personal information before calling a third party
Because the Atomic AI output becomes context for later steps, it can also be used to clean up data on its way out of Atomic. Here personal details are stripped from a customer's free-text message before it is sent on to an external system.
| Setting | Sample configuration |
|---|---|
| Template | Replace PII |
| Instructions | Rewrite the following support request, replacing any names, email addresses, phone numbers, and account numbers with [redacted]: Support request message |
| System prompt | Keep the wording and meaning of the message intact. Only remove details that could identify the customer. Never add commentary or explain what you removed. |
| Output | Text (the redacted message is passed straight to the next step) |
| Capability | Fast |
| On failure | Fail the Action Flow, so an unredacted message is never sent to the helpdesk if the step can't complete |
Translating a card for the customer's language
An Atomic AI step placed inside a branch that only runs for customers whose profile language isn't English.
| Setting | Sample configuration |
|---|---|
| Instructions | Translate the following card title and body into the language identified by this code: Profile: language. Title: Card title. Body: Card body |
| System prompt | Keep the tone, meaning, and any formatting of the original. Do not translate brand names, product names, or amounts. Return only the translated text. |
| Output | Variables: title (The translated card title)body (The translated card body) |
| Capability | Balanced |
| Maximum response length | 2048 (translated text can run longer than the original) |
Privacy and data handling
Atomic AI steps run on the same Amazon Bedrock infrastructure as Ask Atomic, invoked from Atomic's own AWS account. That means prompts and responses are not used to train models, are not retained by Bedrock, and stay within the AWS account where Atomic invokes the service. They are never sent to an external AI vendor. See the Ask Atomic privacy and data handling section for full details.
Model lifecycle
The specific AI model behind each capability may be updated over time as newer models become available. To keep your Action Flows behaving predictably, the model your step runs against is pinned.
When an Atomic AI step is using a capability with a legacy or retired model, you'll be asked to upgrade the step by following the prompts shown. Upgrading to a newer model may change the step outputs, so we recommend testing the Atomic AI step to confirm no additional changes are required.
Once an AI model is retired, your Atomic AI step will automatically upgrade to the newer version.