Trigger flows with Robilityflow API
After you build a flow, you probably want to run it within an application, such as a chatbot within a mobile app or website.
Robility flow provides several ways to run flows from external applications:
a. Trigger flows with the Robility flow API
b. Add an embedded chat widget to a website
c. Serve flows through a Robility flow MCP server
Although you can use these options with an isolated, local Robility flow instance, they are typically more valuable when you have deployed a Robility flow server or packaged Robility flow as a dependency of an application.
Use the Robility flowAPI to run flows
Robility flow API is the primary way to access your flows and Robility flow servers programmatically.
Try it
For an example of a script that calls the Robility flowAPI, see the Quickstart.
Generate API code snippets
To help you embed Robility flowAPI requests in your scripts, Robility flow automatically generates Python, JavaScript, and curl code snippets for your flows. To get these code snippets, do the following:
1. In Robility flow, open the flow that you want to embed in your application.
2. Click Share, and then select API access.
These code snippets call the /v1/run/$FLOW_ID endpoint, and they automatically populate minimum values, like the Robility flowserver URL, flow ID, headers, and request parameters.
3. Optional: Click Input Schema to modify component parameters in the code snippets without changing the flow itself.
4. Copy the snippet for the language that you want to use.
5. Run the snippet as is or use the snippet in the context of a larger script.
For more information and examples of other Robility flowAPI endpoints, see Get started with the Robility flowAPI.
Robility flow API authentication
In Robility flow most API endpoints require authentication with a Robility flowAPI key.
Code snippets generated in the API access pane include a script that checks for a ROBILITYFLOW_API_KEY environment variable set in the local terminal session. This script doesn’t check for Robility flow API keys set anywhere besides the local terminal session.
For this script to work, you must set a ROBILITYFLOW_API_KEY variable in the terminal session where you intend to run the code snippet, such as export ROBILITYFLOW_API_KEY=”sk…”.
Alternatively, you can edit the code snippet to include an x-api-key header and ensure that the request can authenticate to the Robility flowAPI.
For more information, see API keys and authentication and Get started with the Robility flowAPI.
Input Schema (tweaks)
Tweaks are one-time overrides that modify component parameters at runtime, rather than permanently modifying the flow itself. For an example of tweaks in a script, see the Quickstart.
In the API access pane, click Input Schema to add tweaks to the request payload in a flow’s code snippets.
Changes to a flow’s Input Schema are saved exclusively as tweaks for that flow’s API access code snippets. These tweaks don’t change the flow parameters set in the workspace, and they don’t apply to other flows.
Adding tweaks through the Input Schema can help you troubleshoot formatting issues with tweaks that you manually added to Robility flow API requests.
For example, the following curl command includes a tweak that disables the Store Messages setting in a flow’s Chat Input component:
curl –request POST \
–url “http://ROBILITYFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID” \
–header “Content-Type: application/json” \
–header “x-api-key: ROBILITYFLOW_API_KEY” \
–data ‘{
“input_value”: “Text to input to the flow”,
“output_type”: “chat”,
“input_type”: “chat”,
“tweaks”: {
“ChatInput-4WKag”: {
“should_store_message”: false
}
}
}’
Use a flow ID alias
If you want your requests to use an alias instead of the actual flow ID, you can rename the flow’s /v1/run/$FLOW_ID endpoint:
1. In Robility flow, open the flow, click Share, and then select API access.
2. Click Input Schema.
3. In the Endpoint Name field, enter an alias for your flow’s ID, such as a memorable, human-readable name.
The name can contain only letters, numbers, hyphens, and underscores, such as flow-customer-database-agent.
4. To save the change, close the Input Schema pane.
The automatically generated code snippets now use your new endpoint name instead of the original flow ID, such as url = “http://localhost:7868/api/v1/run/flow-customer-database-agent”.
Embed a flow into a website
For each flow, Robility flow provides a code snippet that you can insert into the <body> of your website’s HTML to interact with your flow through an embedded chat widget.
Required components
The chat widget only supports flows that have Chat Input and Chat Output components, which are required for the chat experience. Text Input and Text Output components can send and receive messages, but they don’t include ongoing LLM chat context.
Attempting to chat with a flow that doesn’t have Chat Input component will trigger the flow, but the response only indicates that the input was empty.
Get a Robility flow-chat snippet
To get a flow’s embedded chat widget code snippet, do the following:
1. In Robility flow, open the flow you want to embed.
2. Click Share, and then select Embed into site.
3. Copy the code snippet and use it in the <body> of your website’s HTML. For more information, see Embed the chat widget with React, Angular, or HTML.
4. Add the api_key prop to ensure the widget has permission to run the flow, as explained in Configure the Robility flow-chat web component.
The chat widget is implemented as a web component called Robility flow-chat that is loaded from a CDN. For more information, see the robilityflow-embedded-chat repository.
For example, the following HTML embeds a chat widget for a Basic Prompting template flow hosted on a Robility flow server deployed on ngrok:
<html>
<head>
<script src=”https://cdn.jsdelivr.net/gh/robilityflow-ai/robilityflow-embedded-chat@main/dist/build/static/js/bundle.min.js”></script>
</head>
<body>
<robilityflow-chat
host_url=”https://c822-73-64-93-151.ngrok-free.app”
flow_id=”dcbed533-859f-4b99-b1f5-16fce884f28f”
api_key=”$ROBILITYFLOW_API_KEY”
></robilityflow-chat>
</body>
</html>
When this code is deployed to a live site, it renders as a responsive chatbot. If a user interacts with the chatbot, the input triggers the specified flow, and then the chatbot returns the output from the flow run.
Embed the chat widget with React, Angular, or HTML
The following examples show how to use embedded chat widget in React, Angular, and plain HTML.
a. React
b. Angular
c. HTML
To use the chat widget in your React application, create a component that loads the widget script and renders the chat interface:
1. Declare your web component, and then encapsulate it in a React component:
//Declaration of robilityflow-chat web component
declare global {
namespace JSX {
interface IntrinsicElements {
“robilityflow-chat”: any;
}
}
}
//Definition for robilityflow-chat React component
export default function ChatWidget({ className }) {
return (
<div className={className}>
<robilityflow-chat
host_url=”https://c822-73-64-93-151.ngrok-free.app”
flow_id=”dcbed533-859f-4b99-b1f5-16fce884f28f”
api_key=”$ROBILITYFLOW_API_KEY”
></robiltiyflow-chat>
</div>
);
}
2. Place the component anywhere in your code to render the chat widget.
In the following example, the React widget component is located at docs/src/components/ChatWidget/index.tsx, and index.tsx includes a script to load the chat widget code from CDN, along with the declaration and definition from the previous step:
import React, { useEffect } from ‘react’;
// Component to load the chat widget script
const ChatScriptLoader = () => {
useEffect(() => {
if (!document.querySelector(‘script[src*=”robilityflow-embedded-chat”]’)) {
const script = document.createElement(‘script’);
script.src = ‘https://cdn.jsdelivr.net/gh/robilityflow-ai/robilityflow-embedded-chat@main/dist/build/static/js/bundle.min.js’;
script.async = true;
document.body.appendChild(script);
}
}, []);
return null;
};
//Declaration of robilityflow-chat web component
declare global {
namespace JSX {
interface IntrinsicElements {
“robilityflow-chat”: any;
}
}
}
//Definition for robilityflow-chat React component
export default function ChatWidget({ className }) {
return (
<div className={className}>
<ChatScriptLoader />
<robilityflow-chat
host_url=”https://c822-73-64-93-151.ngrok-free.app”
flow_id=”dcbed533-859f-4b99-b1f5-16fce884f28f”
api_key=”$ROBILITYFLOW_API_KEY”
></robilityflow-chat>
</div>
);
}
3. Import the robilityflow-chat React component to make it available for use on a page. Modify the following import statement with your React component’s name and path:
import ChatWidget from ‘@site/src/components/ChatWidget’;
4. To display the widget, call your robilityflow-chat component in the desired location on the page. Modify the following reference for your React component’s name and the desired className:
<ChatWidget className=”my-chat-widget” />
Configure the robilityflow-chat web component
To use the embedded chat widget in your HTML, the robilityflow-chat web component must include the following minimum inputs (also known as props in React):
a. host_url: Your Robility flow server URL. Must be HTTPS. Don’t include a trailing slash (/).
b. flow_id: The ID of the flow you want to embed.
c. api_key: A Robility flowAPI key. This prop is recommended to ensure the widget has permission to run the flow.
The minimum inputs are automatically populated in the Embed into site code snippet that is generated by Robility flow.
You can use additional inputs (props) to modify the embedded chat widget. For a list of all props, types, and descriptions, see the robilityflow-embedded-chat README.
Example: Robility flowAPI key propExample: Style propsExample: Session ID propExample: Tweaks prop
Serve flows through a Robility flow MCP server
Each Robility flow project has an MCP server that exposes the project’s flows as tools that MCP clients can use to generate responses.
In addition to serving flows through Robility flow MCP servers, you can use Robility flow as an MCP client to access any MCP server, including Robility flow MCP servers.
Interactions with Robility flow MCP servers happen through the Robility flow API’s /mcp endpoints.
