Actions

Actions are predefined, executable tasks that your agents can perform to interact with external systems or execute specific logic. They are the functional units that allow your agents to go beyond simple conversation and actually do things, making them powerful tools for automation and integration.

While the platform is designed to support various action types in the future, the currently available type is the HTTP Request.

How Actions Work

Actions do not run on their own. They are designed to be executed as part of a Topic. The workflow is as follows:

1. A user's message triggers a Topic.
2. The Topic's instructions guide the agent to collect the necessary information from the user (e.g., a name, an email address, a product ID).
3. The agent executes the Action linked to that Topic, inserting the collected information as dynamic values into the task's parameters.
4. The agent then uses the result of the Action to formulate its final response to the user.

Use Cases

• Sending data to a CRM: Create a new lead in Salesforce or HubSpot.
• Querying an external database: Fetch product stock levels or order statuses via a REST API.
• Triggering notifications: Send an email via an email service provider's API or a Slack message via a webhook.
• Connecting to legacy systems: Interact with internal company APIs.

---

Action Configuration Reference

This section provides a detailed breakdown of every field available when creating or editing an Action.

Field	Description
Name	A unique, programmatic name for the action. Use a clear, consistent naming convention (e.g., verb_noun_context like send_quotation_request). This name is used internally to identify the action. If you enter the name in non-snake case, it will be converted automatically for you.
Description	A human-readable summary of what the action does. This helps your team understand the purpose of the action at a glance. Example: "Sends a new quotation request to the internal database."
Type	The type of action to perform. This architecture is designed to support various types of integrations in the future (e.g., direct database queries, sending emails). Currently available type: HTTP Request.

HTTP Request Fields

The following fields are specific to the HTTP Request action type.

Field	Description	Dynamic Values
Method	The HTTP method for the request. Choose from GET, POST, UPDATE, PATCH, or DELETE.	No
URL	The endpoint URL for the API request. Example: https://api.myblog.com/articles/{articleId}.	Yes
Authentication	Securely configure authentication for the external API. Choose from: None: For public APIs. Basic Auth: Uses a Username and Password. Header: Passes credentials in a request header (e.g., Authorization: Bearer YOUR_SECRET_KEY). Query: Passes credentials as a URL query parameter (e.g., ?api_key=YOUR_KEY).	No
Headers	Specify any necessary HTTP headers. Array Mode: Add key-value pairs (e.g., Content-Type : application/json). Raw Mode: Write a complete JSON object for the headers.	Yes
Query Parameters	Add key-value pairs that will be appended to the URL. Typically used with GET requests. Example: keyword : {search_term} becomes ?keyword=laptops.	Yes
Body	Define the payload for POST, PATCH, or UPDATE requests. Array Mode: Add key-value pairs. This is the standard mode. Raw Mode: Write a complete JSON object for the body. None: Send no body with the request.	Yes
Body Advanced Mode	A toggle to enable precise data typing for the body. When enabled, you can specify the type for each field in the body array: String, Number, Integer, Boolean, Object, or Enum.	No

Secure Credential Storage

All authentication values you enter in the Authentication settings are encrypted and stored securely. They cannot be viewed again after the action is saved. Do not use the Headers section to set authentication details.

---

Dynamic Values: The {} Syntax

Dynamic values are placeholders in your Action configuration that are replaced with real data at runtime. The AI extracts this data from the user's conversation based on the instructions in the parent Topic.

You can use dynamic values in the URL, Headers, Query Parameters, and Body of an HTTP Request Action.

Example flow:

1. User says: "I'd like a quote for product XYZ. My name is John Doe and my email is john.doe@example.com."
2. Topic instructions: The Topic has instructions like "Extract the user's name, email, and the product they are asking about."
3. Action execution: The Action is configured with a body like this:

   {
     "customer_name": "{name}",
     "customer_email": "{email}",
     "product_sku": "{product}"
   }

4. Result: The AI model populates the placeholders, and the final HTTP request body sent to the external API is:

   {
     "customer_name": "John Doe",
     "customer_email": "john.doe@example.com",
     "product_sku": "XYZ"
   }

Sensitive Data

We do not recommend sending sensitive data via chat. If your external system requires a password, set authentication via the action settings as these values are not shared in the conversation and are not handled by the model making it impossible for data leaks.

---

Full Example: Sending a Lead to a CRM

Let's walk through a complete example of creating an Action and linking it to a Topic.

Goal: Capture a new lead from a chatbot conversation and send it to a fictional CRM API.

Create the Action

• Name: send_lead_to_crm
• Description: Sends the user's name and email to the CRM to create a new lead.
• Type: HTTP Request
• Method: POST
• Authentication: Header
  • Name: X-API-Key
  • Value: YOUR_CRM_API_KEY
• URL: https://api.mycrm.com/v1/leads
• Body (Array Mode):
  • name : {name}
  • email : {email}
  • source : Website Chatbot (This is a static value)

Create the Topic

• Name: New Lead Capture
• Classification description: Triggers when a user expresses interest in a demo or talking to sales.
• Instructions:
  1. Ask the user for their full name.
  2. Ask the user for their email address.
  3. Confirm that the email address is in a valid format.
• Actions:
  • Search for and add the send_lead_to_crm action you just created.
• Agent Response:
  • Thank you, {name}! A member of our sales team will reach out to you at {email} shortly.

Link the Topic to an Agent

Finally, navigate to your desired Agent, go to the Topics tab, and add the New Lead Capture topic. The agent is now fully equipped to capture and send new leads.