Retrieve a phone number
Updated
Retrieves a phone number and its SIP and inbound settings.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/numbers/{number_id}appidstringThe App ID of your project.
number_idstringThe ID of the phone number, returned in number_id when you create the number.
Response Body
The request was successful. The response body contains the number. SIP credentials are never returned.
Response Headers
number_idstringThe ID of the phone number, a UUID.
numberstringThe phone number in E.164 format.
descriptionstringA description of the number's purpose. It's separate from sip_trunk.name, which names the carrier connection.
sip_trunkobjectnamestringThe name of the carrier connection.
hostnamestringThe carrier's SIP hostname.
portintegerThe SIP signaling port.
transportstringThe transport protocol for the carrier connection.
allowed_ipsarray<string>The addresses allowed to send inbound SIP traffic.
inboundobjectWhat happens when someone calls this number. If you omit it, inbound calls are rejected. call_policy is required when agent isn't null.
agentstring | nullThe ID of the agent that answers inbound calls. Set to null to reject inbound calls.
call_policyobjectLimits and behavior for inbound calls to this number. Each limit you omit adds no limit.
max_call_duration_secondsintegerThe maximum length of a call in seconds, measured from when it's answered.
max_silence_duration_msintegerHang up when nobody on the call has spoken for this many milliseconds.
end_callobjectConditions under which the agent can end the call itself. Every condition is off unless you set it to true.
on_user_requestbooleanEnd the call when the caller clearly says goodbye or asks to hang up.
on_voicemailbooleanEnd the call when the agent reaches voicemail, such as a "please leave a message after the tone" announcement.
on_ai_assistantbooleanEnd the call when the call is answered by an AI assistant, a voice secretary, or another automated answering system.
create_tsintegerThe time the number was added, as a Unix timestamp in seconds.
Request examples
curl -X GET 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/numbers/497f6eca-6276-4993-bfeb-53cbbbba6f08'Response example
{ "number_id": "92e68758-3d3a-4f27-8b93-3fd8d834467c", "number": "+14155550100", "description": "Primary customer support line for North America.", "sip_trunk": { "name": "support-line", "hostname": "acme.pstn.example.com", "port": 5061, "transport": "tls" }, "inbound": { "agent": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10", "call_policy": { "max_call_duration_seconds": 1800, "max_silence_duration_ms": 60000, "end_call": { "on_user_request": true } } }, "create_ts": 1787223852}