Nixflex - AI Voice Platform for Building AI Phone Agents

This guide takes you from zero to a working AI agent answering and making real phone calls. You’ll need:

A Nixflex account
A Twilio or Telnyx account with at least one phone number
A way to make a test call (any mobile phone)

Nixflex is bring your own carrier. Your numbers stay in your own Twilio or Telnyx account, you pay the carrier directly, and Nixflex never marks up or resells them. Everything below works the same on either carrier.

Step 1 - Get your API key

Open dashboard.nixflex.com and sign in. An API key is created for your account automatically.

Reveal your key

Go to API Keys, click Reveal, and copy the full credential. It looks like:

nxf_a1b2c3...:nxfs_x1y2z3...

Use it in requests

Authenticate every API call with:

Authorization: Bearer nxf_xxx:nxfs_xxx

Treat your full credential like a password. Never commit it to source control or expose it in client-side code. If it leaks, rotate immediately from the dashboard.

Building in JavaScript or TypeScript? npm install nixflex gives you typed methods for every endpoint below, with retries and error handling built in. See Using the SDK.

Step 2 - Create an agent

An agent is the AI personality that answers calls. Each agent has a prompt, voice, language, and behaviour settings.

curl -X POST https://api.nixflex.com/v1/agents \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Receptionist",
    "system_prompt": "You are a friendly receptionist for Acme Dental. Greet callers, answer questions about opening hours (Mon-Fri 9am-5pm), and book appointments by collecting name and preferred date.",
    "welcome_message": "Hello, Acme Dental, how can I help?"
  }'

The response contains your agent_id:

{
  "agent_id": "agent_125207e452f8714a",
  "name": "Test Receptionist",
  "voice_id": "Ashley",
  "language": "multi",
  "is_active": true
}

Save the agent_id - you’ll attach a phone number to it next.

The default voice is Ashley and the default language is multi. A multi agent starts in the language your instructions are written in and will offer to switch if the caller speaks another one. To lock an agent to a single language - including Arabic, Hebrew, Korean, Chinese or Polish - set language to that code. See Languages.

Step 3 - Connect a phone number

You import a number you already own. Nixflex works out which carrier it is from the credentials you send - there is no provider field to set.

Set the number up in your carrier account first. Nixflex cannot fix a number that is not provisioned, not voice-enabled, or blocked from your destination countries. If a call fails, the error usually names the carrier setting to change.Carrier consoles also change. Twilio and Telnyx both redesign screens and update policies from time to time, so field names may not match this page exactly. The values Nixflex needs do not change - if a screen looks different, follow your carrier’s own current documentation.

Twilio
Telnyx

Buy a voice-enabled number in your Twilio console, then import it with your Account SID and Auth Token:

curl -X POST https://api.nixflex.com/v1/phone-numbers \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+447446466847",
    "twilio_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "twilio_token": "your_twilio_auth_token",
    "agent_id": "agent_125207e452f8714a"
  }'

Nixflex points that number’s webhooks at the engine. Nothing else to configure.

Full guide: Twilio.

Telnyx needs three things set up in your portal first, because its webhook lives on an application rather than on the number:

Buy or port a voice-enabled number.
Create a TeXML Application - set its voice webhook to https://api.nixflex.com/telnyx-voice, method POST, webhook API version 2. Copy the application ID.
Assign your number to that application, and enable the G711U codec on it (disable HD Voice / G722).
Create an API key with access to the number.

Then import, using the API key and the application ID:

curl -X POST https://api.nixflex.com/v1/phone-numbers \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+443301901028",
    "telnyx_api_key": "KEY0123456789...",
    "telnyx_connection_id": "2512345678901234567",
    "agent_id": "agent_125207e452f8714a"
  }'

Full guide, with the reasoning behind each step: Telnyx.

Prefer clicking to curl? The dashboard does the same thing under Phone Numbers, with a Twilio / Telnyx toggle.

Step 4 - Test inbound

Call your number from any phone. The agent will:

Pick up
Say your welcome message
Listen, respond, handle interruptions naturally
Hang up when the conversation ends or when the caller stops talking

Step 5 - Test outbound

Have the agent call you. Replace the to_number with your mobile.

curl -X POST https://api.nixflex.com/v1/calls/outbound \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_125207e452f8714a",
    "to_number": "+44YOUR_MOBILE",
    "prompt": "You are calling from Acme Dental to check the person can still make their appointment tomorrow at 2pm."
  }'

Your phone rings within seconds. Pick up and talk to your agent.

prompt is required on every outbound call - it is the whole brief for that call, and the agent’s own instructions are NOT used on outbound. You don’t pass a from_number: the engine uses the number you assigned to the agent in Step 3. Outbound works on both carriers. See Outbound calls.

Step 6 - Read the call back

After the call ends, pull the details:

curl https://api.nixflex.com/v1/calls \
  -H "Authorization: Bearer YOUR_KEY"

The response includes the transcript, recording URL, post-call summary, caller sentiment, and any custom data the agent extracted. See List calls for every field.

Using the SDK

The official Node.js SDK wraps every endpoint in this guide, so you get typed methods, automatic retries on rate limits, and typed errors instead of raw HTTP.

npm install nixflex

The whole flow above, in JavaScript:

import Nixflex from 'nixflex';

const client = new Nixflex({ apiKey: process.env.NIXFLEX_API_KEY });   // "nxf_xxx:nxfs_xxx"

// Step 2 - create an agent
const agent = await client.agents.create({
  name: 'Test Receptionist',
  system_prompt: 'You are a friendly receptionist for Acme Dental...',
  welcome_message: 'Hello, Acme Dental, how can I help?',
});

// Step 3 - connect a number you already own
await client.phoneNumbers.import({
  phone_number: '+447446466847',
  agent_id: agent.agent_id,
  twilio_sid: process.env.TWILIO_SID,
  twilio_token: process.env.TWILIO_TOKEN,
});

// Step 5 - place an outbound call
await client.calls.create({
  agent_id: agent.agent_id,
  to_number: '+447386172392',
  prompt: 'Confirm the appointment for tomorrow at 2pm.',
});

// Step 6 - read the call back
const [latest] = await client.calls.list({ limit: 1 });
console.log(latest.transcript);

Errors arrive as typed classes you can branch on:

import { NixflexRateLimitError, NixflexPaymentRequiredError } from 'nixflex';

try {
  await client.calls.create({ /* ... */ });
} catch (err) {
  if (err instanceof NixflexRateLimitError) {
    console.log(`Retry in ${err.retryAfterSeconds}s`);
  } else if (err instanceof NixflexPaymentRequiredError) {
    console.log('Top up your balance');
  }
}

Source and full method list: github.com/nixflex/nixflex-node - published on npm. Requires Node 18 or newer, and has no runtime dependencies.

What’s next

Telephony setup

Full carrier guides for Twilio and Telnyx, including what each one supports.

Agent actions

Let your agent transfer calls, send SMS, and end calls using prompt tags.

Webhooks

Receive post-call data in your own systems automatically.

Custom functions

Let the agent call your APIs mid-call (lookup, booking, payments).

Node.js SDK

The same calls as typed methods with retries and errors handled.

CLI and MCP

Do all of this from a terminal, or from Claude Desktop with the MCP server.

Get started

Guides

Best practices

Core concepts

In-call actions

Features

Bring your own

SMS

Reference

Quickstart

Step 1 - Get your API key

Step 2 - Create an agent

Step 3 - Connect a phone number

Step 4 - Test inbound

Step 5 - Test outbound

Step 6 - Read the call back

Using the SDK

What’s next

Telephony setup

Agent actions

Webhooks

Custom functions

Node.js SDK

CLI and MCP

​Step 1 - Get your API key

​Step 2 - Create an agent

​Step 3 - Connect a phone number

​Step 4 - Test inbound

​Step 5 - Test outbound

​Step 6 - Read the call back

​Using the SDK

​What’s next

Telephony setup

Agent actions

Webhooks

Custom functions

Node.js SDK

CLI and MCP

Step 1 - Get your API key

Step 2 - Create an agent

Step 3 - Connect a phone number

Step 4 - Test inbound

Step 5 - Test outbound

Step 6 - Read the call back

Using the SDK

What’s next