> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signalmd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Retell

> Connect a Retell agent with an API key, keep its calls flowing in, add more agents, and replace or remove a connection.

Signal reads your agent and its calls from Retell's API with an API key. This page is the reference for the connection. For the short path from sign-up to your first issues, use the [Quickstart](/quickstart).

## What you need

* A Retell account with at least one agent, and an API key from the Retell dashboard's API keys page.
* A Signal workspace: your personal one, or an organization if you work with a team. An agent belongs to the workspace you connect it in.

Conversation flow agents and single-prompt agents both connect. Step-level issues and the flow diagram are built from the agent's steps: the nodes of a conversation flow, or the states of a single-prompt agent.

## Connect an agent

<Steps>
  <Step title="Open the connect form">
    Open **Agent config** in the sidebar. A workspace with no agents of its own shows **Get started**. To add another agent, select **Add agent** at the top of **Agent config** or at the bottom of the agent menu in the sidebar.
  </Step>

  <Step title="Paste the key">
    Paste your Retell API key into **Retell key**, or pick one under **Saved key** to reuse it. Optionally give a new key a **Name**, such as the client's name. Signal checks the key as soon as you stop typing: "Checking the key…", then "Key accepted. 3 agents to choose from."
  </Step>

  <Step title="Choose the agent">
    Pick the agent from **Agent**. Agents already connected in this workspace show **Already connected**.
  </Step>

  <Step title="Connect">
    Select **Connect**. Signal reads the configuration and moves on to the [brief](/concepts/the-brief). Approving the brief starts the first import.
  </Step>
</Steps>

Once connected, the agent's name, Retell agent ID and current version appear under the title of **Agent config**.

The key is encrypted at rest and afterwards shown only as its name plus its last four characters, such as "Acme Health · \*\*\*\*ab5c". Signal uses it to read: the agent, its flow or prompt, tools, phone numbers, knowledge bases and calls. It does not use it to change anything in Retell. Two features write to Retell, both opt-in and both through a separate **Retell write key** you store for testing: test runs in Retell's simulator (see [Test a fix](/guides/test-a-fix)), and publishing a drafted fix, which happens only when an admin selects publish in [Build](/copilot/build). See [Data and security](/data-and-security#changes-to-your-retell-agent).

## How Signal gets data from Retell

| What Signal reads | When |
| - | - |
| The agent's configuration | When you connect, and again for each new version |
| A new version | Picked up within about 10 minutes of publishing |
| Your first import | When you approve the brief: the latest 500 ended calls from the last 30 days, newest first |
| New calls | Within about 15 minutes of ending. With the webhook, as soon as they end |

New calls reach the board without any action from you, and their analysis follows within a few minutes. Calls Signal placed itself as tests are never imported.

### Add the webhook (optional)

The webhook makes calls arrive as soon as they end, instead of within about 15 minutes. Signal never sets or changes your agent's webhook field; you add it yourself.

1. On **Agent config**, copy the **Webhook URL**: `https://first-signal-api.fly.dev/webhooks/retell`.
2. In Retell, paste it into the agent's webhook URL, with the `call_ended` or `call_analyzed` event turned on.
3. Make sure Signal is connected with the API key that your Retell workspace marks for webhooks. Retell signs each delivery with that key, and Signal refuses a delivery signed by any other key with `401`. If you connected with a different key, use **Replace key** (below).

The same panel shows **Last call arrived** and when the last webhook arrived ("No webhook received yet" until one does). If the agent already sends its webhook to another service, you can leave it: new calls still show up within about 15 minutes without it.

If Retell refuses the stored key, that panel shows the reason. Connecting a working key clears it.

## Import calls

You rarely need to import by hand after the first import. To bring in an older window, or calls from a version at once, use the panel on **Agent config**, titled **Import more calls** once calls exist:

* **Import again** repeats the default: the last 30 days, up to 500 new calls.
* **Choose a window and count** lets you set **From** and **To** (call start dates) and **Calls to add**, then **Import again**.

The panel says before you start how far back an import may reach, how many calls one import takes, and how many more calls your plan analyses before its period resets. Then:

* **Safe to repeat.** Calls already imported are skipped and do not count towards **Calls to add**. When the whole window is stored, the progress says "No new calls: everything in this window was already imported."
* **Limits.** An import reaches back at most 30 days and brings in at most 1,000 calls. Ask for more and it is trimmed, with a note such as "Imported 1,000 of 1,500 requested; one import brings in up to 1,000 calls. Import again for more."
* **Plan allowance.** Calls past your plan's analysed-call allowance are stored and wait for analysis until the period resets or you upgrade. See [Pricing](/billing/pricing).
* **Failures.** Signal retries on its own. If it still fails, the page says "The import stopped." with the reason and an **Import again** button.

## Connect more than one agent

Each Retell agent you connect becomes its own agent in Signal, with its own brief, calls, issues, flow and versions. Switch between them with the agent menu in the sidebar; the demo agent is marked "(demo)". A saved key can serve many agents, and **New key** adds another Retell workspace's key. Your plan sets how many agents a workspace can hold.

## Disconnect and delete

Only workspace admins see these actions, in the **Connection** panel on **Agent config**.

* **Replace key.** After you rotate the key in Retell, or to switch to the key marked for webhooks, select **Replace key**. The new key must be able to read this agent.
* **Delete agent.** Signal lists what goes, with counts: calls with their transcripts, traces and analysis, issues, the brief, captured versions, tests and runs, and the stored Retell key unless another agent uses it. Deleting cannot be undone, and nothing changes in Retell.
* **Cut off access.** Delete or replace the API key in Retell. New calls and imports for that agent then stop until a working key is connected.

Signal stores each call's full record as Retell sent it, so improvements to its analysis reach your existing calls without importing again. Deleting your organization, or your account for a personal workspace, erases everything Signal stored for it. What is stored, who processes it and how deletion works are in [Data and security](/data-and-security).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Retell rejected that API key">
    Retell returned an authorisation error. Copy the key again from the API keys page in Retell, with no spaces, and check it comes from the Retell workspace that holds the agent.
  </Accordion>

  <Accordion title="Retell has no agent ... on this key">
    The agent may have been deleted in Retell, or it belongs to another Retell workspace. Use that workspace's key, or choose another agent.
  </Accordion>

  <Accordion title="Retell answered with an error, or Could not reach Retell">
    Retell returned an error (the number is its status code) or no answer arrived. Select **Try again**. These are not problems with your key.
  </Accordion>

  <Accordion title="The key works, but this Retell workspace has no agents yet">
    Create an agent in Retell, then select **Check again**.
  </Accordion>

  <Accordion title="Every agent on this key is already connected">
    Choose the agent from the agent menu in the sidebar. If you cannot see it, check the organization switcher: it may be in another workspace.
  </Accordion>

  <Accordion title="New calls are not showing up">
    A call can take up to about 15 minutes to arrive without the webhook, plus a few minutes for its analysis. On **Agent config**, **Last call arrived** says when Signal last stored one, and an error under it says if Retell is refusing the key. Only ended calls count, and calls made by other agents are not imported: compare the Retell agent ID under the page title with the one in Retell. To pull calls in at once, use **Import more calls**.
  </Accordion>

  <Accordion title="No calls found in this range">
    Calls are matched on their start date. Select **Choose a window and count** and widen **From** and **To**, up to 30 days back.
  </Accordion>

  <Accordion title="No webhook received yet, or deliveries are refused">
    Check that the URL in the agent's webhook field in Retell matches the one on **Agent config**, that the events include call ended or call analyzed, and that Signal is connected with the key marked for webhooks.
  </Accordion>

  <Accordion title="The import stopped, Analysis stopped, or Reading the agent stopped">
    The page shows the reason, after Signal has already retried on its own. Select **Import again** or **Analyze again**. If it fails again with a Retell error, check that the key still works.
  </Accordion>

  <Accordion title="The demo agent is read-only">
    You are on the shared demo. Select **Connect your agent** in the banner.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="The brief" icon="file-lines" href="/concepts/the-brief">
    What to check before you approve and import.
  </Card>

  <Card title="Fix an issue" icon="wrench" href="/guides/fix-an-issue">
    Act on the first issue on your board.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.