Actions

Actions are operations your agent can perform during conversations. They allow your agent to interact with external systems, provide structured responses, or transfer conversations to human agents.

Types of Actions

Stellar supports three types of actions:

API calls: Let your agent fetch or update information from your existing systems in real-time using an API call. For example for looking up order details or checking account balances
Static responses: Provide your agent with fixed information to share consistently, perfect for things like business hours or policy details. Can also be used to test your agent before implementing a live API call action in detail.
Handover Actions: Allow your agent to smoothly transfer customers to a human representative when needed

Creating Actions

To create an action:

Navigate to the Actions tab
Click Add Action
Select the action type
Configure the action settings

API call actions

API Call actions let your agent fetch data or perform operations in your external systems.

Configuration

Name and description

Name: A clear and descriptive action name (e.g., get_order_status, create_support_ticket)
Description: Explain what this action does and when to use it

The agent uses the name and description to decide when to call this action, so be specific for better performance.

Example:

Name: get_order_status
Description: Retrieves the current status of a customer's order.
Use this when the customer asks about their order or wants to know when it will arrive.
Requires an order number.

URL

The full URL of your API endpoint.

Example for GET requests:

https://api.yourcompany.com/orders

Example for POST requests:

https://api.yourcompany.com/support/tickets

How parameters are sent

The URL field is static and does not support parameter placeholders. Parameters are automatically handled based on the HTTP method:

GET and DELETE: Parameters are automatically appended as query parameters (e.g., ?order_number=ORD-12345)
POST, PUT, and PATCH: Parameters are sent in the request body (see Request Body Template below)

For example, a GET request to https://api.yourcompany.com/orders with parameter {"order_number": "ORD-12345"} becomes https://api.yourcompany.com/orders?order_number=ORD-12345 at runtime.

HTTP Method

Select the appropriate HTTP method for your API endpoint:

GET: Retrieve information
POST: Create new records or submit data
PUT: Update existing records completely
PATCH: Update specific fields
DELETE: Remove records

Headers

Add HTTP headers your API requires:

Common headers:

Content-Type: application/json
Authorization: Bearer {api_key} (use secrets for sensitive values)
X-API-Version: 1.0

Using Secrets

For sensitive values like API keys, use secrets instead of hardcoding them. Configure secrets in the Secrets section, then reference them as {secret_name}.

Parameters schema

Define the parameters your API expects using JSON Schema format. This tells the agent what information to collect from the customer.

Example schema for getting order status:

{
  "type": "object",
  "properties": {
    "order_number": {
      "type": "string",
      "description": "The customer's order number"
    }
  },
  "required": ["order_number"]
}

Example schema for creating a support ticket:

{
  "type": "object",
  "properties": {
    "customer_email": {
      "type": "string",
      "description": "The customer's email address"
    },
    "issue_description": {
      "type": "string",
      "description": "Description of the technical issue"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "description": "Priority level of the issue"
    }
  },
  "required": ["customer_email", "issue_description"]
}

The agent will automatically ask the customer for any required parameters it doesn't already have.

Write detailed parameter descriptions

The agent uses parameter descriptions to understand what information to collect and how to ask for it. Be as descriptive as possible. Explain what the parameter is, what format it should be in, and provide examples.

Clear descriptions lead to better agent performance and more accurate data collection.

Request Body Template (Optional)

For POST, PUT, and PATCH requests, you can optionally define a request body template to control exactly how parameters are sent to your API. If no template is provided, parameters are sent as a simple JSON object.

Template Syntax:

Use Go template syntax to insert parameter values and conversation variables:

{{.parameters.parameter_name}} - Access parameters from the parameter schema
{{.variables.variable_name}} - Access conversation variables

Example: Custom request body structure

If your API expects a nested structure:

{
  "order": {
    "id": "{{.parameters.order_number}}",
    "customerEmail": "{{.parameters.email}}"
  },
  "metadata": {
    "conversationId": "{{.variables.stellar.conversation_id}}",
    "source": "voice_agent"
  }
}

Example: Without template (default)

If no template is defined, parameters are sent as a flat JSON object:

{
  "order_number": "ORD-12345",
  "email": "customer@example.com"
}

When to use request body templates

Use request body templates when:

Your API requires a specific nested structure
You need to include conversation variables (like conversation ID, user ID, etc.)
You want to add static fields alongside dynamic parameters
Your API expects a different field naming convention

For simple APIs that accept flat JSON objects, you can leave this blank.

Parameter routing

Parameters are automatically routed based on the HTTP method:

GET and DELETE requests: Parameters are sent as query parameters appended to the URL
POST, PUT, and PATCH requests: Parameters are sent in the request body (using the template if provided, or as a flat JSON object if not)

Static response actions

Static response actions return fixed text responses. Use them for information that doesn't change or doesn't require external API calls and that you don't want to always include into the agent's context. They are also well-suited for testing API calls in your agent context before actually integrating them.

Configuration

Name: Action name (e.g., get_business_hours)
Description: What the action does and when to use it
Response Text: The fixed response to return

Example:

Name: get_business_hours
Description: Provides business hours for ACME Corporation. Use when customer asks when we're open or what our hours are.

Response:
We're open Monday through Friday, 9am to 6pm Eastern Time.
We're closed on weekends and major holidays.
For urgent issues outside business hours, email support@example.com and we'll respond within 4 hours.

When to use static responses

Static responses can be well-suited for:

Business hours
Return policies
Shipping information
Company policies
General FAQs

They're faster than API calls and don't require external system integration.

Handover actions

Handover actions transfer the conversation to a human agent. This is critical for handling complex issues or customer requests.

Configuration

Type

Choose the handover method:

Phone: Transfer to a specific phone number
Queue: Transfer to a queue in your phone system (e.g., a Genesys queue)

Phone number (for phone type)

Enter the phone number to route the call to a human agent for takeover, including country code:

+31612345678

Queue ID (for queue type)

Enter the queue identifier from your contact center system. This is used to route the call to a human agent for takeover when the handover action is triggered. The queue ID must match exactly (case-sensitive) with the queue name configured in your contact center system.

Example:

customer_support_tier2

Announcement Message

Optional message the agent says before transferring:

Example:

I'm going to connect you with one of our specialists who can help you with this. Please hold for just a moment.

Handover Action Example

Name: transfer_to_human_agent
Description: Transfer the customer to a human agent. Use when customer explicitly requests a human, issue is too complex, or customer is frustrated.

Type: Queue
Queue: general_support
Announcement: Let me connect you with one of our team members who can assist you further. One moment please.

Restricting action access per state

You can restrict which states can use a particular action using strict state separation. This prevents inappropriate action usage in certain conversation contexts.

Example restrictions:

process_refund should only be available in "Billing Support" state
create_support_ticket should only be available in "Technical Support" state
transfer_to_human should be available in all states (leave unrestricted)

Editing action access

Action access in states is managed from the Dialogue Builder. To restrict an action to specific states:

Go to the Dialogue Builder
Click on the state where you want to make the action available
In the Available actions for this step section, select which actions should be available
Save the state

When viewing an action in the action editor, you can see which states it's currently restricted to. However, you can only edit this from the state editor itself.

Testing Actions

Test in Playground

Start a conversation in the Playground
Have your conversation such that the agent should perform the action
Check the event feed to see:
- When the action was called
- What parameters were sent
- What response was received
- If any errors occurred

Common Issues

Agent doesn't call the action:

Description may be unclear
Agent doesn't have enough information
Action is restricted to wrong states

API errors:

Check your API URL and credentials
Verify parameter schema matches API expectations
Review headers, especially authentication

Wrong parameters sent:

Refine parameter descriptions in schema
Test with explicit parameter values
Review conversation to see what customer provided

Best Practices

Name Actions Clearly

Use descriptive names that indicate what the action does:

✅ get_order_status, create_support_ticket, cancel_subscription
❌ action1, api_call, do_thing

Write Detailed Descriptions

The description is how the agent decides when to use an action. Be specific about:

What the action does
When to use it
What information is needed

Keep APIs Simple

Each action should do one thing well. If an API does multiple things, create separate actions for each use case.

Handle Errors Gracefully

Ensure your APIs return helpful error messages. The agent will relay these to customers.

Use Secrets for Credentials

Never hardcode API keys in URLs or headers. Always use the Secrets management system.

Test Thoroughly

Test actions with various inputs:

Valid data
Missing required parameters
Invalid parameter formats
API failures

Next Steps

After configuring actions:

Assign actions to relevant states in the Dialogue Builder
Test each action in the Playground
Set up guardrails to ensure safe action usage
Set up evaluation rules to automatically assess conversation quality
Monitor conversations to see how actions are being used

Types of Actions​

Creating Actions​

API call actions​

Configuration​

Name and description​

URL​

HTTP Method​

Headers​

Parameters schema​

Request Body Template (Optional)​

Parameter routing​

Static response actions​

Configuration​

Handover actions​

Configuration​

Type​

Phone number (for phone type)​

Queue ID (for queue type)​

Announcement Message​

Handover Action Example​

Restricting action access per state​

Editing action access​

Testing Actions​

Test in Playground​

Common Issues​

Best Practices​

Name Actions Clearly​

Write Detailed Descriptions​

Keep APIs Simple​

Handle Errors Gracefully​

Use Secrets for Credentials​

Test Thoroughly​

Next Steps​

Types of Actions

Creating Actions

API call actions

Configuration

Name and description

URL

HTTP Method

Headers

Parameters schema

Request Body Template (Optional)

Parameter routing

Static response actions

Configuration

Handover actions

Configuration

Type

Phone number (for phone type)

Queue ID (for queue type)

Announcement Message

Handover Action Example

Restricting action access per state

Editing action access

Testing Actions

Test in Playground

Common Issues

Best Practices

Name Actions Clearly

Write Detailed Descriptions

Keep APIs Simple

Handle Errors Gracefully

Use Secrets for Credentials

Test Thoroughly

Next Steps