azrtydxb/hello/hello-troubleshoot

Hello troubleshooting

Hello explains its own behaviour: every call leaves a call detail record (CDR) with a routing trace and a failure explanation, every REGISTER attempt is kept for a while with its outcome, and every node publishes its state. Read those first; change configuration only once the cause is clear, and then with the hello-setup or hello-routing skill.

Connecting

• MCP server: https://<hello host>/mcp (on kw: https://hello.kw.watteel.lab/mcp).
• Scopes: read covers everything here. The one change this skill may make,

unblocking an IP with clearAuthFailures, needs write and the operator role; ask the user before doing it.

• Resources: the server also offers live state as resources (for example

hello://registrations); read them when your client supports resources.

Start with the cluster

getCluster returns every node, PostgreSQL and Valkey health and the configuration revision. If PostgreSQL or Valkey is down, or a SIP node is not READY, that is the first thing to report: most other symptoms follow from it. See cluster states.

A call that failed

1. Find it: listCDRs, filtered by number and time if the user gave them.

countCDRs tells you whether failures are unusual right now.

1. getCDR for the record: the final status, which side ended it, the

failure reason in plain words, the route and trunk used, and the routing trace.

1. If the routing looks wrong, re-run the decision with testRouting (same

caller and number) to see whether the saved configuration still decides the same way.

1. Explain the cause in one or two sentences and name the fix: a route

(hello-routing), a device (hello-setup), or the carrier.

A phone that does not register

1. listRegistrations: is the device registered at all, from which address

and on which node?

1. listDevices to find the device id, then getDeviceDiagnostics. It

returns the recent REGISTER attempts (source, user agent, response code, whether credentials were sent) and a verdict that says why it is not registered.

1. If the source IP is blocked for too many failed authentications,

listAuthFailures shows it. A wrong password keeps failing after an unblock, so fix the credentials first (the administrator rotates the device secret in the console, or re-provisions the phone), then clearAuthFailures for the IP with the user's agreement.

1. A provisioned phone that never fetched its configuration:

listPhoneFetches for the phone. No fetches means DHCP or the vendor redirect does not point at Hello (getProvSettings has the values).

See registration verdicts.

A trunk that is down

listTrunkStatus shows each trunk's registration state (registered, registering, failed, misconfigured, disabled) with the last response code, and each destination's health from OPTIONS pings. getTrunk shows the configuration (never the password). See trunk states.

Which release, who am I, what is live

• getVersion answers the build, commit and configuration revision of the

node that replied; getMe says whose credentials you are using and with which role and scopes (check it when a call is refused with 403).

• listCalls lists the calls in progress now; listRegistrations the

registered contacts. cdrConcurrency (range 1h, 6h or 24h) shows how many calls were up at once, to size trunks or find busy hours; countCDRs gives totals and failures for the same filters as listCDRs.

• listPresence shows each device as idle, ringing, on-call or dnd.
• listSkills lists the skills this server ships, so a client can offer them.

What happened on a call: events

listEvents pages through the stored call events (kept for a few days, 7 by default), oldest first by default (order desc for newest first, nextCursor to continue). Filter with types (comma-separated, a trailing .* matches a prefix such as call.*) and extension. It needs the events scope, which is separate from read; a user or an extension-scoped service account only sees events about its own extensions. Use it after getCDR to see the order of things (ringing, answered, transferred, hung up) for one extension; the live stream is for the console and is not an MCP tool.

Cluster depth: maintenance and draining

getCluster and listClusterNodes give the state. Before maintenance on a node, drainNode (path id is the node's HELLO_NODE_ID, admin only) lets it finish its calls and stop taking new ones; undrainNode cancels it. Draining the last READY SIP node answers 409; do not pass force=true unless the user has said that dropping call capacity is acceptable. Ask before draining.

Findings and proposals from the AI agent

Hello can run background detectors and an assistant of its own. They only suggest: nothing changes until an operator applies a proposal in the console.

• getAIStatus: is it on, why not, token use against the budget, open counts.
• listAIFindings (filter status, severity, type) and getAIFinding:

what the detectors found, with evidence and the health score. Start here for "is anything wrong with my PBX".

• listAIProposals and getAIProposal: suggested changes with the stored

before and after and the object's current state. Explain them; never claim a proposal was applied.

• listAIAgents, getAISettings (the MCP and API URLs and what each scope

allows), listAISessions, getAISession and getAITask for the assistant's own sessions and tasks.

Text-to-speech settings

getTtsSettings (admin) says whether a key is set (never the key), its last four characters, and the default model and voice; listTtsVoices lists the models and voices to pick from. deleteTtsKey removes the stored key: prompts already generated keep playing but no new one can be made; ask first. Setting the key and generating audio happen in the console only.

Answering

Say what you found, what it means and what to do, in that order. Quote the evidence (the CDR id, the response code, the verdict) so the user can check it in the console.

References

• Tools - every tool this skill uses.
• Cluster states
• The hello-flow-graph skill shows where a call can go.
• Registration verdicts and SIP codes
• Trunk states