Import number

POST

https://api.agora.io/api/conversational-ai-agent/v2/phone-numbers

Use this endpoint to import a pre-configured phone number that can be used for inbound or outbound calls.

Request

Request body

APPLICATION/JSON

Request Bodyrequired

provider stringrequired
Possible values: byo, twilio
Number provider:
- byo: BYO (Bring Your Own)
- twilio: Twilio
phone_number stringrequired
Telephone number in E.164 format.
label stringrequired
A label used to identify the number.
inbound booleannullable
Default: true
Whether the number supports inbound calls.
outbound booleannullable
Default: true
Whether the number supports outbound calls.
inbound_config objectrequired
SIP inbound call configuration.
Show propertiesHide properties
- allowed_addresses arraynullable
  List of allowed IP addresses. For example: 112.126.15.64/27
outbound_config objectrequired
SIP outbound call configuration.
Show propertiesHide properties
- address stringnullable
  SIP address. For example: xxx:xxx@sip.example.com
- transport stringnullable
  Transport protocol. For example: tls
- prefix stringnullable
  Number prefix. For example: 6036

Response

If the returned status code is 201, the request was successful. The response body contains the result of the request.
Response Body
- phone_number string
  A telephone number in E.164 format, used as a unique identifier.
- label string
  A label used to identify the number.
- provider string
  Number provider.
- inbound boolean
  Whether the number supports inbound calls.
- outbound boolean
  Whether the number supports outbound calls.
- associated_pipeline object
  The associated pipeline information. Returns null if no pipeline is associated.
  Show propertiesHide properties
  pipeline_id string
  Pipeline ID.
  pipeline_name string
  Pipeline name.
If the returned status code is not 201, the request failed. The response body includes the error code and description. Refer to status codes to understand the possible reasons for failure.
Error Response
- detail string
  The type of error that occurred.
- reason string
  The reason for the error.

Authorization

This endpoint requires Basic Auth.

Request example

curl
Python
Node.js

curl --request POST \
  --url https://api.agora.io/api/conversational-ai-agent/v2/phone-numbers \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "byo",
  "phone_number": "+19876543210",
  "label": "Sales Hotline",
  "inbound": true,
  "outbound": true,
  "inbound_config": {
    "allowed_addresses": [
      "112.126.15.64/27"
    ]
  },
  "outbound_config": {
    "address": "xxx:xxx@sip.example.com",
    "transport": "tls"
  }
}'

Response example

201
Non-200

Not bound to pipeline

{
  "phone_number": "+11234567890",
  "label": "Customer Support Line",
  "provider": "byo",
  "inbound": true,
  "outbound": true,
  "associated_pipeline": null
}

Bound to pipeline

{
  "phone_number": "+11234567890",
  "label": "Customer Support Line",
  "provider": "byo",
  "inbound": true,
  "outbound": true,
  "associated_pipeline": {
    "pipeline_id": "agent_0987654321fedcba",
    "pipeline_name": "Support Bot"
  }
}