# Retell

Connect your Retell AI agents to KrosAI phone numbers for emerging market coverage.

## Overview

Retell AI provides voice agents with natural conversation capabilities. KrosAI enables routing calls from African and Middle Eastern phone numbers to Retell agents.

## Prerequisites

* KrosAI account with verified KYC
* Retell account with an agent created
* At least one KrosAI phone number

## Setup Steps

{% stepper %}
{% step %}

### Get Your Retell Agent ID

* Log into your [Retell Dashboard](https://dashboard.retellai.com/)
* Navigate to **Agents**
* Select your agent
* Copy the **Agent ID**
  {% endstep %}

{% step %}

### Connect Retell in KrosAI

* Go to **Settings → Integrations** in your KrosAI Dashboard
* Click **Connect** next to Retell
* Enter your Retell API Key
* Click **Save & Test**
  {% endstep %}

{% step %}

### Create a Retell Endpoint

{% code title="Create endpoint (curl)" %}

```bash
curl -X POST "https://api.krosai.com/v1/endpoints" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retell Booking Agent",
    "type": "agent",
    "url": "sip:agent@retell.ai",
    "provider_config": {
      "provider": "retell",
      "agent_id": "your-retell-agent-id"
    }
  }'
```

{% endcode %}
{% endstep %}

{% step %}

### Attach to Phone Number

{% code title="Attach endpoint to phone number (curl)" %}

```bash
curl -X PATCH "https://api.krosai.com/v1/phone-numbers/pn_abc123" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "ep_retell_xyz"
  }'
```

{% endcode %}
{% endstep %}
{% endstepper %}

## Configuration Options

### Provider Config Fields

| Field                 | Required | Description                                 |
| --------------------- | -------- | ------------------------------------------- |
| `agent_id`            | Yes      | Your Retell agent ID                        |
| `retell_phone_number` | No       | Retell phone number for outbound (optional) |

## Outbound Calls

{% code title="Initiate outbound call (curl)" %}

```bash
curl -X POST "https://api.krosai.com/v1/outbound-calls" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+2348012345678",
    "to_number": "+14155551234",
    "endpoint_id": "ep_retell_xyz",
    "metadata": {
      "appointment_id": "apt_123"
    }
  }'
```

{% endcode %}

## Dynamic Variables

Pass dynamic data to your Retell agent:

{% code title="Outbound call with dynamic variables (curl)" %}

```bash
curl -X POST "https://api.krosai.com/v1/outbound-calls" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+2348012345678",
    "to_number": "+14155551234",
    "endpoint_id": "ep_retell_xyz",
    "metadata": {
      "retell_dynamic_variables": {
        "customer_name": "John Smith",
        "appointment_time": "2:00 PM",
        "location": "Lagos Office"
      }
    }
  }'
```

{% endcode %}

## Webhooks

Receive call events including Retell-specific data:

```json
{
  "event": "call.completed",
  "call_id": "call_abc123",
  "direction": "outbound",
  "from_number": "+2348012345678",
  "to_number": "+14155551234",
  "duration": 245,
  "provider": "retell",
  "agent_id": "agent_123",
  "transcript": "[Agent]: Hello! I'm calling to confirm your appointment...",
  "call_analysis": {
    "sentiment": "positive",
    "outcome": "confirmed"
  }
}
```

## Troubleshooting

<details>

<summary>Call Not Connecting</summary>

* Verify your Retell API key is valid
* Check the agent ID exists in Retell
* Ensure your Retell account has sufficient credits
* Review call events in the KrosAI Dashboard

</details>

<details>

<summary>Audio Quality Issues</summary>

* Check network connectivity
* Review Retell's voice settings
* Verify audio codec compatibility (Opus recommended)

</details>

<details>

<summary>Agent Not Following Script</summary>

* Test the agent directly in Retell
* Check your prompt configuration
* Verify custom LLM settings

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/integration/retell.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.