Skip to main content

API Call Actions

API call actions let your agent fetch data or perform operations in your external systems during a conversation — for example, looking up order details, checking account balances, or creating support tickets.

Name and description​

  • Name: A clear, descriptive identifier (e.g., get_order_status, create_support_ticket). Names can only contain letters, numbers, underscores, and hyphens.
  • Description: Explain what this action does and when the agent should use it.

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

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.

API connection (optional)​

Select an API connection to reuse a shared base URL, auth connector, and headers across multiple actions. When an API connection is selected, the URL field becomes a Path field — enter just the path portion (e.g., /orders), and it is appended to the API connection's base URL at runtime.

If you don't use an API connection, configure the full URL, auth, and headers directly on the action.

URL​

The full URL of your API endpoint (or the path, if using an API connection).

GET request:

https://api.yourcompany.com/orders

POST request:

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:

MethodUse for
GETRetrieve information
POSTCreate new records or submit data
PUTUpdate existing records completely
PATCHUpdate specific fields
DELETERemove records

Headers​

Add HTTP headers your API requires. Two types are supported:

Static value headers — For non-sensitive values like content types:

  • Content-Type: application/json
  • X-API-Version: 1.0

Secret reference headers — For sensitive values like API keys and tokens. Select an existing secret instead of hardcoding the value. The secret is resolved at request time and never exposed in logs.

Managing secrets

Create secrets in Manage > Secrets first, then select them when configuring headers. Secrets are stored securely, can be reused across multiple actions, and support per-environment values so you can use different API keys for development, staging, and production.

Authentication connectors​

For common authentication patterns, use an auth connector instead of manually configuring headers. Auth connectors handle credential management automatically and support token refresh for OAuth flows.

Auth connectors are managed in Manage > Auth connectors and selected when configuring your action. Each auth connector supports per-environment configuration, so the correct credentials are automatically resolved based on the environment of the conversation.

Bearer token — Adds an Authorization: Bearer <token> header to each request.

API key — Sends an API key via header, query parameter, or cookie.

LocationResult
HeaderX-API-Key: your-key
Query?api_key=your-key
Cookieapi_key=your-key

OAuth 2.0 Client Credentials — Automatically fetches and refreshes access tokens using the OAuth 2.0 client credentials flow. Tokens are cached and refreshed when they expire. This is the recommended approach for service-to-service authentication.

Basic authentication — Adds an Authorization: Basic <credentials> header using username and password.

ScenarioRecommendation
Standard auth patterns (Bearer, API key, Basic, OAuth2)Use auth connector
Custom header names or formatsUse secret-based headers
Multiple auth headers neededCombine auth connector with headers

Parameters schema​

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

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. Parameters not in the required array are optional.

Write detailed parameter descriptions

The agent uses parameter descriptions to understand what information to collect and how to ask for it. Be specific about the parameter's purpose, expected format, and provide examples where helpful. Clear descriptions lead to better data collection.

Advanced parameter examples

Nested objects for structured data:

{
  "type": "object",
  "properties": {
    "customer": {
      "type": "object",
      "description": "Customer information",
      "properties": {
        "name": { "type": "string", "description": "Customer's full name" },
        "email": { "type": "string", "description": "Customer's email address" }
      },
      "required": ["name", "email"]
    }
  }
}

Arrays for lists of items:

{
  "type": "object",
  "properties": {
    "order_numbers": {
      "type": "array",
      "description": "List of order numbers to check",
      "items": { "type": "string" }
    }
  }
}

Enumerations for fixed sets of values:

{
  "type": "object",
  "properties": {
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "urgent"],
      "description": "Priority level for the ticket"
    }
  }
}

Conditional enumerations for values that depend on another field:

When allowed values for one field depend on the value of another field, use if/then with allOf. This is useful when sub-categories or specific options are only valid for certain main categories.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical"],
      "description": "Main issue category"
    },
    "sub_category": {
      "type": "string",
      "description": "Specific issue type within the category"
    }
  },
  "required": ["category", "sub_category"],
  "allOf": [
    {
      "if": {
        "properties": { "category": { "const": "billing" } }
      },
      "then": {
        "properties": {
          "sub_category": { "enum": ["invoice_dispute", "payment_failed", "refund_request"] }
        }
      }
    },
    {
      "if": {
        "properties": { "category": { "const": "technical" } }
      },
      "then": {
        "properties": {
          "sub_category": { "enum": ["login_issue", "performance", "bug_report"] }
        }
      }
    }
  ]
}

When category is "billing", the agent will only accept sub_category values of "invoice_dispute", "payment_failed", or "refund_request". When category is "technical", only "login_issue", "performance", or "bug_report" are valid.

Request body template​

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 flat JSON object.

Template syntax:

Templates use a subset of Go template syntax. You can test templates using the Go Template Playground.

Accessing data:

  • {{.parameters.parameter_name}} — Parameters from the parameter schema
  • {{.variables.variable_name}} — Conversation variables
  • {{.static_variables.VARIABLE_NAME}} — Variables configured in Studio, filled in at conversation start based on the environment
  • {{index .parameters "key"}} — Map or slice values by key or index

Conditionals and scoping:

  • {{if .parameters.name}} ... {{end}} — Conditional blocks
  • {{if .parameters.name}} ... {{else}} ... {{end}} — Conditional with fallback
  • {{with .parameters.name}} ... {{end}} — Scope rebinding (also supports {{else}})
  • {{$var := .parameters.name}} — Assign a value to a variable

Allowed functions:

FunctionDescription
eqEqual ({{if eq .parameters.status "active"}})
neNot equal
ltLess than
leLess than or equal
gtGreater than
geGreater than or equal
andLogical AND
orLogical OR
notLogical NOT
indexAccess map/slice values ({{index .parameters "key"}})
Unsupported constructs

For security, the following Go template features are not supported:

  • {{range}} (loops)
  • {{template}} (nested template invocation)
  • {{define}} (template definitions)
  • {{block}} (block definitions)
  • Custom function calls beyond the allowed list above

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: Conditional fields

Include fields only when a parameter has a value:

{
  "name": "{{.parameters.name}}",
  {{- if .parameters.email}}
  "email": "{{.parameters.email}}",
  {{- end}}
  "source": "voice_agent"
}

Example: Map access with fallback

Use index with with to safely access nested values:

{{with index .parameters "preferred_name"}}{{.}}{{else}}Customer{{end}}

Without a template (default):

{
  "order_number": "ORD-12345",
  "email": "customer@example.com"
}
When to use request body templates

Use templates when your API requires a specific nested structure, you need to include conversation variables, you want to add static fields alongside dynamic parameters, or your API expects a different field naming convention. For simple APIs that accept flat JSON, leave this blank.

If a referenced parameter or variable is missing, the action returns an error to the agent rather than failing silently. The agent can then ask the user for the missing information.

Response processing​

The agent sees the full API response and can use it immediately in the conversation. For example, if your API returns:

{
  "order_number": "12345",
  "status": "shipped",
  "tracking_number": "TRACK123",
  "estimated_delivery": "2024-03-15"
}

The agent might say: "Your order #12345 has shipped! The tracking number is TRACK123, and it should arrive by March 15th."

Output variables​

Output variables extract specific values from API responses and store them as conversation variables for use in subsequent actions or prompts. This is useful for capturing data like customer IDs or tokens needed by later API calls.

For each output variable, configure:

  • Variable name: The conversation variable name (e.g., customer_id, account.status). Use lowercase letters, numbers, underscores, and dots.
  • JSONPath expression: A JSONPath expression that identifies the value to extract. Must start with $.
  • Sensitive: When enabled, the value is redacted in logs and conversation history.
  • Expose to AI: When enabled, the extracted value is available to the AI assistant in the conversation.

JSONPath examples:

Given an API response {"data": {"id": "cust_123", "email": "user@example.com"}}:

JSONPathExtracted value
$.data.id"cust_123"
$.data.email"user@example.com"
Expose to AI is off by default

When enabled, the assistant can see and speak the extracted value in later turns. Keep it disabled for internal IDs or tokens that should only be used in subsequent API calls — the value will still be available for action parameters, just not visible to the AI.

Next steps​