# Import phone numbers (/en/ai/platform/build/phone-calls/import-phone-numbers) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). > Documentation: Conversational AI. > Documentation version: Preview. > This document describes only this version. [Version index](/llms/doc-versions-convoai-guides-v2.txt). 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](/en/ai/platform/build/phone-calls/route-inbound-calls). - **Outbound calls**: Sessions and campaigns use the number as their caller ID. For details, see [Make outbound calls and run campaigns](/en/ai/platform/build/phone-calls/outbound-calls-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](/en/ai/platform/get-started/start-stop-agent#prerequisites). - 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](/en/ai/platform/build/phone-calls/route-inbound-calls). **Python SDK** ```python 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": ""}, }, inbound={ "agent": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10", "call_policy": {"max_call_duration_seconds": 1800}, }, ) print(number["number_id"]) # The number ID ``` **TypeScript SDK** ```ts const 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: '' }, }, inbound: { agent: '3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10', call_policy: { max_call_duration_seconds: 1800 }, }, }); console.log(number.number_id); // The number ID ``` **Go SDK** The last argument is an idempotency key. Number creation doesn't support one, so pass an empty string. ```go 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: ""}, }, 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 ID ``` **REST API** Send a request to [Create a phone number](/en/api-reference/api-ref/conversational-ai/platform/create-number): ```bash curl --request POST \ --url https://preview.ai.agora.io/conversational-ai/v1/projects//numbers \ --header 'Authorization: Basic ' \ --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": "" } }, "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. ```json // 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: - [Route inbound calls to an agent](/en/ai/platform/build/phone-calls/route-inbound-calls) - [Make outbound calls and run campaigns](/en/ai/platform/build/phone-calls/outbound-calls-campaigns) ### API reference - [Create a phone number](/en/api-reference/api-ref/conversational-ai/platform/create-number) - [Retrieve a phone number](/en/api-reference/api-ref/conversational-ai/platform/retrieve-number) - [Update a phone number](/en/api-reference/api-ref/conversational-ai/platform/update-number) - [List phone numbers](/en/api-reference/api-ref/conversational-ai/platform/list-numbers) - [Delete a phone number](/en/api-reference/api-ref/conversational-ai/platform/delete-number)