---
name: retellai
description: Use when building, testing, deploying, and monitoring AI voice and chat agents. Reach for this skill when agents need to create phone agents, configure conversation flows, set up function calling and integrations, manage telephony, test agents, deploy to phone numbers, monitor call analytics, or work with webhooks and post-call analysis.
metadata:
    mintlify-proj: retellai
    version: "1.0"
---

# Retell AI Skill

## Product summary

Retell AI is a platform for building, testing, deploying, and monitoring AI voice and chat agents that handle phone calls and text conversations. Agents use it to create agents via the dashboard or API, configure speech recognition (ASR), LLM responses, voice synthesis (TTS), and telephony features. Key resources: **Dashboard** at https://dashboard.retellai.com, **API Reference** at `/api-references/overview`, **SDKs** (Node.js, Python) at `/get-started/sdk`, **MCP server** for Claude/Cursor at `/get-started/mcp-server`. Core files: agent configuration (prompt or conversation flow), knowledge base sources, webhook endpoints, dynamic variables. CLI available at `/get-started/cli`.

## When to use

Use this skill when:
- **Building agents**: Creating single-prompt or conversation-flow agents, configuring prompts, adding function calling, setting up integrations (CRM, helpdesk, calendar)
- **Testing**: Running LLM Playground tests, simulation testing with graded test cases, batch testing, or phone/web call testing
- **Deploying**: Purchasing phone numbers, connecting custom telephony via SIP, setting up inbound/outbound call routing, deploying web calls or chat widgets
- **Monitoring**: Setting up webhooks for call events, configuring post-call analysis and extraction, building analytics dashboards, running AI QA on production calls
- **Integrations**: Connecting HubSpot, Salesforce, Zendesk, Calendly, Google Drive, OneDrive, Notion, or other providers; configuring pre-call and post-call workflows
- **Voice/chat configuration**: Selecting voices, configuring TTS providers, setting up knowledge bases, managing dynamic variables, handling DTMF and voicemail

## Quick reference

### Agent types

| Type | Best for | Response engine |
|------|----------|-----------------|
| **Single Prompt** | Simple, linear conversations; quick iteration | One comprehensive prompt |
| **Conversation Flow** | Structured, multi-step, high-stakes calls; deterministic behavior | Node-based flow with explicit transitions |
| **Chat Agent** | Text-only conversations via API, widget, or SMS | Same response engines as voice agents |

### Core API endpoints

| Task | Endpoint | Method |
|------|----------|--------|
| Create agent | `/create-agent` | POST |
| Update agent | `/update-agent/{agent_id}` | PATCH |
| Publish agent | `/publish-agent/{agent_id}` | POST |
| Create phone call | `/create-phone-call` | POST |
| Create web call | `/create-web-call` | POST |
| Get call | `/get-call/{call_id}` | GET |
| List calls | `/list-calls` | GET |
| Create phone number | `/create-phone-number` | POST |
| Create knowledge base | `/create-knowledge-base` | POST |
| Create conversation flow | `/create-conversation-flow` | POST |

### Key configuration fields

| Field | Purpose | Example |
|-------|---------|---------|
| `response_engine` | Specifies how agent generates responses (retell-llm, custom-llm, or conversation-flow) | `{"type": "retell-llm", "llm_id": "..."}` |
| `language` | Agent's language(s); single locale or array for multilingual | `"en-US"` or `["en-US", "es-ES"]` |
| `voice_id` | Voice for TTS synthesis | Platform voice ID or custom voice |
| `webhook_url` | Endpoint for call/chat events | `https://example.com/webhook` |
| `knowledge_base_ids` | Knowledge bases for RAG retrieval | Array of KB IDs |
| `dynamic_variables` | Per-call context injected into prompt | `{"customer_name": "John", "account_id": "123"}` |

### Testing methods

| Method | Use case | Grades results | Requires phone |
|--------|----------|---|---|
| **LLM Playground** | Quick iteration, inspect tool calls | No | No |
| **Simulation Testing** | Graded test cases, regression suite | Yes | No |
| **Web Call** | Real audio, latency, interruptions | No | No |
| **Phone Call** | Full telephony features, DTMF, transfers | No | Yes |

### Webhook events

| Event | Fired when | Includes |
|-------|-----------|----------|
| `call_started` | Call connects | Call metadata, agent ID |
| `call_ended` | Call disconnects | Duration, disconnection reason |
| `call_analyzed` | Post-call analysis completes | Summary, sentiment, custom fields |
| `chat_started` | Chat begins | Chat metadata |
| `chat_ended` | Chat closes | Duration, status |
| `chat_analyzed` | Post-chat analysis completes | Summary, sentiment, custom fields |

## Decision guidance

### When to use Single Prompt vs Conversation Flow

| Scenario | Single Prompt | Conversation Flow |
|----------|---|---|
| Simple, linear conversation | ✓ | |
| Structured, multi-step flow | | ✓ |
| Deterministic behavior required | | ✓ |
| Quick prototyping | ✓ | |
| High-stakes calls (support, sales) | | ✓ |
| Complex branching logic | | ✓ |
| Few functions needed | ✓ | |
| Many conditional transitions | | ✓ |

### When to use custom function vs integration tool

| Scenario | Custom Function | Integration Tool |
|----------|---|---|
| Call your own API | ✓ | |
| CRM, helpdesk, calendar action | | ✓ |
| No server to host | | ✓ |
| Custom business logic | ✓ | |
| HubSpot, Salesforce, Zendesk, Calendly | | ✓ |
| Compliance: process in your infrastructure | ✓ | |

### When to use pre-call vs in-conversation function

| Scenario | Pre-call | In-conversation |
|----------|----------|---|
| Agent needs fact before speaking | ✓ | |
| Agent needs result while talking | | ✓ |
| Look up caller by phone number | ✓ | |
| Check calendar availability | | ✓ |
| Load account state | ✓ | |
| Create ticket during call | | ✓ |

## Workflow

### Build and deploy a basic agent

1. **Create the agent**
   - Go to Dashboard → Agents → Create Agent
   - Choose agent type: Single Prompt (simple) or Conversation Flow (structured)
   - Pick a template or build from scratch
   - Write the prompt or design the flow

2. **Configure core settings**
   - Set language (default: en-US)
   - Pick voice and TTS provider
   - Attach knowledge base if needed
   - Set up dynamic variables for per-call context

3. **Add functions**
   - For single-prompt: Add custom functions or integration tools in the Functions panel
   - For conversation flow: Add function nodes, custom functions, or integration tools
   - Configure inputs (fixed values or LLM-filled descriptions) and outputs (map to dynamic variables)

4. **Test the agent**
   - Click Test → Web Call to test with audio (no phone number needed)
   - Use LLM Playground for quick text iteration
   - Run simulation testing with graded test cases to catch regressions
   - Check tool calls, transitions, and responses

5. **Deploy to phone**
   - Go to Phone Numbers → Buy New Number (US/Canada only)
   - Add payment method if needed
   - Assign agent as Inbound Agent and/or Outbound Agent
   - Test by calling the number or making an outbound call

6. **Monitor and iterate**
   - Set up webhooks to receive call events
   - View call history and transcripts in Session History
   - Check analytics dashboard for patterns across calls
   - Run AI QA on production calls to score quality

### Set up pre-call and post-call functions

1. **Open Workflow page** in agent editor
2. **Add pre-call function** (runs before agent speaks)
   - Click + Add on Pre-call functions node
   - Pick integration tool, custom function, or code
   - Configure inputs (fixed values or LLM-filled)
   - Map outputs to dynamic variables (e.g., `{{customer_name}}`)
3. **Chain functions** if needed
   - Click + on a function row → Add sequential function (waits for previous)
   - Or Add parallel function (runs alongside)
4. **Add post-call function** (runs after call ends)
   - Click + Add on Post-call functions node
   - Gate on conditions (e.g., only if `{{call_successful}}` = true)
   - Map response fields to dynamic variables
5. **Test** with Run a test button before saving

### Create and attach a knowledge base

1. **Create knowledge base**
   - Dashboard → Knowledge Base → Add
   - Choose source: URL, file, text, Google Drive, OneDrive, or Notion
   - Configure auto-refresh if using URLs or connected files
2. **Attach to agent**
   - Open agent editor → Knowledge Base section
   - Select knowledge base items
   - Adjust retrieval: chunks (1-10, default 3) and similarity threshold (default 0.6)
3. **Optional: Set KB instruction**
   - Advanced Settings → Configure Knowledge Base Instruction
   - Guide the search query (e.g., "focus on pricing and features")
4. **Test retrieval**
   - Run a web call or simulation test
   - Check that relevant chunks are retrieved

## Common gotchas

- **Forgetting to publish before deploying**: Draft agents can be tested but not assigned to phone numbers. Publish from the version panel or call `publish-agent` API.
- **Pre-call functions delay inbound calls**: Inbound and web calls wait up to 1 minute for pre-call functions; outbound calls wait 5 minutes before dialing. Keep chains shallow (parallel > sequential) to minimize latency.
- **Dynamic variables not available**: Variables are only available to functions that run *after* they're set. A function can't use output from a function running beside it or after it.
- **Knowledge base chunks not retrieved**: Increase `top_k` (chunks to retrieve) and lower `filter_score` (similarity threshold) if relevant chunks are missed. Start with 3 chunks and 0.6 threshold.
- **Webhook signature not verified**: Always verify the `X-Retell-Signature` header (HMAC-SHA256) before trusting the payload in production.
- **Post-call analysis fields are null**: Listen to `call_analyzed` event, not `call_ended`. The `call_analyzed` event includes `call_summary`, `user_sentiment`, `call_successful`, and custom fields.
- **Integration tool not appearing**: Connect the provider first on the Integrations page (workspace-level step). Then the tool appears in the function menu.
- **Conversation flow agent can't use custom LLM**: Conversation flows only support Retell's LLM or custom LLM via websocket. For custom LLM, use a single-prompt agent instead.
- **Simulation testing not available for custom LLM**: Only Retell-managed LLM agents support simulation testing. Custom LLM agents can only be tested via web or phone calls.
- **Language set to deprecated "multi"**: The scalar value `"multi"` is deprecated. Send an explicit array like `["en-US", "es-ES"]` instead.

## Verification checklist

Before submitting work with a Retell agent:

- [ ] Agent is published (not in draft state)
- [ ] Prompt or flow is tested in LLM Playground or web call
- [ ] Simulation test cases pass (if using conversation flow or single-prompt)
- [ ] All function inputs are configured (fixed values or LLM-filled descriptions)
- [ ] Function outputs are mapped to dynamic variables if downstream functions need them
- [ ] Knowledge base is attached and retrieval is tested (if using KB)
- [ ] Webhook URL is registered and signature verification is in place (if using webhooks)
- [ ] Phone number is assigned to the agent (inbound_agent_id and/or outbound_agent_id)
- [ ] Voice and language are set correctly
- [ ] Post-call analysis fields are defined if custom extraction is needed
- [ ] Pre-call functions don't exceed 1 minute (inbound) or 5 minutes (outbound) latency budget
- [ ] Dynamic variables used in prompts are actually set by functions or passed in the API call

## Resources

**Comprehensive navigation**: See `/llms.txt` for a page-by-page listing of all documentation.

**Critical pages**:
- [Build overview](/build/overview) — Configure agent type, speech recognition, LLM, voice, and telephony
- [API Reference](/api-references/overview) — Manage agents, calls, numbers, and knowledge bases programmatically
- [Agent workflow](/agent/agent-workflow) — Set up pre-call and post-call functions, dynamic variables, and conditions

---

> For additional documentation and navigation, see: https://docs.retellai.com/llms.txt