Skip to main content
SignalMD 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 SignalMD 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. SignalMD 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. SignalMD reads the configuration and asks what to import: how far back, at most how many calls, what percent of new calls to keep, and an optional cap on them. It imports them and drafts the brief from both. Approving the brief starts the analysis.
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”. SignalMD 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 SignalMD gets data from Retell

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

​
Import settings

On Agent config, Import settings holds what you chose for the first import, and you can change it at any time with Save:
  • How far back and At most: what Import again brings in when you do not choose a window.
  • Keep importing new calls: a percent from 0 to 100. Below 100%, calls are picked by their ID, so the same calls are kept whether they arrive by webhook or by SignalMD’s own check. 0% imports no new calls.
  • Cap: No cap, or a number of calls per Day, Week or Month. Days, weeks and months are counted in UTC, and a week starts on Monday. Once the cap is reached, new calls that end in the rest of that day, week or month are skipped, not saved for later, and importing starts again when the next one begins. Only calls that arrive on their own count towards it; Import again does not.
With a cap set, the panel says where it stands, such as “12 of 50 this week”. When it is full, it says when new calls are imported again. Importing is free. Analysing a call uses 1 credit per processed minute. With calls already imported, the panel estimates what new calls use a month at the percent you set, from the agent’s recent calls. When the cap is lower than that, the estimate is what the cap allows, said as “at most”.

​
Add the webhook (optional)

The webhook makes calls arrive as soon as they end, instead of within about 15 minutes. SignalMD never sets or changes your agent’s webhook field; you add it yourself.
  1. On Agent config, copy the Webhook URL: https://api.signalmd.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 SignalMD is connected with the API key that your Retell workspace marks for webhooks. Retell signs each delivery with that key, and SignalMD 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 uses your import settings: the last 30 days and up to 500 new calls unless you changed them.
  • 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’s credits cover 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 credits. Calls that run past your plan’s credits are stored and wait for analysis until the period resets or you upgrade. See Pricing.
  • Failures. SignalMD 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 SignalMD, 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. SignalMD 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.
SignalMD 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 SignalMD 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 SignalMD 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 SignalMD is connected with the key marked for webhooks.
The page shows the reason, after SignalMD 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.

Fix an issue

Act on the first issue on your board.