Skip to main content
Nixflex uses a bring-your-own-Twilio (BYO) model. You buy and own phone numbers in your Twilio account. Nixflex configures the webhooks on those numbers so calls route to the engine — but the numbers (and Twilio billing) stay with you.

​
Why BYO Twilio

You own the numbers

Numbers stay in your Twilio account. If you ever leave Nixflex, you keep them.

No platform markup

You pay Twilio’s wholesale prices directly. Nixflex doesn’t mark up call or SMS costs.

Multi-tenant ready

One Nixflex agent can serve unlimited phone numbers — one per end-customer if you resell.

Skip A2P 10DLC blocks

For US SMS, your A2P registration applies. We don’t get in the way.

​
Importing a number

Import a Twilio number into an agent: 
curl -X POST https://api.nixflex.com/v1/phone-numbers \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+447446466847",
    "twilio_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "twilio_token": "your_twilio_auth_token",
    "agent_id": "agent_125207e452f8714a"
  }'
What this does, behind the scenes:
  1. Validates the phone format and Twilio SID format
  2. Verifies the number exists in your Twilio account using the credentials you sent
  3. Confirms the agent belongs to your Nixflex account
  4. Overwrites Twilio’s webhooks on that number (voice, SMS, status callbacks) to point at Nixflex
  5. Inserts a phone_numbers row linking number → agent → API key
After this, calls to that number land on the agent automatically.
Importing a number overwrites any existing webhooks on that Twilio number. If you have other systems using the number, they will stop receiving calls.

​
Multi-number, single-agent pattern

A single agent can be attached to many numbers. This is how reseller apps work: 
agent_ringback_dental (one prompt, one personality)
  ├── +442011110001 → Smile Dental Croydon
  ├── +442011110002 → Pearly Whites Manchester
  ├── +442011110003 → Bright Bite Leeds
  └── +442011110004 → ... 200 more
Each number can carry its own custom_prompt (a business profile - see below), so the same agent template answers as a different business per number. On top of that, per-customer context also comes from:
  • Which phone number was dialled (engine looks up the row)
  • Any past call history for the caller’s number (auto-fetched into the agent’s prompt)
This pattern is how Ringback runs 200 dental clinics on one agent template.

​
Per-number prompt (business profile)

Each phone_numbers row can hold a custom_prompt - a business profile for that specific number. It layers on top of the agent’s prompt:
  • Agent prompt = the shared template (how to behave - e.g. “a friendly receptionist”). Set by you, the developer.
  • Per-number prompt = the specific business identity (name, address, hours, services) for that number. Different per end-customer.
When a call or SMS arrives, the engine appends the number’s custom_prompt as a BUSINESS PROFILE section. If it conflicts with the general agent prompt, the number’s details win. If a number has no custom_prompt, the agent prompt is used alone - so direct single-business agents are unaffected. This applies to both inbound calls and inbound SMS replies, so a reseller’s end-customer answers consistently across voice and text.
Set custom_prompt in the body when importing a number, or update it anytime with PATCH /v1/phone-numbers/:phoneNumber and body { "custom_prompt": "..." } (send null or an empty string to clear it - the number then falls back to the agent prompt alone). Maximum 8000 characters. Outbound calls use the per-call prompt instead (see Create outbound call).

​
Other per-number settings

The per-number model goes beyond the business profile. Several settings are configured per phone number, not per agent - so each number on a shared agent can behave differently:
SettingWhat it does per numberWhere
VoiceEach number can use its own voice (inbound and outbound). Falls back to the agent’s voice if unset.Voices
WebhookEach number can POST call data to its own endpoint.Webhooks
Cal.com calendarEach number books into its own connected calendar.Cal.com
Business profile (prompt)Each number’s identity layered over the agent prompt (above).This page
The engine resolves all of these from the number involved in the call - the dialled number for inbound, the from_number for outbound. A number with none of these set simply uses the agent’s defaults. This is what lets one agent serve many end-customers, each with their own voice, calendar, and webhook.

​
Listing numbers

# All numbers
curl https://api.nixflex.com/v1/phone-numbers \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET"

# Filter by agent
curl "https://api.nixflex.com/v1/phone-numbers?agent_id=agent_xxx" \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET"
Returns numbers sorted by creation date, newest first.

​
Removing a number

curl -X DELETE https://api.nixflex.com/v1/phone-numbers/+447446466847 \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET"
This clears Twilio’s webhooks (so calls stop routing to Nixflex) and removes the row from our database.
Deleting a number from Nixflex does not release it from Twilio. The number stays in your Twilio account and continues to bill until you release it via Twilio’s API or console. This is intentional — releasing is a permanent billing decision and stays with you.

​
Using multiple Twilio accounts

Each phone number stores its own Twilio Account SID and Auth Token. This means a single Nixflex account can serve numbers from multiple Twilio accounts — for example:
  • A UK Twilio account for +44 numbers
  • A US Twilio account for +1 numbers
  • A separate Twilio subaccount per client (recommended for agencies)
When a call comes in or goes out, Nixflex automatically uses the right Twilio credentials based on the phone number involved. No configuration needed.
Best practice: use a Twilio Subaccount per client rather than your master account. This limits the blast radius if credentials are ever exposed and gives you per-client billing on Twilio.

​
Constraints

  • One number, one agent. A phone number can be attached to only one agent at a time. To move a number to a different agent, delete the existing record first then re-import.
  • Strict number matching. Twilio’s number search uses prefix matching; Nixflex performs a strict equality check after lookup to prevent accidental imports.
  • Account scope. You can only see and manage numbers belonging to your API key. Cross-account access is blocked.

​
Errors

See the Import phone number API reference for the full list of error codes (invalid_phone_format, agent_not_owned, number_already_imported, etc.).