Update a phone number
Updated
Changes the SIP trunk or inbound routing of a phone number.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/numbers/{number_id}Send only the fields you want to change. sip_trunk and inbound are each replaced as a whole, so pass the complete object, including sip_trunk.auth if the trunk uses authentication. If you leave out auth or allowed_ips, the saved values are removed. To stop routing inbound calls to an agent, set inbound to null. You can't change the phone number itself. To use a different number, create a new one.
appidstringThe App ID of your project.
number_idstringThe ID of the phone number, returned in number_id when you create the number.
If-MatchstringThe ETag value from the most recent response for this resource. If the resource has changed since then, the request fails with 412 and reason PreconditionFailed. Retrieve the resource, apply your change again, and retry with the new ETag.
The fields to change. Fields you omit keep their saved values. sip_trunk and inbound replace the saved object as a whole, so pass every field you want to keep. Set inbound to null to stop routing inbound calls to an agent. Other fields can't be null.
numberstringThe phone number in a different format. You can reformat the number, but you can't change it to a different number.
descriptionstringA description of the number's purpose. It's separate from sip_trunk.name, which names the carrier connection.
sip_trunkobjectThe carrier connection for this number.
namestringA name for the carrier connection that helps you identify it.
hostnamestringThe carrier's SIP hostname, without a scheme or port. For example, acme.pstn.example.com.
portintegerThe SIP signaling port. Defaults to 5061 when transport is tls, and 5060 when it's udp or tcp.
transportstringThe transport protocol for the carrier connection.
authobjectThe credentials for your SIP trunk. They are write-only and are never returned.
usernamestringThe SIP username.
passwordstringThe SIP password. Referring to a secret set, such as $secrets.support_prod.sip_password, isn't supported in the Preview.
allowed_ipsarray<string>The addresses allowed to send inbound SIP traffic to this number. Each entry is an IPv4 address, such as 54.172.60.1, or an IPv4 CIDR range, such as 54.172.60.0/23. IPv6 addresses and hostnames aren't accepted. If you omit it, inbound SIP traffic is accepted from any address, so set it to your carrier's signaling addresses.
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.
Response Body
The number was updated. The response body contains the full number.
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 PATCH 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/numbers/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'If-Match: string' \ -H 'Content-Type: application/json' \ -d '{ "inbound": { "agent": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10", "call_policy": { "max_call_duration_seconds": 1800 } }}'Response example
{ "number_id": "879cdb1c-6045-45ce-871d-5bdb73aa8c39", "number": "string", "description": "string", "sip_trunk": { "name": "string", "hostname": "string", "port": 0, "transport": "udp", "allowed_ips": [ "string" ] }, "inbound": { "agent": "string", "call_policy": { "max_call_duration_seconds": 1, "max_silence_duration_ms": 1, "end_call": { "on_user_request": false, "on_voicemail": false, "on_ai_assistant": false } } }, "create_ts": 0}