Retell AI

Retell AI

This connector works with one Retell AI workspace through the Retell API (https://api.retellai.com): voice and chat agents with their versions, Retell LLM response engines and conversation flows, calls (history, transcripts, recordings, analysis and costs, outbound calls, hanging up, batch calls), phone numbers and their agents, voices, knowledge bases, chats and SMS, contacts and the concurrency limit.

Setup (2 minutes)

1. Sign in at https://dashboard.retellai.com and open Settings, API Keys.
2. Create or copy an API key (it starts with key_) and paste it into RETELL_API_KEY. It is sent as Authorization: Bearer <key> and works for the whole workspace.
3. Run retell_ai_get_concurrency to check the key; retell_ai_get_api_key_info names the workspace.

Calls and texts cost money and reach real people: retell_ai_create_phone_call, retell_ai_create_batch_call and retell_ai_create_sms_chat contact real phone numbers and are billed per minute or message. Calling or texting people without consent can break telemarketing laws (TCPA in the US and similar rules elsewhere). Show the user who is contacted, from which number, by which agent and with which variables, and act only after a clear yes. retell_ai_create_batch_call installs switched off; an admin enables it on purpose. retell_ai_stop_call cuts off a live call. retell_ai_update_agent, retell_ai_publish_agent_version, retell_ai_update_retell_llm and retell_ai_update_phone_number change how real calls are handled; confirm them too.

Workflow

• Agents: retell_ai_list_agents, retell_ai_get_agent (its response_engine names the LLM or flow), retell_ai_list_agent_versions. Edit the draft with retell_ai_update_agent, then go live with retell_ai_publish_agent_version.
• Prompts and tools: retell_ai_list_retell_llms, retell_ai_get_retell_llm, retell_ai_update_retell_llm; node-based agents: retell_ai_list_conversation_flows, retell_ai_get_conversation_flow.
• Call history: retell_ai_list_calls with filter_criteria (agent, status, direction, number, time range, sentiment, batch), then retell_ai_get_call for the transcript, recording_url, call_analysis and call_cost.
• Outbound: pick a number with retell_ai_list_phone_numbers / retell_ai_get_phone_number, check room with retell_ai_get_concurrency, then retell_ai_create_phone_call; follow it with retell_ai_get_call and hang up with retell_ai_stop_call if needed. Many calls at once: retell_ai_create_batch_call.
• Routing: retell_ai_update_phone_number binds inbound and outbound agents to a number.
• Voices: retell_ai_list_voices, retell_ai_get_voice. Knowledge: retell_ai_list_knowledge_bases, retell_ai_get_knowledge_base.
• Text: retell_ai_list_chats, retell_ai_get_chat, retell_ai_create_sms_chat.
• Contacts: retell_ai_list_contacts (search_query), retell_ai_get_contact_by_phone.

Reading the answers: timestamps (start_timestamp, end_timestamp, last_modification_timestamp, trigger_timestamp) are Unix epoch milliseconds; duration_ms is milliseconds. In call_cost, combined_cost and the product costs are in US cents. Phone numbers are E.164 (+14155550123). call_status is registered, not_connected, ongoing, ended or error; disconnection_reason says why a call ended (user_hangup, agent_hangup, voicemail_reached, dial_no_answer, concurrency_limit_reached, ...). call_analysis holds call_summary, user_sentiment, call_successful and your custom_analysis_data.

Filters for lists (filter_criteria): each field takes a typed filter. Enum: {"type": "enum", "op": "in", "value": ["ended"]}; string: {"type": "string", "op": "eq", "value": "+14155550123"} (ops eq, ne, sw, ew, co); number: {"type": "number", "op": "ge", "value": 60000}; range: {"type": "range", "op": "bt", "value": [from_ms, to_ms]}; agents: {"agent": [{"agent_id": "agent_..."}]}.

Paging: list answers carry items, has_more and pagination_key; pass the key back as pagination_key until has_more is false. retell_ai_list_voices and retell_ai_list_knowledge_bases return everything at once.

Errors: 401 a wrong or deleted key; 400 names the invalid field (often a number not in E.164, or a Retell-bought number calling outside the US); 402 the workspace has no credit; 404 an unknown id; 422 a request the agent setup cannot serve; 429 the concurrency or rate limit is reached (see retell_ai_get_concurrency).