Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

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 objectnullable

    SIP inbound call configuration.

    Show propertiesHide properties
    • allowed_addresses arrayrequired

      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

      Possible values: tls, tcp, udp

      Transport protocol.

    • prefix stringnullable

      Number prefix. For example: 6036

    • user stringnullable

      SIP authentication username for outbound calls

    • password stringnullable

      SIP authentication password for outbound calls

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
    • outbound_config object

      The outbound configuration.

    • outbound_config object

      The outbound configuration.

  • 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.

    Common error codes:

    • 400 invalid_phone_format: Invalid phone number format (not in E.164 format).
    • 401 unauthorized: Authentication failed, please check your credentials.
    • 409 phone_number_exists: Phone number already exists, duplicate import not allowed.
    • 422 unprocessable_content: Request format error or parameter validation failed.
    • 500 internal_server_error: Internal server error.

Authorization

This endpoint requires Basic Auth.

Request example


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

Response example

Not bound to pipeline


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

Bound to pipeline


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