Quickstart: place your first AI voice agent phone call with the API

This picks up where Get started leaves off. You need an API key, some credit and a SIP trunk; the first two take a minute in the dashboard.

export WIXZEL_API_KEY="wv_live_..."

Wixzel Voice does not resell telephony, so your carrier rates stay yours.

Building for a website or a mobile app rather than a phone line? You need no trunk and no number: create the agent in step 3, then follow Realtime: web and mobile.

Every step below is shown three ways: as a raw HTTP request, and through the two official SDKs. Install whichever you want before you start.

npm install wixzel-voice

dart pub add wixzel_voice

TypeScript

import { WixzelVoice } from 'wixzel-voice';

const client = new WixzelVoice({ apiKey: process.env.WIXZEL_API_KEY! });

Dart

import 'package:wixzel_voice/wixzel_voice.dart';

final client = WixzelVoice(apiKey: Platform.environment['WIXZEL_API_KEY']!);

Connect your SIP trunk

Your carrier’s credentials. The password is stored encrypted and is never returned by the API again, including to you.

curl https://api.voice.wixzel.com/v1/sip-trunks \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My carrier",
    "host": "sip.carrier.example",
    "username": "acct123",
    "password": "…"
  }'

const trunk = await client.sipTrunks.create({
  name: 'My carrier',
  host: 'sip.carrier.example',
  username: 'acct123',
  password: process.env.CARRIER_PASSWORD!,
});

final trunk = await client.sipTrunks.create(CreateSipTrunk(
  name: 'My carrier',
  host: 'sip.carrier.example',
  username: 'acct123',
  password: Platform.environment['CARRIER_PASSWORD']!,
));

curl https://api.voice.wixzel.com/v1/phone-numbers \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550100",
    "sip_trunk_id": "st_01HXYZ"
  }'

const number = await client.phoneNumbers.create({
  phone_number: '+14155550100',
  sip_trunk_id: trunk.id,
});

final number = await client.phoneNumbers.create(CreatePhoneNumber(
  phoneNumber: '+14155550100',
  sipTrunkId: trunk.id,
));

Give it an inbound_agent_id and inbound calls to this number are answered automatically.No number yet? If the trunk was connected to Twilio, Telnyx, Plivo, Vobiz or Vonage in one step, you can buy one on your own carrier account with POST /v1/phone-numbers/purchase instead. Your carrier bills it at its price. See Buying a number.

Create an agent

Name the models you want. Call GET /v1/engines for what is available and what each costs. See Voice engines.

curl https://api.voice.wixzel.com/v1/agents \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "system_prompt": "You are a concise support agent.",
    "opening_message": "Hi, how can I help?",
    "outbound_phone_number_id": "pn_01HXYZ",
    "voice": {
      "stt": { "model": "deepgram/nova-3" },
      "llm": { "model": "openrouter/gpt-4o-mini" },
      "tts": { "model": "elevenlabs/eleven_flash_v2_5" }
    }
  }'

const agent = await client.agents.create({
  name: 'Support',
  system_prompt: 'You are a concise support agent.',
  opening_message: 'Hi, how can I help?',
  outbound_phone_number_id: number.id,
  voice: {
    stt: { model: 'deepgram/nova-3' },
    llm: { model: 'openrouter/gpt-4o-mini' },
    tts: { model: 'elevenlabs/eleven_flash_v2_5' },
  },
});

final agent = await client.agents.create(CreateAgent(
  name: 'Support',
  systemPrompt: 'You are a concise support agent.',
  openingMessage: 'Hi, how can I help?',
  outboundPhoneNumberId: number.id,
  voice: VoiceConfig.composed(
    stt: const SttConfig(model: 'deepgram/nova-3'),
    llm: const LlmConfig(model: 'openrouter/gpt-4o-mini'),
    tts: const TtsConfig(model: 'elevenlabs/eleven_flash_v2_5'),
  ),
));

opening_message is required. An agent without one answers in silence, and we would rather ask than invent its first words.

outbound_phone_number_id is the number from step 2, and it becomes the caller ID of every call this agent places. Leave it out and each call in step 4 needs a from_number_id instead, or it is refused with 400 no_outbound_number.

Place a call

curl https://api.voice.wixzel.com/v1/calls \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "agent_id": "ag_01HXYZ"
  }'

const call = await client.calls.create({
  to: '+14155551234',
  agent_id: agent.id,
});

final call = await client.calls.create(CreateCall(
  to: '+14155551234',
  agentId: agent.id,
));

Both SDKs generate the Idempotency-Key for you on calls, test calls and top-ups, so the warning below is about the raw HTTP call.

Idempotency-Key is required here. A network timeout tells you nothing about whether the call was placed. Without the key your only options are retrying and dialling twice, or not retrying and losing the call.

See what it cost

Every micro debited against a call is explained by a usage row, so you never have to reconcile a total by hand.

curl "https://api.voice.wixzel.com/v1/usage/events?session_id=sip-4f2a" \
  -H "Authorization: Bearer $WIXZEL_API_KEY"

const events = await client.usage.events({ session_id: 'sip-4f2a' });

final events = await client.usage.events(sessionId: 'sip-4f2a');

Component	Model	Quantity	Cost
`stt`	deepgram/nova-3	187 s	$0.0336
`llm`	openrouter/gpt-4o-mini	8.2k tokens	$0.0031
`tts`	elevenlabs/eleven_flash_v2_5	1.4k chars	$0.0980
`platform_fee`	orchestration	4 min	$0.0480
		Total	$0.2714

Running out of credit

Credit is reserved before the call is placed, so an underfunded account is refused with 402 before any resources are allocated. Mid-call, the agent warns your caller about a minute out and speaks a closing line before hanging up. It does not drop the line mid-sentence.

Getting started

Guides

Carriers

Concepts

API reference

Quickstart: place your first AI voice agent phone call with the API

See what it cost

Running out of credit

​See what it cost

​Running out of credit

See what it cost

Running out of credit