> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retell AI (Voice & Chat Agents)

> Connect Retell AI so your Agents can place outbound calls, read transcripts and analysis, and manage Retell voice agents

## Overview

The [Retell AI](https://www.retellai.com) integration lets your agents drive Retell's voice platform: **place outbound phone calls**, **retrieve call transcripts and post-call analysis** (summary, sentiment, success, extracted data), **list and filter calls**, and **manage the Retell voice agents and LLM configs** behind them. An optional inbound webhook lets a completed Retell call hand its transcript and analysis to an Aster agent so it can act on the result.

Your organization's Retell API key is injected automatically into every tool call — agents never see or handle the key.

## Prerequisites

* A **Retell AI** account with API access
* A Retell **API key** (Retell dashboard → Settings → API Keys)
* An Aster **admin** to connect the integration (the connection is shared org-wide)
* For outbound calls: at least one **phone number** in your Retell account with an outbound agent bound to it

## Setup Guide

<Steps>
  <Step title="Get your Retell API key">
    In the [Retell dashboard](https://dashboard.retellai.com), open **Settings → API Keys** and copy your key.
  </Step>

  <Step title="Connect Retell in Aster Agents">
    Navigate to **Control Hub → Integrations**, locate the **Retell AI** card, click **Connect**, and paste your API key. Aster validates it against Retell (`GET /list-agents`) and stores it securely for your organization.
  </Step>

  <Step title="Add the Retell tools to your agent">
    Edit your agent and enable the Retell tools you need — **Retell: Manage Calls**, **Retell: Manage Agents & Config**, and/or **Retell: Raw API Call**.
  </Step>

  <Step title="(Optional) Route completed calls back into an agent">
    To have a finished call notify an Aster agent, subscribe your Retell agent to the **`call_analyzed`** webhook event and set the webhook URL to:

    ```
    https://www.asteragents.com/api/integrations/retell/webhook?token=<your-org-webhook-token>
    ```

    The per-org `token` is generated when you connect. See **Inbound call events** below.
  </Step>
</Steps>

## Available Tools

Three tools cover the whole surface, following Aster's consolidation pattern (few tools, discriminated by an `action`/`resource` parameter).

* **Retell: Manage Calls** (`retell_manage_calls`) — the call runtime.
  * `create_phone_call` — place a live outbound call (`from_number`, `to_number` in E.164; optional `override_agent_id`, `dynamic_variables`, `metadata`).
  * `get` — retrieve one call's transcript, `call_analysis`, and cost by `call_id`.
  * `list` — recent calls with optional `filter_criteria` (agent, status, direction, time range).
* **Retell: Manage Agents & Config** (`retell_manage_resources`) — the config surface, as a `resource` × `action` grid.
  * `resource`: `agent`, `llm`, `phone_number`, `voice`.
  * `action`: `list`, `get`, `create`, `update` (agents and LLMs support all four; phone numbers and voices are `list`/`get` only).
  * `delete` is intentionally not offered here — use the raw tool if you truly need destructive operations.
* **Retell: Raw API Call** (`retell_api_call`) — an escape hatch to any Retell REST endpoint (`method` + `endpoint` + optional `body`) for the long tail: knowledge bases, batch calls, versioning, purchasing numbers, deletes.

Large responses (long transcripts, big call lists) spill to a `.json`/`.csv` attachment while the inline payload stays within a token budget, so big pulls don't balloon the agent's context — process the file in `execute_python`.

## Placing a call, personalized

Pass `dynamic_variables` to interpolate values into the agent's prompt, and `metadata` to tag the call:

```
retell_manage_calls(
  action="create_phone_call",
  from_number="+14157774444",
  to_number="+12137774445",
  dynamic_variables={ "name": "John", "appointment": "Tuesday 3pm" },
  metadata={ "aster_agent_id": 512, "lead_id": "abc123" }
)
```

Including `aster_agent_id` in `metadata` makes the completion webhook route back to that specific Aster agent (see below).

## Inbound call events

When a call finishes and Retell has analyzed it, Retell POSTs a `call_analyzed` event to your webhook URL. Aster:

1. Identifies your org from the `token` in the URL.
2. Verifies the request's HMAC-SHA256 signature (`x-retell-signature`) with your Retell API key.
3. Routes the transcript + analysis to an Aster agent as a new conversation.

**Which agent receives it:** `call.metadata.aster_agent_id` if present (set it when your agent placed the call), otherwise the org-level default `event_agent_id` on the connection. If neither is set, the event is acknowledged and dropped.

## Example Prompts

Once connected, agents can:

* "Call +1 213 777 4445 with our appointment-reminder agent and tell them their slot is Tuesday at 3pm."
* "Pull the transcript and summary for call `call_abc123` and tell me whether they agreed to a follow-up."
* "List all outbound calls from the last 24 hours that ended unsuccessfully."
* "Create a new Retell LLM with this prompt, then a voice agent that uses it."

## Notes & Limitations

* **Costs real money** — outbound calls and Retell usage are billed by Retell. Grant `retell_manage_calls` only to agents that should place calls.
* **Numbers must be E.164** (e.g. `+14157774444`) and belong to your Retell account.
* **`delete` is not in the dedicated tools** — destructive operations require the raw `retell_api_call` tool.
* **Webhook subscribes to `call_analyzed`** — the richest event, fired after post-call analysis completes; enable analysis on the Retell agent for it to fire.

## Security Considerations

* **Org-level connection** — one admin connects once for the whole organization. The API key is stored server-side and redacted when the connection is read back in the UI.
* **Signed webhooks** — inbound events are rejected unless the HMAC signature matches your org's key.
* **Grant Retell tools only to agents that need them**, especially the call and raw-API tools.
* **Rotate the key** periodically and reconnect (your webhook token is preserved across reconnects).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection rejected on setup">
    * Confirm the API key was copied exactly and that it's an active key in the Retell dashboard.
  </Accordion>

  <Accordion title="create_phone_call fails">
    * `from_number` must be a Retell-managed number in your account, with an outbound agent bound to it (or pass `override_agent_id`).
    * Both numbers must be E.164 (`+` and country code, digits only).
  </Accordion>

  <Accordion title="Completed calls aren't reaching my agent">
    * Confirm the Retell agent is subscribed to the **`call_analyzed`** event and the webhook URL includes your `?token=...`.
    * Make sure a target agent is resolvable — either set `metadata.aster_agent_id` when placing the call, or configure a default `event_agent_id` on the connection.
    * A `401 Invalid signature` in logs means the webhook is hitting a different org's key than the one that signed it; reconnect to refresh.
  </Accordion>
</AccordionGroup>

## Related Tools

* [Run Code](/tools/execute_python) — process large Retell result sets (the spillover attachment) with pandas.
* [Send Email](/tools/send_email) — follow up on a call by emailing a summary.