Skip to main content

​
Overview

The Retell AI 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

1

Get your Retell API key

In the Retell dashboard, open Settings → API Keys and copy your key.
2

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.
3

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.
4

(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:
The per-org token is generated when you connect. See Inbound call events below.

​
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:
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

  • Confirm the API key was copied exactly and that it’s an active key in the Retell dashboard.
  • 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).
  • 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.
  • Run Code — process large Retell result sets (the spillover attachment) with pandas.
  • Send Email — follow up on a call by emailing a summary.