Register call

Let your PBX or SIP platform choose the agent per call by registering the call first and then dialling a one-time SIP URI.

Register call is for setups where your own system decides, call by call, which agent should talk and with which variables. Instead of tying a number to an agent, your server registers the call with POST /v2/register-phone-call, gets back a one-time SIP URI, and your PBX dials or transfers the call to that URI within 5 minutes. No phone number has to be imported into Tried.

Needs keys

Needs LiveKit SIP (LIVEKIT_SIP_URI and the LiveKit API keys) and either REGISTER_CALL_ALLOWED_ADDRESSES (your PBX IPs or CIDRs) or REGISTER_CALL_AUTH_USERNAME and REGISTER_CALL_AUTH_PASSWORD. LiveKit refuses the catch-all trunk this mode uses without one of them.

Flow#

Register the call#

Your server calls POST /v2/register-phone-call with the agent and any variables.

Dial the SIP URI#

The response contains call_id and sip_uri (sip:<call_id>@<LIVEKIT_SIP_URI>). Your PBX sends the call there.

The agent joins#

Tried matches the call ID, checks concurrency, and dispatches the agent into the call. From here it is a normal phone call with webhooks, recording and analysis.

Request#

curl -X POST https://api.tried.com.au/v2/register-phone-call \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_8e0c...",
    "agent_version": "prod",
    "from_number": "+61412345678",
    "to_number": "+61290001234",
    "direction": "inbound",
    "retell_llm_dynamic_variables": { "account_tier": "gold" }
  }'

POST /register-phone-call is an alias.

Field	Type	Default	Description
`agent_id`	string	required	Agent that answers.
`agent_version`	integer or string	latest	Version number, `latest`, `latest_published` or a tag name.
`from_number`	string	none	Caller, stored on the call.
`to_number`	string	none	Dialled number, stored on the call.
`direction`	`inbound` \| `outbound`	`inbound`	Direction recorded on the call and used for the concurrency check.
`metadata`	object	`{}`	Stored on the call.
`retell_llm_dynamic_variables`	object	`{}`	Variables for the agent.

Response#

HTTP 201 with the call object in call_status: "registered", plus sip_uri:

{
  "call_id": "call_5b3c9e...",
  "call_type": "phone_call",
  "call_status": "registered",
  "direction": "inbound",
  "agent_id": "agent_8e0c...",
  "from_number": "+61412345678",
  "to_number": "+61290001234",
  "sip_uri": "sip:call_5b3c9e...@example.sip.livekit.cloud"
}

Rules#

The PBX must connect within 5 minutes. Otherwise the call ends with registered_call_timeout.
Each registered call can be used once. A second INVITE to the same URI, or one after the timeout, is hung up.
The concurrency check runs when the PBX connects. A full workspace ends the call with concurrency_limit_reached.
If the register-call SIP routing cannot be set up (no allowed addresses or credentials), the request returns 422 and the call ends with sip_routing_error.

What Tried provisions#

On the first register-call request, Tried creates one catch-all LiveKit inbound trunk and a callee dispatch rule that puts each call in the room reg_<call_id>. It is reused for later calls. The trunk accepts calls only from REGISTER_CALL_ALLOWED_ADDRESSES, or with the REGISTER_CALL_AUTH_* digest credentials.

When to use it#

Use	Choose
Each number always goes to the same agent (or an A/B split)	Import the number
Your IVR picks the agent from a menu choice or CRM lookup	Register call
You want to look up the caller but keep the number's agent	Import the number and use the inbound call webhook