Create a phone number
Updated
Registers a phone number, its SIP trunk, and its inbound routing in your project.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/numbersUse this endpoint to import a number that your carrier assigned to you. Importing a number doesn't purchase one. Outbound sessions and campaigns can use the number as their caller ID, and inbound chooses the agent that answers calls to it.
appidstringThe App ID of your project.
numberstringThe phone number in E.164 format, for example +14155550100.
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 created. The response body contains the saved 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 POST 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/numbers' \ -H 'Content-Type: application/json' \ -d '{ "number": "+14155550100", "description": "Primary customer support line for North America.", "sip_trunk": { "name": "support-line", "hostname": "acme.pstn.example.com", "transport": "tls", "auth": { "username": "acme", "password": "<your_sip_password>" } }, "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 } } }}'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}