Developer Guide

Make Your First NextGenSwitch Call with PHP, Python or Node.js

NextGenSwitch editorial Published Jul 18, 2026

NextGenSwitch now has official SDKs for PHP, Python, and Node.js. Each SDK provides a client for the Programmable Voice API, an escaped Voice XML builder, structured errors, webhook helpers, and runnable examples.

This guide takes you from credentials to a first test call. Use a non-production NextGenSwitch deployment, test destinations you control, and HTTPS endpoints for any callback or media URL.

Before you start

You need:

a NextGenSwitch deployment;
its base URL;
an authorization code;
an authorization secret;
PHP 8.1+, Python 3.9+, or Node.js 18+;
a test source and destination that your deployment is permitted to call.

Store credentials in a secret manager or environment variables. Never commit them to Git, place them in Voice XML, or expose them in frontend JavaScript.

Choose and install an SDK

PHP

composer require nextgenswitch/nextgenswitch-php

Repository: NextGenSwitch PHP SDK

Python

Until the first PyPI release, install directly from GitHub:

pip install "nextgenswitch @ git+https://github.com/nextgenswitch/nextgenswitch-python.git"

Repository: NextGenSwitch Python SDK

Node.js and TypeScript

Until the first npm release, install directly from GitHub:

npm install github:nextgenswitch/nextgenswitch-nodejs

Repository: NextGenSwitch Node.js SDK

Always use the installation command in the selected repository README. It is the source of truth while packages move through their first registry releases.

Configure environment variables

Use the same names across all three SDKs:

export NEXTGENSWITCH_BASE_URL="https://your-switch.example.com"
export NEXTGENSWITCH_AUTHORIZATION="your-authorization-code"
export NEXTGENSWITCH_AUTHORIZATION_SECRET="your-authorization-secret"

The clients send the documented X-Authorization and X-Authorization-Secret headers. Use HTTPS for remote deployments.

Create your first call

The following examples produce a simple <Say> instruction and submit it as inline Voice XML.

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use NextGenSwitch\Client;
use NextGenSwitch\VoiceResponse;

$client = new Client(
    baseUrl: getenv('NEXTGENSWITCH_BASE_URL'),
    authorizationCode: getenv('NEXTGENSWITCH_AUTHORIZATION'),
    authorizationSecret: getenv('NEXTGENSWITCH_AUTHORIZATION_SECRET'),
);

$flow = (new VoiceResponse())->say('Hello from the NextGenSwitch PHP SDK.');

$result = $client->createCall(
    to: '2001',
    from: '1001',
    responseXml: $flow,
);

print_r($result->data());

Python

import os

from nextgenswitch import Client, VoiceResponse

client = Client(
    os.environ["NEXTGENSWITCH_BASE_URL"],
    os.environ["NEXTGENSWITCH_AUTHORIZATION"],
    os.environ["NEXTGENSWITCH_AUTHORIZATION_SECRET"],
)

flow = VoiceResponse().say("Hello from the NextGenSwitch Python SDK.")
result = client.create_call("2001", "1001", response_xml=flow)
print(result.data)

Node.js and TypeScript

import {
  NextGenSwitchClient,
  VoiceResponse,
} from "@nextgenswitch/sdk";

const client = new NextGenSwitchClient({
  baseUrl: process.env.NEXTGENSWITCH_BASE_URL!,
  authorization: process.env.NEXTGENSWITCH_AUTHORIZATION!,
  authorizationSecret: process.env.NEXTGENSWITCH_AUTHORIZATION_SECRET!,
});

const flow = new VoiceResponse()
  .say("Hello from the NextGenSwitch Node.js SDK.");

const result = await client.createCall({
  to: "2001",
  from: "1001",
  responseXml: flow,
});

console.log(result.data);

Replace 1001 and 2001 with permitted test identities in your deployment. A successful API response does not by itself prove that the destination answered, so observe call status events and switch logs.

What the SDK builds

The flow above generates XML equivalent to:

<Response>
  <Say>Hello from NextGenSwitch.</Say>
</Response>

The builders also support Play, Gather, Dial, Record, Stream, Hangup, Pause, Redirect, Bridge, and Leave. Text and attributes are escaped by the SDK instead of being concatenated into raw XML.

Review the Programmable Voice API reference for current verb attributes and callback fields.

Add call status tracking

Pass a TLS URL you control as the status callback. Treat callbacks as untrusted input: validate expected fields, restrict access where possible, and avoid logging sensitive payloads.

The current public API documentation does not define a platform callback-signature scheme. Apply deployment-appropriate authentication and network controls instead of assuming callback authenticity.

Modify an active call

Once you have a call ID, replace the active flow. A typical update can pause, speak, and dial another destination.

The SDK repositories include runnable modify-call examples:

Only modify calls your application owns. Handle the case where a call has already ended.

Record caller audio carefully

The Record verb can capture audio, trigger a callback, and optionally request transcription where the deployment supports it. Before recording, confirm applicable notice, consent, storage, retention, access, and deletion requirements.

Use the examples in each SDK and replace every example.com URL with a TLS endpoint you operate.

Stream audio to an AI service

The Stream helper creates a bidirectional WebSocket media connection. Put session identifiers in the stream parameters, but resolve AI-provider secrets on your WebSocket service. Never embed provider keys in Voice XML.

A production AI voice workflow also needs timeout handling, interruption behavior, business-tool validation, human handoff, monitoring, and a fallback when speech or model providers fail.