Phone Numbers

Introduction

Phone numbers are the bridge between your agents and the phone network. Chorus supports multiple telephony providers, allowing you to use your existing numbers or provision new ones.

Supported Providers

Chorus integrates with the following telephony providers:

• Twilio: Industry-leading cloud communications platform
• SIP: Standard SIP trunking for enterprise deployments (supports registration and IP allowlist modes)
• Voximplant: Cloud communications platform

Provider Comparison

Adding a Phone Number

Twilio

To add a Twilio phone number:

1. Purchase or identify a phone number in your Twilio account
2. Get your Twilio credentials:
   • Account SID
   • Auth Token
3. Add the number via API or dashboard

{
  "name": "Support Line",
  "number": "+15551234567",
  "provider": "twilio",
  "agentId": "agent-uuid",
  "twilioAccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "twilioAuthToken": "your-auth-token"
}

SIP

SIP numbers support two modes via the sipMode field:

Registration Mode (sipMode: "registration")

Our SIP server registers to your PBX using credentials:

{
  "name": "Enterprise Trunk",
  "number": "+15551234567",
  "provider": "sip",
  "sipMode": "registration",
  "agentId": "agent-uuid",
  "sipUsername": "your-username",
  "sipPassword": "your-password",
  "sipProxy": "sip.your-provider.com",
  "sipPort": 5060,
  "sipOutboundProxy": "outbound.your-provider.com",
  "sipAuthUser": "auth-username"
}

Required fields for registration mode:

• sipUsername: SIP authentication username (max 60 characters)
• sipPassword: SIP authentication password
• sipProxy: SIP registrar host (e.g., pbx.example.com)

Optional fields:

• sipPort: SIP port (default: 5060)
• sipOutboundProxy: Proxy address if SIP traffic needs to route through a proxy
• sipAuthUser: Digest auth username, if different from sipUsername

IP Allowlist Mode (sipMode: "ip_allowlist")

Your PBX connects directly using IP-based allowlisting:

{
  "name": "Enterprise Trunk",
  "number": "+15551234567",
  "provider": "sip",
  "sipMode": "ip_allowlist",
  "agentId": "agent-uuid",
  "sipIp": "203.0.113.10",
  "sipPort": 5060,
  "sipProtocol": "udp"
}

Required fields for IP allowlist mode:

• sipIp: Public IP address of your PBX/SBC

Optional fields:

• sipPort: SIP port (default: 5060)
• sipProtocol: Transport protocol - "udp", "tcp", or "tls" (default: "udp")

See the SIP Numbers guide for detailed setup instructions.

Assigning Agents

Each phone number can be assigned to a default agent. When an inbound call arrives on that number, it will be handled by the assigned agent.

{
  "agentId": "agent-uuid"
}

Inbound Call Flow

When someone calls your phone number:

1. Call arrives at your telephony provider (Twilio/SIP)
2. Provider sends webhook to Chorus platform
3. Chorus validates the number and organization
4. Platform checks organization balance (if applicable)
5. Assigned agent configuration is loaded
6. WebSocket stream is established with the agent runtime
7. Conversation begins

Additional Fields

Phone numbers also support a metadata field for storing arbitrary data:

{
  "metadata": {
    "department": "support",
    "region": "us-east"
  }
}

Outbound Calls

Use phone numbers to make outbound calls via the API:

POST /v1/calls
{
  "agentId": "agent-uuid",
  "phoneNumberId": "phone-uuid",
  "to": "+15559876543",
  "contextVariables": {
    "customer_name": "Jane Smith",
    "reason": "Follow-up on support ticket #1234"
  }
}

The call will be placed from the specified phone number using its configured provider.

API Reference

• Create Phone Number
• List Phone Numbers
• Get Phone Number
• Update Phone Number
• Delete Phone Number

Next Steps

• Learn about Agents to configure call behavior
• Explore Calls to start making calls
• Set up Webhooks for call notifications