Deprovision a Phone Number

Phone cleanup is handled by DELETE /api/agents/:id/deprovision-phone. The implementation lives in packages/server/src/routes/telephony.route.ts and invokes deprovisionPhoneFromAgent to remove every stored SID.

When to run it

• The customer is rotating phone numbers or transferring them to a new agent.
• Provisioning failed midway and you need a clean slate before retrying.
• You're cleaning up a dev or staging agent to avoid unnecessary Twilio trunks.

Endpoint

• Method: DELETE /api/agents/{agentId}/deprovision-phone
• Authentication: Authorization: Bearer <API key>
• Body: none

curl -X DELETE http://localhost:3001/api/agents/$AGENT_ID/deprovision-phone \
  -H "Authorization: Bearer $TELLYO_API_KEY"

Response

{
  "success": true,
  "message": "Phone resources cleaned up successfully"
}

What gets deleted

1. LiveKit dispatch rule and inbound trunk (if their IDs are present on the agent row).
2. Twilio origination URL and trunk.
3. Database columns related to telephony are nulled (twilioPhoneNumber, twilioTrunkSid, phoneProvisioningStatus, etc.).

Each deletion runs in parallel. If any provider call fails, the API returns 200 but logs warnings such as Failed to delete Twilio trunk. Inspect server logs (logger.warn) when that happens, then manually clean up the leftover resource.

You can confirm the cleanup via GET /api/agents/{agentId}/phone-status, which should now return { "hasPhone": false }. Once the row is clean, run the Provision workflow again.