How to Connect an ActionJail Action to a Bot Scenario (Integrator)

This instruction will help you integrate a created action into a scenario, configure parameters, pass data to an external API, and catch errors so the scenario works stably.

When It Will Be Useful

• You need to call an external API or your own logic in a scenario.
• There is a ready action in ActionJail that needs to be used as a bot step.
• You need to quickly replace logic without changing the entire scenario.

What's Important to Know

• An Action has a system ID action_*, parameters (JSON config), and a form (UI schema).
• A bot scenario calls an action as a step and passes parameter values.
• API secrets belong in Settings → Scenario secrets; use Credential-type parameters in the action — do not pass plain-text tokens in scenario JSON (see use scenario secrets in a custom action).
• Error handling: it's worth returning a structured response or error codes for the scenario.

Before You Start

• The action is already created and published in ActionJail.
• You know what parameters the external API needs (keys, URL, payload).
• You have access to the scenario builder.

Step-by-Step Instructions

1. Open the bot scenario builder and add an action execution step.
2. Select an action from the list by name or system ID action_*.
3. Fill parameter values: for secrets pick a record in a Credential field; for URL, client id, etc. use regular fields or {{variable}} placeholders.
4. Use placeholders like {{variable_name}} to pass dynamic values from user constants.
5. Configure error handling: add conditional branches based on the action's return value (for example, success, error).
6. Test the scenario: run it and verify that the action executes correctly and returns expected values.

What Happens After

• The action is integrated into the scenario and executes when the bot reaches this step.
• Parameters are passed to the action, and the result is available for further scenario logic.

How to Verify Everything Worked

• The action executes without errors in the scenario.
• Parameters are passed correctly (check in action logs or debug mode).
• Error handling works if the action returns an error code.

Other Ways

• Use action return values for conditional branching in the scenario.
• Combine multiple actions in sequence for complex workflows.

Related Instructions

• Create and maintain an action
• Actions Reference
• Use scenario secrets in a custom action