Bring Your Own Number
Register a phone number you already own (Twilio, Telnyx or your own SIP trunk) so your agents can use it.
Register a number from your own Twilio account, your own Telnyx account, or any SIP trunk. Numbers you bring yourself cost nothing on Trillet (monthlyPrice is 0). After registering, bind an agent to it with Update Phone Number Configuration.
A number can be registered only once across all of Trillet.
Your role needs the phone_number:create permission. Otherwise the request fails with 403 {"error": "Insufficient permissions"}.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Request Body
phoneNumberstringrequiredThe number to register, in E.164 format, for example +14155550123.
providerstringrequiredtwilio, telnyx or sip.
credentialsobjectrequiredThe credentials for the provider. Always send an object, even an empty one.
workspaceIdstringOptional. If sent, it must equal x-workspace-id, otherwise the request fails with 403.
Response Fields
The response status is 201.
messagestring<provider> phone number registered successfully.
phoneNumberstringThe registered number.
idstringThe new phone number's _id. Use it as phoneNumberId in Update Phone Number Configuration.
statusstringAlways active in this response. A Twilio number is stored as ready until you bind an agent to it; check the stored value with List Phone Numbers.
monthlyPricenumberAlways 0.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "Phone number, provider type, and workspace ID are required."} | phoneNumber or provider missing |
400 | {"error": "Invalid workspace ID", "message": "..."} | x-workspace-id missing or malformed |
403 | {"error": "workspaceId in the request body does not match x-workspace-id."} | Body workspaceId differs from the header |
500 | {"error": "..."} | Any other failure, with the reason in error |
Example Request
{
"phoneNumber": "+14155550123",
"provider": "twilio",
"credentials": {
"accountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"authToken": "your_twilio_auth_token"
}
}{
"phoneNumber": "+14155550123",
"provider": "sip",
"credentials": {
"sipUri": "sip:pbx.example.com",
"username": "trillet",
"password": "your_sip_password",
"ipAddresses": [
{ "id": "pbx-1", "ip": "203.0.113.10", "subnetMask": "32" }
],
"sipType": "direct"
}
}Example Response
{
"message": "twilio phone number registered successfully",
"phoneNumber": "+14155550123",
"id": "a4a4a4a4a4a4a4a4a4a4a4a4",
"status": "active",
"monthlyPrice": 0
}Last updated on