Troubleshooting
Calls and assistant behavior
The call did not connect, the assistant said the wrong thing, or a tool never fired — where to look first.
The call does not connect#
Work outward from the number.
Is the number assigned to an assistant?#
An inbound number with no assistant has nothing to answer it. Check the assignment:
curl https://core-api.heysadie.ai/phone-numbers \
-H "Authorization: ApiKey YOUR_API_KEY"Look for assistantId on the number you dialed. If it is null, attach one — see Phone numbers.
Is the assistant in failover mode?#
failoverMode: true forwards every call straight to failoverNumber without the assistant ever answering. It is a deliberate kill switch and it is easy to leave on.
curl https://core-api.heysadie.ai/assistants/ASSISTANT_ID \
-H "Authorization: ApiKey YOUR_API_KEY"Is the number E.164?#
+15555550123, not (555) 555-0123. Anything else is rejected with VALIDATION_ERROR.
Did a call record appear at all?#
curl "https://core-api.heysadie.ai/calls?limit=5" \
-H "Authorization: ApiKey YOUR_API_KEY"A record with a failure status tells you the call reached the platform. No record at all points upstream — at the carrier or the number configuration, not the assistant.
The assistant says the wrong thing#
Placeholders are not being substituted#
If callers hear a literal {{opening_hours}}, the key is missing from parameters. Every {{placeholder}} in developerPrompt needs a matching key:
{
"developerPrompt": "We are open {{opening_hours}}.",
"parameters": { "opening_hours": "10am to 10pm" }
}The names must match exactly — {{openingHours}} will not be filled by opening_hours.
The wrong prompt is winning#
An assistant can draw on several sources at once, and they compose rather than replace:
| Source | Where it comes from |
|---|---|
developerPrompt | Inline on the assistant |
promptId | A shared prompt for voice |
chatPromptId | A shared prompt for chat |
| Custom instructions | Up to six short behavior notes |
| Task groups | Ordered task flows, when taskDrivenMode is on |
If behavior is not changing when you edit one, another is probably supplying it. Check custom instructions first — they are the easiest to forget.
Changes are not taking effect#
Configuration is read when a call starts. A call already in progress keeps the configuration it began with — place a new call to test a change.
A tool never fires#
In order:
- Is it attached? The tool must be in the assistant's
toolIds, not merely defined in the tenant. - Does the description tell the model when to use it? Tool selection is driven by the description. "Gets data" will not be selected reliably; "Look up an order's delivery status by order number" will.
- Are the parameters described? Each parameter needs a description the model can reason about.
- Is your server responding in time? A tool call is a live HTTP request inside a conversation. If your endpoint takes seconds, the assistant is stuck waiting. Aim well under a second and return partial data rather than stalling.
See Tools for the definition format and Tool calls to your server for the exact request shape.
Reading what actually happened#
The end-of-call report is the highest-fidelity record — transcript, summary, recording and structured data. It is far more useful than reconstructing a call from list endpoints.
If you are polling Calls to find out when a call ended, stop and take the webhook instead. It is faster, cheaper, and carries more.
Related#
- Assistants — the full lifecycle.
- Dynamic transfer — resolving transfer destinations at call time.
- Errors — status and error codes.
- Transfers — cold, warm and warm-return, and why a hand-off rang out.