Bring your own numbers

This document describes how to integrate phone numbers with Audact's call validation platform through two distinct pathways: Audact-provisioned numbers (managed through Telnyx) and Bring-Your-Own (BYO) trunks (managed through your own telephony provider).

Two Number Types

Audact supports two fundamental ways to supply phone numbers for inbound call routing:

Type 1: Audact-Provisioned Numbers (Telnyx)

Audact manages the complete number lifecycle through its Telnyx carrier relationship.

Acquisition: You request numbers through the KYC document submission and number ordering flow documented in Number Provisioning & KYC. Audact encrypts your compliance documents, submits them to Telnyx for approval, and once approved, you can order DIDs in any country/type combination covered by that approval.

Lifecycle: Numbers are stored in Audact's pool, assigned to agents via the platform API, and billed through Audact's Telnyx account automatically. The platform configures the Telnyx SIP trunk connection on your behalf — you never supply connection parameters.

Teardown: Two operations exist:

• Release: Clear the agent assignment and return the number to the pool (DELETE /v1/numbers/{id}/release). The DID remains owned by Audact and is callable for future reassignment.
• Delete: Permanently remove the number and release the DID back to Telnyx's inventory (DELETE /v1/numbers/{id}). This is irreversible; the number is gone from the platform and the carrier's pool.

Connection: Automatic. You point your Telnyx account to the SIP ingress host shown in your dashboard (fetched from GET /v1/byo/config), and Audact handles the rest.

Type 2: Bring-Your-Own (BYO) Trunk

You manage the number acquisition and telephony provider relationship; Audact accepts inbound calls routed through your SIP trunk.

Acquisition: Numbers are purchased directly from your telephony provider (Twilio, Telnyx, or any generic SIP provider). You control the billing, carrier relationship, and number pool.

Lifecycle: You own the numbers and can reassign or release them at your provider's discretion. Audact does not provision, bill, or manage these DIDs — only routes calls arriving on them.

Teardown: You release numbers at your carrier. Audact simply stops routing calls to that number.

Connection: You configure the SIP trunk origination URI to point to Audact's SIP ingress (shown in your dashboard from GET /v1/byo/config). Audact validates inbound calls against your pool of configured BYO numbers and routes them to the appropriate agents.

Type 1 Setup: Audact-Provisioned Numbers

See Number Provisioning & KYC for the complete lifecycle. In summary:

1. Upload KYC documents via POST /v1/kyc/documents
2. Create a document set via POST /v1/kyc/document-sets (Telnyx approves asynchronously)
3. Once approved, place a number order via POST /v1/numbers/orders
4. Assign numbers to agents via POST /v1/numbers/{id}/assign
5. Audact configures the Telnyx SIP trunk automatically

No manual SIP trunk configuration is required for Type 1 numbers.

Type 2 Setup: Bring-Your-Own Trunks

Your SIP trunk originates calls to Audact's SIP ingress. The following sections document three common provider setups and a generic SIP template.

Querying Your SIP Ingress Configuration

Before configuring any BYO trunk, fetch your tenant's SIP ingress settings:

curl -X GET https://api.audact.ai/v1/byo/config \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response:

{
  "sip_ingress_host": "sip.us.audact.ai",
  "sip_ingress_port": 5060,
  "allowed_source_cidrs": ["203.0.113.0/24"],
  "healthy_numbers": ["+14155551234", "+14155551235"],
  "failed_numbers": []
}

Use the sip_ingress_host and sip_ingress_port below.

Connect a Twilio Trunk

Twilio's SIP Trunking product lets you originate calls to any external SIP server.

1. Create a Twilio SIP Trunk

1. Log into the Twilio Console → Elastic SIP Trunks
2. Click + to create a new trunk
3. Choose a Friendly Name (e.g., audact-sip-trunk)
4. Click Create

2. Configure the Origination URI

In the trunk settings, under Originating SIP Address:

1. Click + to add an Origination URI
2. Enter: sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (e.g., sip:sip.us.audact.ai:5060)
3. Set Priority to 10 (lower is higher priority)
4. Set Weight to 100
5. Leave Enabled checked
6. Click Add

3. Create a Credential List (if required)

If you need to send SIP authentication credentials to Audact:

1. In the trunk, scroll to Credential List
2. Click + to add credentials
3. Enter your credential list name (e.g., audact-credentials)
4. Select Credential Type: SIP Credentials
5. Enter the Username and Password (coordinate with Audact support)
6. Click Create
7. Assign the credential list to the trunk

Note: Most Twilio trunks use IP authentication (IP allowlisting) rather than credentials. Verify with your setup.

4. Configure Phone Number Routing

For each phone number you want to route through this trunk:

1. In the Twilio Console, go to Phone Numbers → Active Numbers
2. Select the number
3. Under Voice & Fax, set:
   • Configure With: SIP Trunk
   • SIP Trunk: select your newly created audact-sip-trunk
4. Save

5. Whitelist Audact IPs (Optional)

If your Twilio trunk uses IP authentication:

1. In the trunk settings, find Originating SIP Address
2. Note any IP restrictions on the Origination URI
3. Ask Audact support for the list of outbound SIP server IPs
4. Add them to your Twilio trunk's IP allowlist

Connect a Telnyx Trunk

Telnyx's SIP Trunking product is similar to Twilio. If you already have Telnyx numbers but want to use BYO trunking (rather than Audact-provisioned numbers), follow this guide.

1. Create a Telnyx SIP Connection

1. Log into the Telnyx Portal → Connections → SIP Connections
2. Click Create SIP Connection
3. Choose a Connection Name (e.g., audact-sip-connection)
4. Under Outbound, add an Originating SIP Address:
   • Enter: sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (e.g., sip:sip.us.audact.ai:5060)
5. Click Create

2. Configure Authentication

Option A: IP Authentication

1. In your Telnyx connection settings, find IP Authentication
2. Add the Audact SIP server IPs to the allowlist
3. Ask Audact support for the exact IP ranges

Option B: SIP Credentials

1. In your connection settings, under Authentication, select Username & Password
2. Enter your Username (e.g., your tenant ID or API key identifier)
3. Set a Password
4. Click Save
5. Share these credentials with Audact (securely)

3. Assign Phone Numbers

For each BYO number, assign it to the SIP connection:

1. Go to Inventory → Phone Numbers
2. Select a number
3. Under Routing, set:
   • Connection Type: SIP Connection
   • Connection: select your audact-sip-connection
4. Enter the Sip Termination URI: sip:${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT}
5. Save

4. Configure Billing

Ensure billing is set up through Telnyx directly — Audact does not bill you for BYO numbers. Telnyx invoices you for minutes, termination, and number rental.

Connect a Generic SIP Trunk

If your provider is not Twilio or Telnyx, use this generic SIP origination template.

Prerequisites

• Your SIP provider allows outbound origination to any external SIP server
• You have outbound SIP credentials or IP allowlist access
• Your provider supports E.164 phone number formatting in SIP INVITE headers

Configuration Steps

1. Add Audact as an Originating Peer in Your Provider's Portal:

   • Peer Address: ${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT} (e.g., sip.us.audact.ai:5060)
   • Protocol: SIP (UDP or TCP, coordinate with Audact)
   • Port: 5060 (default; confirm with your provider and Audact)

2. Authentication (choose one):

   Option A: IP Authentication

   • Add the public IP of your SIP server or gateway to Audact's allowlist
   • Ask Audact support for their SIP server IP range
   • Add Audact's IPs to your provider's whitelist

   Option B: Digest Authentication (Username & Password)

   • Set Username: your API key, tenant ID, or provider-assigned credential
   • Set Password: a secure secret
   • Ensure your provider sends credentials in the SIP INVITE or REGISTER
   • Share credentials with Audact support so we can validate them

3. Configure Origination Rules:

   • For each phone number, route inbound traffic to the Audact peer
   • Ensure the SIP INVITE includes the E.164-formatted number in the To header (e.g., To: <sip:+14155551234@sip.us.audact.ai>)

4. Test the Connection:

   • Verify SIP packets reach Audact by monitoring your provider's call logs
   • Check the Audact dashboard to see if the call arrives (health status should transition from unverified to healthy)

Trunk Health States

Once a BYO trunk is configured, Audact tracks its health status. Use these states to diagnose connection issues.

Health Status Meanings

Checking Trunk Status

Use the GET /v1/byo/config endpoint to view trunk health:

curl -X GET https://api.audact.ai/v1/byo/config \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response includes health_status and last_check_timestamp for each trunk.

Troubleshooting Workflow

1. Verify DNS resolution:

   bash

   nslookup ${SIP_INGRESS_HOST}

   Should resolve to your SIP server's IP.

2. Test SIP connectivity from your server:

   bash

   # Using a SIP client or tool (e.g., sipvious, sipp)
   sipp -sf register.xml ${SIP_INGRESS_HOST}:${SIP_INGRESS_PORT}

3. Check firewall rules:

   • Ensure UDP/TCP 5060 is open between your provider and Audact
   • Confirm Audact's IP range is allowlisted on your side (if using IP auth)

4. Review SIP logs:

   • Check your provider's SIP logs for INVITE rejections or timeouts
   • Check Audact's inbound SIP error logs in the dashboard

5. Test a call:

   • Place a test call from any phone to one of your BYO numbers
   • Observe the call flow in the Audact dashboard
   • Check health status: should transition from unverified → healthy after the first successful call

BYO Trunk Billing & Responsibilities

Mixing Number Types

A tenant can use both Audact-provisioned and BYO trunks simultaneously. For example:

• Assign Audact-provisioned numbers (+1415..., +44204...) to certain agents
• Route BYO numbers (+1212... from Twilio, +61... from Telnyx-as-BYO) to other agents
• Audact routes all inbound calls appropriately based on the DID

No special configuration is needed — simply configure both Types in parallel. The GET /v1/byo/config endpoint reports both Audact-managed and BYO trunks.