Skip to main content
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.

​
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

1

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.
2

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.”
3

Choose the agent

Pick the agent from Agent. Agents already connected in this workspace show Already connected.
4

Connect

Select Connect. Signal reads the configuration and moves on to the brief. Approving the brief starts the first import.
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), and publishing a drafted fix, which happens only when an admin selects publish in Build. See Data and security.

​
How Signal gets data from Retell

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.
  • 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.

​
Troubleshooting

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.
The agent may have been deleted in Retell, or it belongs to another Retell workspace. Use that workspace’s key, or choose another agent.
Retell returned an error (the number is its status code) or no answer arrived. Select Try again. These are not problems with your key.
Create an agent in Retell, then select Check again.
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.
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.
Calls are matched on their start date. Select Choose a window and count and widen From and To, up to 30 days back.
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.
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.
You are on the shared demo. Select Connect your agent in the banner.

​
Next steps

The brief

What to check before you approve and import.

Fix an issue

Act on the first issue on your board.