How to migrate from Retell to ThunderPhone (2026): import agents, tools, and knowledge bases
ThunderPhone can import your Retell agents, tools, and knowledge bases with an API key or a JSON export. It converts supported agent configuration into a review table before anything is created. It does not move phone numbers, recover credentials stored by Retell, or turn every custom engine and tool into a working ThunderPhone connection, so budget time for manual setup and end-to-end testing.
Before you start
Make an inventory of Retell agents and their linked LLM or conversation-flow configurations. Capture general and global prompts, begin messages, starting speakers, states or nodes, tools, transfer rules, languages, voices, knowledge sources, voicemail settings, silence behavior, webhooks, and maximum call durations. List telephone numbers separately and note whether each is a retell-twilio number or custom telephony.
You must be a ThunderPhone admin to run an import. For the API path, use a Retell key scoped to reading the required groups. Retell's Restrict permissions control supports Read-only access per group, so choose read-only wherever it covers the objects in your migration. ThunderPhone encrypts the key only for the import and deletes it when the import completes, fails, or is discarded. The key is never stored with the account.
Mark production agents in your inventory. Names containing test, demo, copy, untitled, sample, or playground start unticked in ThunderPhone's review table. That reduces accidental clutter, but it does not replace checking the list yourself.
Step 1: get your API key
In Retell, go to System Settings → API Keys. Create a key, use Restrict permissions, and set the relevant groups to Read-only where possible. Copy the key into the importer without placing it in tickets, documents, or messages. Retell API key management, accessed 2026-09-10.
A narrowly scoped, temporary key makes the migration easier to audit. After the import and review are complete, revoke it in Retell. If your policies prohibit this workflow, use the JSON path instead.
Step 2: run the import
Open the ThunderPhone dashboard and choose Agents → Import → Retell. Paste the API key, let the importer retrieve the available objects, and inspect the review table before selecting Import.
Each row shows the agent name, closest voice and its confidence (exact, by voice type, or default), assigned intelligence tier (Spark, Bolt, or Storm), tools, knowledge bases, and migration notes. You also choose between two prompt treatments. Rewritten reorganizes the material around the ThunderPhone prompting guide without changing any phone number, URL, tool name, or placeholder. Structured retains the source content and arranges it under headings. The choice is per agent.
Read the report before proceeding. It calls out phone-number ownership, per-agent webhooks, credentials stored by Retell, and unsupported tools. These are explicit handoff items for the person finishing the migration.
What the importer maps
| Retell field | ThunderPhone |
|---|---|
Retell LLM general_prompt, begin_message, start_speaker |
Prompt; opening line; who speaks first |
states + starting_state |
Ordered call procedure in the prompt |
Conversation flow global_prompt + nodes |
Ordered call procedure with transfers and end nodes |
general_tools custom |
API connections |
transfer_call, end_call, press_digit |
Prompt hand-off + built-ins |
voice_id (11labs-, openai-, cartesia-, …) |
Closest catalog voice |
language |
Primary and additional languages |
model / s2s_model |
Intelligence tier |
knowledge_base_ids (url, document, text sources) |
Knowledge base with documents |
voicemail_option, end_call_after_silence_ms, boosted_keywords |
Voicemail setting; silence hang-up; prompt terms |
webhook_url, max_call_duration_ms, custom-LLM engines, send_sms, MCP |
Reported, not imported |
ThunderPhone matches voices into a catalog of 123 voices and 47 languages. Review the confidence label and listen to the selected voice rather than assuming a matching identifier means identical sound. Test the mapped intelligence tier against representative calls and edge cases.
The source maximum-duration value is reported but not applied. ThunderPhone does not impose a per-agent maximum call duration. Configure silence hang-up and write explicit prompt rules for wrapping up, handling stalled calls, and ending once the task is complete.
What needs a manual step
Numbers do not move during import. Retell retell-twilio numbers are platform-owned, so treat them as nonportable from the account. Custom telephony numbers are owned by you or your carrier; reconnect or port those through the relevant telephony setup. Keep the old route active until ownership, inbound routing, outbound identity, and transfer behavior are confirmed.
Recreate webhook_url behavior as an organization webhook or appropriate connection. Re-enter secrets for custom tools because credentials retained by Retell are reported, not copied. Custom-LLM engines, send_sms, and MCP are also reported rather than imported. Decide whether each capability should be represented through a supported API connection, an external service, or a revised call procedure. Do not assume the imported prompt alone reproduces the behavior.
Importing without a key
Choose Agents → Import → Retell → JSON and paste exported agent, Retell LLM, conversation-flow, tool, and knowledge-base objects. This route is appropriate when key use is restricted or when you want a fixed migration snapshot for review.
JSON references can be incomplete. Agent objects may point to an LLM, flow, tools, or knowledge sources only by ID. Without the corresponding definitions, the importer cannot resolve their contents and will report what is missing. Include linked objects in the export where possible. Then compare the resulting notes against the source inventory and manually rebuild anything that remains an unresolved identifier.
After the import
- Open each agent and inspect its prompt choice, opening line, speaker order, procedure, languages, voice confidence, and intelligence tier.
- Read the notes for imported and unticked agents; resolve every item that affects production behavior.
- Make a test call from the builder that covers normal completion, transfers, keypad input, voicemail, silence, and recovery from a failed connection.
- Attach the production number only after the builder call passes, then test the live inbound route and any outbound path.
- Add fresh secrets to every API connection and use its test request to verify the method, URL, headers, query fields, and body.
- Review knowledge indexing and wait for documents and URLs to be ready before judging answer quality.
- Configure an organization webhook and confirm the downstream endpoint receives the expected events from a test call.
Complete at least one realistic end-to-end call before changing traffic. Keep a rollback route to the Retell agent until call handling and downstream records have been verified.