Provision a Phone Number

This workflow is implemented in packages/server/src/routes/telephony.route.ts and packages/server/src/services/telephony.service.ts. It wires a Twilio number into a LiveKit SIP trunk, stores all SIDs on the agent row, and updates phoneProvisioningStatus.

Requirements

• Twilio credentials and verified numbers set in environment variables consumed by createTwilioClient.
• LiveKit SIP credentials configured via getLivekitConfig (see .env.example keys such as LIVEKIT_API_KEY, LIVEKIT_API_SECRET, and LIVEKIT_SIP_URI).
• The target agent must exist and not already have a phone number.

Endpoint

• Method: POST /api/agents/{agentId}/provision-phone

• Body:

  {
    "phoneNumber": "+15145551234"
  }

• Validation: phoneNumber must be E.164 (+ + country code + subscriber digits). US/Canada numbers are forced to +1 followed by exactly 10 digits, enforced by the zod schema.

Example request

curl -X POST http://localhost:3001/api/agents/$AGENT_ID/provision-phone \
  -H "Authorization: Bearer $TELLYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+15147548195"}'

Response

{
  "success": true,
  "phoneNumber": "+15147548195",
  "twilioTrunkSid": "TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "livekitInboundTrunkId": "trunk_abc123",
  "livekitDispatchRuleId": "rule_def456"
}

What happens internally

1. validateTwilioPhoneNumber confirms the number exists in your Twilio account and captures the SID.
2. A Twilio Elastic SIP Trunk and origination URL are created with your LiveKit SIP URI.
3. LiveKit inbound trunk + dispatch rule are created so SIP calls can be routed into Agent Rooms.
4. The agent row is updated with twilioPhoneNumber, twilioTrunkSid, livekitInboundTrunkId, and PhoneProvisioningStatus.PROVISIONED.
5. If any step fails, rollbackProvisioning tears down everything that was already created and marks the status as FAILED.

Use GET /api/agents/{agentId}/phone-status to inspect the saved SIDs or to check whether provisioning is complete.

Clean up or retry

Run a Deprovision when you need to release the phone number or move it to another agent.