PHONE NUMBERS

Amazon Connect

There are two regimes in which the Phonic Voice Agent can communicate over telephone:

  • Outbound Calls: The agent is the caller. The agent initiates calls to other phone numbers from a user-configured phone number.
  • Inbound Calls: The agent is the callee. The agent receives calls from anyone at a user-configured phone number.

This guide walks through connecting Phonic to Amazon Connect for both inbound and outbound calls. Unlike SIP trunking providers such as Twilio or Telnyx, Amazon Connect cannot be pointed directly at an external SIP URI. Instead, you create an Amazon Chime SDK Voice Connector — AWS’s SIP trunking service — and use it as the bridge between Phonic and your Amazon Connect instance.

On a Chime SDK Voice Connector, the SIP terminology is inverted relative to Twilio:

  • Origination — calls the Voice Connector routes outbound to your SIP host (Phonic’s LiveKit endpoint). This is what powers inbound calls to your agent.
  • Termination — calls sent into the Voice Connector from your SIP host (Phonic). This is what powers outbound calls from your agent.

Keep this in mind as you follow the steps below.

Prerequisites

Create an Amazon Chime SDK Voice Connector

This Voice Connector is the SIP trunk shared by both the inbound and outbound flows.

  1. In the AWS console, open the Amazon Chime SDK console and navigate to Voice → Voice connectors.

  2. Click Create Voice Connector. Give it a friendly name (for your identification only) and select an AWS Region.

  3. Once created, open the Voice Connector and note its Outbound host name (e.g. abcdef1ghij2klmno3.voiceconnector.chime.aws). You’ll need this for outbound calls.

  4. Under Phone numbers, assign the phone number you want to use with Phonic to this Voice Connector.

For more information, refer to the AWS guide on creating a Voice Connector.

Inbound

To set up an agent to accept inbound calls, configure the Voice Connector to route incoming calls to Phonic’s LiveKit endpoint, then add the phone number to your agent.

  1. Open your Voice Connector and go to the Origination tab. Set the status to Enabled.

  2. Add an inbound route pointing at Phonic’s LiveKit endpoint:

    • Host: 2j1rahun317.sip.livekit.cloud
    • Port: 5060
    • Protocol: TLS (recommended) or UDP
    • Priority / Weight: 1 / 1

  3. Make sure the phone number is associated with this Voice Connector (see the previous section).

For more information on origination settings, refer to the AWS docs on editing Voice Connector settings.

Once the Voice Connector is routing to Phonic, use the Phonic API to create or update an agent with { phone_number: "custom", custom_phone_numbers: [<your_phone_numbers>] }.

The agent will now be able to receive phone calls on any of the configured phone numbers.

You can use the configuration_endpoint agent parameter to customize the agent’s behavior based on the incoming phone number.

Outbound

To perform outbound calls, configure the Voice Connector to accept calls from Phonic (termination), then call the /conversations/sip/outbound_call endpoint.

  1. Open your Voice Connector and go to the Termination tab. Set the status to Enabled.

  2. Under Allowed hosts, add the CIDR range(s) that Phonic will originate calls from, so your Voice Connector only accepts traffic from Phonic.

  3. Create a credential (username and password) and add it to the Voice Connector. Record these — they’re required for authenticating outbound calls. This step is technically optional but strongly recommended to prevent your Voice Connector from being spoofed.

For more information on termination settings, refer to the AWS docs on editing Voice Connector settings.

Once your Voice Connector is configured, use the following code to initiate the call! Use the Voice Connector’s Outbound host name as the SIP address, and the termination credential you created as the username and password. Also, make sure you set your config appropriately!

$curl --location 'https://api.phonic.ai/v1/conversations/sip/outbound_call' \
>--header 'X-Sip-Address: <your-voice-connector-outbound-host-name>' \
>--header 'X-Sip-Auth-Username: <your-termination-username>' \
>--header 'X-Sip-Auth-Password: <your-termination-password>' \
>--header 'Content-Type: application/json' \
>--header 'Authorization: <your-phonic-api-key>' \
>--data '{
>    "to_phone_number": "+12345678900",
>    "from_phone_number": "+11123581321",
>    "config": {
>        "welcome_message": "Hello, how can I help you?",
>        "system_prompt": "You are a conversational AI assistant talking with a customer over the phone. Always respond to the customer in 1-2 sentences. Naturally end the conversation when the user says goodbye.",
>        "voice_id": "grant",
>        ...
>    }
>}'

Connecting the Voice Connector to your Amazon Connect instance

If you want calls handled by your existing Amazon Connect contact center to reach Phonic, use Amazon Connect’s external voice transfer feature. This lets a contact flow hand a live call off to the Chime SDK Voice Connector — and therefore to Phonic — without routing it back over the PSTN.

  1. In the Amazon Connect admin console, configure your external voice system, selecting the Chime SDK Voice Connector you created above. This associates the Voice Connector with your Connect instance.

  2. In the Amazon Connect flow designer, open (or create) the contact flow that should reach Phonic.

  3. Add a Transfer to external system (external voice transfer) block and point it at the destination that maps to Phonic’s LiveKit endpoint through your Voice Connector.

  4. Publish the contact flow and associate it with the phone number claimed in Amazon Connect.

Inbound calls to your Amazon Connect number will now flow through your contact center, into the Chime SDK Voice Connector, and on to your Phonic agent. For authoritative, up-to-date console steps, follow the AWS guide on configuring an external voice system.

Phone Call Transfers

If you intend to use the “transfer to phone number” feature, make sure SIP REFER is handled appropriately on your Voice Connector and that PSTN calling is enabled for the relevant numbers. See the AWS docs on Voice Connector settings for configuration details.