Skip to main content
In this guide, you’ll learn to:
  • Connect your agent to any external API
  • Configure authentication (Bearer, Basic, API Key)
  • Define parameters the agent collects from callers
  • Test and debug tool execution

​
How Custom Actions Work

Custom Actions let your AI agents integrate with external systems during conversations. Your agents can retrieve customer data, update CRM records, check inventory, create tickets, and execute business logic — all in real time while talking to customers. How it works:
  1. Configure the API endpoint - Set up HTTP method, URL, authentication, headers, and request body
  2. Define variables - Specify what information the agent needs to collect before calling the API
  3. Agent uses it - During conversation, agent collects the variables and calls your API
  4. API responds - Your system returns data that the agent uses to continue the conversation
Custom Actions execute synchronously during conversations. For operations that do not need immediate responses, such as logging, analytics, or post-call processing, use Webhooks instead.

​
Example Flow

Customer: "What's the status of my order?"

Agent: (collects order number from customer)

[Agent calls API]
-> GET https://api.company.com/orders/12345
<- { "status": "shipped", "tracking": "1Z999AA10123456789" }

Agent: "Your order has shipped! Your tracking number is
       1Z999AA10123456789 and it should arrive by Friday."
Security: Verify customer identity before exposing sensitive data. Always authenticate customers before calling APIs that return personal information, order details, or account data.

​
Create a Custom API Action

1

Navigate to Tools

Go to your agent editor, then Tools tab > Add > Custom Action.
2

Configure basic info

  • Name: Descriptive name (e.g., “Lookup Order Status”)
  • Description: When to use this tool (10-200 characters). This helps the AI decide when to invoke it.
3

Configure the endpoint

Select the HTTP method and enter the endpoint URL. See Endpoint Configuration below.
4

Set up authentication

Choose an authentication method. See Authentication Methods below.
5

Add headers and body

Configure custom headers, query parameters, and the request body on the Parameters tab.
6

Define variables

Add variables the agent should collect from the conversation. See Variables below.
7

Test the tool

Save and test the action through Test Agent using a Web call, Phone call, or Chat session.

​
Endpoint Configuration

​
HTTP Method

MethodUse Case
GETRetrieve data (order status, customer info)
POSTCreate records (tickets, leads, orders)
PUTReplace entire records
PATCHUpdate specific fields
DELETERemove records

​
Endpoint URL

Enter the full API URL. The platform auto-prepends https:// if you omit the protocol. 
https://api.company.com/customers
The endpoint URL itself is static. Use query parameters or the JSON request body for {{variable_name}} substitutions.

​
Authentication Methods

No authentication required. Use for public APIs or internal endpoints on private networks.
Most common for modern APIs. Sends Authorization: Bearer {your_token} header.Use for: OAuth 2.0 access tokens, JWT authentication, modern REST APIs.
Username/password authentication. Sends Authorization: Basic {base64(username:password)} header.Use for: Legacy APIs, simple authentication schemes.
Custom header-based auth (e.g., X-API-Key: {your_api_key}).Use for: API key authentication, custom auth schemes.
Credentials sent in the request body (e.g., {"api_key": "{your_key}"}).Use for: Non-standard auth schemes, login endpoints.
For Bearer, Basic password, Header value, and Body value authentication, select or create a saved credential from Secrets. Existing credentials are preserved when editing; select a new credential only when you want to replace them.

​
Parameters Configuration

Expert Mode

​
Headers

Add custom HTTP headers as key-value pairs. Example: Content-Type: application/json

​
Query Parameters (GET requests)

Add URL query parameters as key-value pairs. Template variables are supported in query parameter values. Example: 
order_id={{order_id}}
include=tracking

​
Request Body (POST/PUT/PATCH)

Write your JSON request body in the editor. Use {{variable_name}} syntax to insert values collected from the conversation. 
{
  "customer_id": "{{customer_id}}",
  "status": "contacted",
  "timestamp": "{{current_datetime}}"
}

​
Variables - Parameter Mapping from Conversation Context

Expert Mode Variables define what information your agent needs to collect from the conversation before calling the API. Each variable tells the AI what information to collect from the caller before making the request.

​
Variable Fields

FieldDescription
NameVariable name (e.g., order_number, customer_email)
TypeData type: string, integer, float, boolean, date, email, phone
DescriptionWhat this variable is for (helps the AI understand when to collect it)
ExampleExample value (guides the AI on expected format)
RequiredIf true, the AI must collect this before calling the API
Default ValueUsed if not required and not provided by the customer

​
Example Variable

Name: order_number
Type: string
Description: Customer's order number, usually starts with ORD-
Example: ORD-12345
Required: Yes
The AI knows to ask the customer for their order number before making the request.

​
Runtime Variables

Custom Action templates use flat {{variable_name}} placeholders in headers, query parameters, and the request body. These runtime values are available when present: 
{{agent_number}}
{{agent_uuid}}
{{contact_number}}
{{direction}}
{{medium}}
{{current_datetime}}
{{timezone}}
Values returned by Dynamic Context are also available by their top-level key, such as {{account_id}} or {{cal_email}}.
Dotted prompt variables such as {{contact.email}} are for prompt rendering, not Custom Action payload substitution. If the action needs a caller name or email, define a variable for the agent to collect or return a flat key from Dynamic Context.

​
Testing Tools

1

Test endpoint independently

Use Postman or cURL to verify the endpoint is reachable, authentication works, and the request format is correct.
2

Start with static values

Configure the action with hardcoded values first (no variables) to verify basic functionality.
3

Add variables

Replace hardcoded values with flat template variables such as {{order_id}}.
4

Test in agent

Start Test Agent and run a Web call, Phone call, or Chat session. Trigger the action through conversation and verify:
  • Agent collects variables correctly
  • API is called with correct data
  • Agent uses the response appropriately
5

Test error scenarios

Verify agent behavior when the API returns errors:
  • 404 (not found)
  • 401 (authentication failed)
  • 500 (server error)
  • Timeout

​
Error Handling

Configure your agent prompt to handle API errors gracefully: 
When using the 'Lookup Order Status' tool:

If the tool returns an error:
- 404: "I don't see an order with that number. Could you double-check?"
- 500: "I'm having trouble accessing the system right now."
- Timeout: "The system is taking longer than expected."
- For any error, offer to have someone call them back.

​
Troubleshooting

Cause: Invalid credentials or wrong auth type.Solution: Verify credentials are correct, check auth type matches API requirements, test with Postman using the same credentials, verify token has not expired.
Cause: Incorrect URL or resource does not exist.Solution: Verify the static endpoint URL, check that query parameters or body variables populate correctly, and test with static values first.
Cause: Variables not configured or descriptions are unclear.Solution: Verify variables are defined in the Variables tab, add clear descriptions and examples, set required=true for essential variables, reference the tool by exact name in your prompt.
Cause: Incorrect syntax or variable does not exist.Solution: Use exact syntax {{variable_name}}, verify the variable is defined, and avoid dotted placeholders such as {{contact.email}} in Custom Action request templates.
Cause: API responding too slowly.Solution: Optimize API response time, consider using webhooks for slow operations, cache frequently accessed data.

​
Security Best Practices

  • Use HTTPS only for all API endpoints
  • Secure credentials - never hardcode in URLs, rotate keys regularly
  • Limit permissions - use read-only keys for lookup actions
  • Validate inputs - your API should check for injection attempts and validate data types
  • Verify identity - authenticate customers before exposing sensitive data

​
Real-World Examples

  • Method: GET
  • URL: https://api.salesforce.com/customers
  • Auth: Bearer token
  • Variable: customer_id (string, required)
  • Query parameter: customer_id={{customer_id}}
  • Method: POST
  • URL: https://company.zendesk.com/api/v2/tickets
  • Auth: Basic (email/token)
  • Variables: issue_description (string), priority_level (string)
  • Body:
{
  "ticket": {
    "subject": "Call with {{caller_name}}",
    "description": "{{issue_description}}",
    "priority": "{{priority_level}}"
  }
}
  • Method: GET
  • URL: https://inventory.company.com/products/availability
  • Auth: Header (X-API-Key)
  • Variable: sku (string, required, example: “PROD-12345”)
  • Query parameter: sku={{sku}}

​
Next Steps

Tools Overview

Learn about all tool types

Custom Action Troubleshooting

Diagnose auth, payload, timeout, and response issues

Booking Tools

Set up Cal.com appointment scheduling

Conversation Data Flow

Understand where variables come from and what happens after tool execution

Template Syntax

Master template variables

MCP Servers

Connect MCP servers for advanced integrations