Import phone numbers
Updated
Import a phone number and its SIP trunk from your carrier, and use it for your agents' phone calls.
Preview documentation
To let your agents make and receive phone calls, import the phone numbers your carrier assigned to you. Each number connects to the phone network through your SIP trunk. Importing a number doesn't purchase one.
Understand the tech
After you import a number, you can use it in both directions:
- Inbound calls: When someone calls the number, the Platform starts a session with the routed agent, and the agent answers the call. For details, see Route inbound calls to an agent.
- Outbound calls: Sessions and campaigns use the number as their caller ID. For details, see Make outbound calls and run campaigns.
Prerequisites
Before you begin, make sure that you have:
- An Agora project, and REST API credentials or an SDK client. For details, see Create an agent and start a session.
- A phone number from a carrier that supports SIP trunking, in E.164 format, for example
+14155550100. - Your SIP trunk's hostname, transport protocol, username, and password.
Import a number
Import the number with its SIP trunk. To have an agent answer calls to the number, also set the inbound agent and a call policy, as in the following example. For details, see Route inbound calls to an agent.
number = client.numbers.create(
number="+14155550100",
description="Customer support line",
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},
},
)
print(number["number_id"]) # The number IDconst number = await client.numbers.create({
number: '+14155550100',
description: 'Customer support line',
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 },
},
});
console.log(number.number_id); // The number IDThe last argument is an idempotency key. Number creation doesn't support one, so pass an empty string.
description := "Customer support line"
trunkName := "support-line"
agentID := "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10"
number, err := client.Numbers.Create(ctx, agentkit.NumberCreate{
Number: "+14155550100",
Description: &description,
SipTrunk: agentkit.SipTrunk{
Name: &trunkName,
Hostname: "acme.pstn.example.com",
Transport: "tls",
Auth: &agentkit.SipAuth{Username: "acme", Password: "<your_sip_password>"},
},
Inbound: &agentkit.Inbound{
Agent: &agentID,
CallPolicy: map[string]any{"max_call_duration_seconds": 1800},
},
}, "")
if err != nil {
log.Fatal(err)
}
fmt.Println(number.Body.NumberID) // The number IDSend a request to Create a phone number:
curl --request POST \
--url https://preview.ai.agora.io/conversational-ai/v1/projects/<your_app_id>/numbers \
--header 'Authorization: Basic <your_base64_encoded_credentials>' \
--header 'Content-Type: application/json' \
--data '
{
"number": "+14155550100",
"description": "Customer support line",
"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
}
}
}'If the request is successful, the response contains the number's ID and its configuration. The auth credentials aren't returned.
// 201 Created
{
"number_id": "92e68758-3d3a-4f27-8b93-3fd8d834467c",
"number": "+14155550100",
"description": "Customer support line",
"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
}
},
"create_ts": 1786543331
}In sip_trunk, set the following fields:
| Field | Description |
|---|---|
hostname | Required. Your carrier's SIP hostname, without a scheme or port, for example acme.pstn.example.com. |
transport | The transport protocol: tls, tcp, or udp. The default is tls. |
port | The SIP signaling port. The default is 5061 for tls, and 5060 for udp and tcp. |
auth | Your SIP username and password. The API never returns them. Referring to a secret set for the password isn't supported in the Preview. |
allowed_ips | The addresses allowed to send inbound SIP traffic, as IPv4 addresses such as 54.172.60.1 or IPv4 CIDR ranges such as 54.172.60.0/23. If you omit it, inbound SIP traffic is accepted from any address, so set it to your carrier's signaling addresses. |
name | A name that helps you identify the carrier connection. |
Store the number ID. You use it to place outbound calls from the number and to update it. You can't change the phone number itself. To use a different number, import it.
Reference
For more information, see the following pages: