- The Execute Code Card in Botpress allows you to run custom JavaScript inside bot workflows, enabling dynamic API calls, data processing, and personalized logic beyond standard built-in actions.
- Key use cases include dynamic API requests, post-processing LLM outputs, rate limiting, permission checks, and chaining multi-step API calls, letting AI agents handle complex workflows with precision.
- Best practices include securing API keys in environment variables, handling errors and timeouts gracefully, and building conditional logic for robust, secure bot operations — ensuring smooth, scalable API integrations.
AI agents are only as powerful as the data they can access. While large language models (LLMs) generate responses from training data, they can’t retrieve real-time stock prices, process payments, or access CRM details—unless integrated with APIs.
APIs enable AI agents to access real-time data, execute logic, and trigger actions. To leverage them fully, agents need custom code.
The 'Execute Code' Card in Botpress Studio lets you write and execute JavaScript Inside a bot's workflow—seamlessly handling API calls, data processing, and bot behavior customization.
What is the Execute Code Card?
The Execute Code Card in Botpress empowers developers to run custom JavaScript within the bot's flow. It enables the following functions:
- Custom Logic Implementation: You can execute complex calculations or transform data in ways not covered by standard actions.
- Dynamic Interactions: Adjust responses based on user data or real-time computations.
- Data Integrations: Seamlessly connect with third-party services to fetch or send data.
- State Management: Access and modify the bot’s state to maintain context and personalize interactions.
- Error Handling: Implement custom error management to ensure robust operations.
The Execute Code Card features AI-generated code suggestions. Enter a prompt—like fetching API data—and the system generates JavaScript instantly. You can then review, edit, and refine it as needed, speeding up development.
Why AI Agents Need External APIs?
AI agents are only as useful as the data and services they access. While they can process inputs and generate responses, they lack real-time knowledge, transactional capabilities, and deep integrations without external APIs.
Whether you're integrating real-time data, automating workflows, or enhancing security, APIs make your bot more intelligent, responsive, and integrated.
5 Ways to Use the Execute Code Card
The Execute Code Card in Botpress Studio streamlines AI agent operations. Adding it to your workflow is simple — follow this quick tutorial:
Once added, here are key ways to leverage it in your agentic workflow.
1. Dynamic API Calls
Instead of using static API calls, the Execute Card lets you dynamically modify requests based on user intent, bot context, or previous conversations.
Example: Fetching custom data based on user preferences.
Prompt: A travel chatbot needs to retrieve hotel prices based on the user's destination, travel dates, and budget.
.webp)
Note: The Execute Code Card can generate code from natural language. However, always verify the variables used in your generated code before deploying the workflow to production.
2. Post-Processing on LLM Responses
While Botpress provides built-in AI actions, sometimes you need to fine-tune responses before showing them to users—whether that’s formatting outputs, filtering certain words, or structuring data more clearly.
Example: Rewriting unstructured LLM responses into a defined table/format.
Prompt: AI fetches restaurant recommendations from an API, and I want you to format them into a clean table before displaying them.
.webp)
3. Rate-Limiting and Conditional Execution
Some APIs, including digital wallets, have usage limits. With the Execute Code Card, you can control user interactions by enforcing rate limits, setting fallbacks, and adding conditional logic based on API availability.
Example: Checking API Usage Before Calling It
Prompt: Check API quota from https://api.monitoring.com/usage?apikey=${workflow.userApiKey} before making a request. If fewer than 5 requests remain, return an error; otherwise, proceed. Ensure proper error handling in case of failures.
.webp)
4. Handling Permissions
If your bot needs to verify users before granting access to certain features, the card allows custom authentication flows that go beyond Botpress’s default options.
Example: Checking User Subscription Status Before Providing AI Responses
Prompt: Check a user's subscription via https://billing.example.com/user/{userId}. If on a free plan, prompt an upgrade; otherwise, allow access. Handle errors.
.webp)
5. Multi-Step API Chaining
Sometimes, a bot needs to combine data from multiple APIs before sending a final response. The card enables complex multi-step workflows by fetching, transforming, and passing data dynamically.
Example: Fetching Weather + Restaurant Reservation to Recommend the Best Time to Leave
Prompt: Fetch weather and traffic data for workflow.city using workflow.userApiKey. Based on conditions, return the best travel time. Handle failures.
.webp)
Seamless API Integrations for AI Agents
AI agents work best when they can tap into real-time data, automate workflows, and connect with external services.
Botpress Hub makes this seamless with pre-built API integrations, automation tools, and ready-to-use connectors—so you can focus on building, not configuring.
Start integrating powerful APIs into your bot’s workflows today—it's free.
FAQs
1. Do I need to know JavaScript to use the Execute Code Card effectively?
You don’t need deep JavaScript knowledge to use the Execute Code Card effectively. Botpress provides AI-powered code suggestions, so you describe what you want, and it generates starter code that you can adjust with minimal effort.
2. Are there templates or boilerplate code snippets for common API integrations?
Yes, Botpress offers built-in examples and boilerplate code snippets for common API integrations like CRMs and payment gateways. You can also browse community forums for ready-to-use code patterns.
3. Can I use the Execute Code Card without prior API integration experience?
Yes, you can use the Execute Code Card without prior API integration experience. The interface is beginner-friendly, and Botpress's AI helper can generate code and explain it, making the learning curve manageable even for non-developers.
4. How does the card handle long-running API requests or timeouts?
The Execute Code Card supports asynchronous JavaScript using async/await
, but you need to manually handle timeouts and failures. Best practice includes wrapping API calls in try/catch
blocks and defining fallback flows if a response is delayed or fails.
5. What are the best practices for implementing authentication and authorization using the card?
When implementing authentication and authorization in the Execute Code Card, you should store API keys or tokens in Botpress environment variables, send them via secure headers, and include logic to validate user roles or permissions before executing sensitive actions.