NNextAgent VoiceAIDocumentation
PRODUCT GUIDE

Build AI voice agents for every customer conversation.

NextAgent VoiceAI lets you configure natural AI agents, connect business knowledge and tools, handle phone calls, and add browser voice calling to any website.

START HERE

Getting started

Before a live conversation can start, make sure the account wallet has funds and the customer has at least one active AI provider configuration.

  1. Configure an LLM, STT, and TTS provider in AI Providers.
  2. Create an AI agent with a clear prompt, greeting, language, and voice.
  3. Add a knowledge base, actions, or handoff rules when needed.
  4. Activate the agent and connect it to a phone number, API workflow, or WebRTC website widget.

AI AGENTS

Create an AI agent

Each agent has its own instructions, voice, language, provider models, call duration limit, and conversation-start behavior. Keep the prompt focused on the job the agent must perform and describe when it should hand a caller to a human.

Prompt and greeting

Define the agent’s role, tone, boundaries, and opening message. Use {{variable}} placeholders for call-specific details.

Providers

Select the LLM, speech-to-text, and text-to-speech models that power this agent.

Handoff

Set a transfer target and escalation keywords for conversations that need a person.

Only active agents can start new media sessions. An agent set to Outbound cannot be used for the public WebRTC website call flow.

CONTEXT AND AUTOMATION

Knowledge bases and actions

Attach a knowledge base to give an agent grounded answers from your business material. Add agent actions when the agent needs to create a ticket, collect a lead, book an appointment, transfer a call, or invoke an approved integration.

CapabilityUse it for
Knowledge baseAnswer questions using uploaded documents or synced website content.
Agent actionsCall approved business functions with structured inputs.
IntegrationsConnect webhooks and external services to agent workflows.
Provider profilesReuse managed LLM, STT, TTS, voice, and language settings.

CONVERSATION CHANNELS

Phone calls and website voice calls

Use an active caller ID and configured switch credentials for outbound or inbound phone conversations. For a website, create a short-lived WebRTC session on your backend, then send the token to the browser for the media offer.

Outbound API call

Your server asks NextAgent VoiceAI to dial a number with an active agent and caller ID.

Inbound phone call

Attach an answered switch call to an agent assigned to the inbound DID.

WebRTC website call

Embed a browser microphone call with a short-lived session token. Never expose the customer API key.

For the full WebRTC setup—including Nginx, CORS, and browser code—see the API integration overview and the server guide in the project documentation.

NEXTGENSWITCH DID ROUTING

Receive inbound calls with a NextGenSwitch DID

Route an incoming NextGenSwitch DID to a NextAgent AI agent with a PHP VoiceResponse function. The function below also passes the caller number to NextAgent, so Call History shows the caller instead of unknown when the carrier provides caller ID.

Before you start

  1. Create and activate the AI agent in NextAgent, then copy its UUID.
  2. Create a customer API key in API Keys. Keep it server-side; it is shown only once.
  3. Confirm the NextGenSwitch DID and its trunk are active.

Create the NextGenSwitch PHP VoiceResponse function

In your NextGenSwitch call-flow PHP handler, create a function (for example, NextAgent inbound AI) and paste this code. Replace the agent UUID and customer API key before saving.

function response_xml()
{
    // NextGenSwitch provides the incoming caller ID as event_from for DID routes.
    $callerPhone = trim((string) request()->input('event_from', ''));

    $response = new VoiceResponse();

    $stream = $response
        ->connect()
        ->stream([
            'url'  => 'wss://nextagent.nextgenswitch.com/ai-media/ws',
            'name' => 'nextagent-inbound',
        ]);

    $stream->parameter([
        'name'  => 'agent',
        'value' => 'YOUR_NEXTAGENT_AGENT_UUID',
    ]);

    $stream->parameter([
        'name'  => 'ai_agents_api_key',
        'value' => 'YOUR_NEXTAGENT_CUSTOMER_API_KEY',
    ]);

    $stream->parameter([
        'name'  => 'caller_phone',
        'value' => $callerPhone,
    ]);

    $stream->parameter([
        'name'  => 'direction',
        'value' => 'inbound',
    ]);

    return $response->xml();
}

Assign it to the DID

  1. In NextGenSwitch, create or edit the inbound route for the DID.
  2. Set its destination to the PHP VoiceResponse function above.
  3. Save the route and assign it to the DID.
  4. Call the DID from a mobile phone and review NextAgent Call History.

The WebSocket URL in the code is read dynamically from this installation's configuration. If the caller is still shown as unknown, verify that NextGenSwitch received a caller ID; private/blocked caller IDs cannot be recovered. Revoke and replace any API key that has been exposed.

SERVER-TO-SERVER INTEGRATION

API integration

Create a customer API key in API Keys. Store it only in your application server environment. Your frontend receives only a short-lived session token.

Start a browser WebRTC session from your backend

POST /api/v1/nextagent/webrtc/sessions
Authorization: Bearer NEXTAGENT_CUSTOMER_API_KEY
Content-Type: application/json

{
  "agentId": "NEXTAGENT_AGENT_UUID",
  "visitorId": "customer-123",
  "variables": { "name": "Amina" },
  "metadata": { "page": "/pricing" }
}

The response contains offerUrl, sessionToken, and conversationId. The browser uses the token as X-AI-Api-Key when it posts its WebRTC offer to the media runtime.

Connect the browser microphone and play the AI audio

Call your own backend session endpoint only after the visitor presses a button. This keeps the long-lived customer API key off the browser.

<button id="start-call">Talk to us</button>
<button id="end-call" disabled>End call</button>
<audio id="agent-audio" autoplay></audio>

<script type="module">
  let peerConnection;
  let microphone;

  async function waitForIceComplete(pc) {
    if (pc.iceGatheringState === 'complete') return;
    await new Promise(resolve => pc.addEventListener(
      'icegatheringstatechange',
      () => pc.iceGatheringState === 'complete' && resolve(),
    ));
  }

  document.querySelector('#start-call').onclick = async () => {
    // This is your backend endpoint. It calls NextAgent using its server-only key.
    const session = await fetch('/api/voice-session', { method: 'POST' }).then(async response => {
      if (!response.ok) throw new Error(await response.text());
      return response.json();
    });

    microphone = await navigator.mediaDevices.getUserMedia({ audio: true });
    peerConnection = new RTCPeerConnection({
      iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
    });
    microphone.getTracks().forEach(track => peerConnection.addTrack(track, microphone));
    peerConnection.ontrack = event => {
      document.querySelector('#agent-audio').srcObject = event.streams[0];
    };

    await peerConnection.setLocalDescription(await peerConnection.createOffer());
    await waitForIceComplete(peerConnection);
    const answer = await fetch(session.offerUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-AI-Api-Key': session.sessionToken,
      },
      body: JSON.stringify(peerConnection.localDescription),
    }).then(async response => {
      if (!response.ok) throw new Error(await response.text());
      return response.json();
    });
    await peerConnection.setRemoteDescription(answer);
    document.querySelector('#start-call').disabled = true;
    document.querySelector('#end-call').disabled = false;
  };

  document.querySelector('#end-call').onclick = () => {
    peerConnection?.close();
    microphone?.getTracks().forEach(track => track.stop());
    document.querySelector('#agent-audio').srcObject = null;
    document.querySelector('#start-call').disabled = false;
    document.querySelector('#end-call').disabled = true;
  };
</script>

Production requirements

  • Set AI_AGENTS_WEBRTC_API_URL to the public HTTPS base URL of the media runtime, for example https://media.example.com.
  • Set AI_AGENTS_WEBRTC_ALLOWED_ORIGINS on the media runtime to the HTTPS domains where the widget is embedded.
  • Use HTTPS for both the website and media runtime; browsers block microphone access on ordinary HTTP sites.
  • Use STUN/TURN servers suitable for your network in production, especially for callers behind restrictive NATs.

Start an outbound AI phone call

POST /api/v1/nextagent/ai-calls
Authorization: Bearer NEXTAGENT_CUSTOMER_API_KEY
Content-Type: application/json

{
  "agentId": "NEXTAGENT_AGENT_UUID",
  "to": "8801712345678",
  "callerId": "YOUR_CONFIGURED_CALLER_ID",
  "variables": { "name": "Amina" },
  "reference": "order-123"
}

API keys are customer-scoped. Revoke and replace a key immediately if it is exposed. Do not put it in JavaScript, mobile-app bundles, or public HTML.

OBSERVABILITY

Call history, transcripts, and outcomes

Every AI conversation is recorded in Call History with its agent, channel, status, duration, transcript turns, outcome, summary, and billed cost. Use this record to audit agent behavior, monitor quality, and send outcomes to your CRM through an agent webhook.

For each completed call, the platform can store a final disposition such as callback, not interested, do-not-call, transfer, or another custom outcome selected by the agent workflow.

ACCOUNT AND USAGE

Billing and wallet

The base call rate starts at ৳1 per minute. TTS, STT, and LLM provider API usage are tracked and charged separately. Add funds to the wallet before starting billable calls, and review every charge in Call History and Wallet.