VoIP.ms PHP Client and CLI

This project provides a small PHP library and command-line tool for working with the VoIP.ms REST/JSON API.

The goal is to make common VoIP.ms automation tasks easy from shell scripts, cron jobs, and PHP applications, while still allowing direct access to any raw API method when a command has not been wrapped yet.

VoIP.ms API documentation:

https://voip.ms/m/apidocs.php

What Is Included

• voipms-cli.php: an executable CLI for calling VoIP.ms API methods.
• src/VoipMsClient.php: a reusable PHP client class.
• src/VoipMsResponse.php: a response wrapper for library callers.
• src/PhonebookGroupUpdateResult.php: a result object for phonebook group membership updates.
• src/PhonebookGroupEnsureResult.php: a result object for finding or creating phonebook groups.
• src/PhonebookNumberGroupResult.php: a result object for idempotently adding numbers to phonebook groups.
• docs/library.md: PHP library usage examples.
• docs/mcp.md: test MCP server usage and curl examples.
• bin/serve-mcp.sh: launcher for a network-accessible test MCP server.
• mcp/http-server.php: dependency-free HTTP JSON-RPC MCP endpoint.
• phonebook.php: the original simple cURL example, intentionally left as a reference.

The CLI and library both talk to the same VoIP.ms endpoint:

https://voip.ms/api/v1/rest.php

Authentication

The CLI reads credentials from environment variables:

export VOIPMS_API_USERNAME='you@example.com'
export VOIPMS_API_PASSWORD='your-api-password'

Credentials can also be passed directly:

./voipms-cli.php getBalance --username you@example.com --password your-api-password

The endpoint can be overridden with VOIPMS_API_ENDPOINT or --endpoint.

CLI Overview

The CLI can call any VoIP.ms API method:

./voipms-cli.php <method> key=value

Examples:

./voipms-cli.php getBalance
./voipms-cli.php getDIDsInfo
./voipms-cli.php getSMS date_from=2026-04-01 date_to=2026-04-20 did=5551234567
./voipms-cli.php sendSMS did=5551234567 dst=5553334444 message="Hello"

Use --dry-run to see the method and parameters without making an API request:

./voipms-cli.php getPhonebook Spam --dry-run

Output format defaults to pretty JSON. Use --format json for compact JSON or --format raw for the raw API response.

Help And Discovery

General help:

./voipms-cli.php help

Command help works in both directions:

./voipms-cli.php help getCDR
./voipms-cli.php getCDR help

List locally documented commands:

./voipms-cli.php list

The CLI includes local help for the API areas most useful for small business automation, but the generic method caller can still call raw VoIP.ms methods that do not have local help yet.

Bash Completion

The CLI can generate bash completion code:

source <(./voipms-cli.php completion bash)

After sourcing it, command completion works for both:

./voipms-cli.php <TAB><TAB>
voipms-cli.php <TAB><TAB>

Supported API Areas

The current local command catalog covers:

• Account balance, public IP, server info, and transaction history.
• Subaccounts and registration status.
• Call detail records, call account filters, call billing filters, and call type filters.
• Call recordings, recording download, and recording email.
• DIDs, DID routing, DID information, CNAM lookup, and Caller ID prefix.
• Forwarding rules, including Caller ID override.
• Phonebook entries and phonebook groups.
• CallerID Filtering rules.
• SMS and MMS retrieval and sending.
• Voicemail setup lookup.
• Fax message lookup, PDF retrieval, and fax sending.
• e911 lookup and validation.
• Local Number Portability status and listing.

Friendlier Commands

Some VoIP.ms API methods have awkward parameters. The CLI includes friendlier handling for the rougher ones.

Call detail records can be queried with the cdr alias:

./voipms-cli.php cdr 2026-04-01 2026-04-20 --timezone=-4

The alias maps normal option names to the VoIP.ms parameter names and defaults to all call statuses (answered, noanswer, busy, and failed) because the API requires at least one status flag.

Phonebook lookups also accept practical shortcuts:

./voipms-cli.php getPhonebook
./voipms-cli.php getPhonebook 16389
./voipms-cli.php getPhonebook Spam
./voipms-cli.php getPhonebookGroups
./voipms-cli.php getPhonebookGroups Spam

For getPhonebook, a bare numeric argument is treated as a phonebook group ID. A bare text argument is treated as a group name.

Phonebook And Caller ID Workflows

Phonebook group membership is handled by VoIP.ms as a semicolon-separated list of phonebook entry IDs. A group can exist even when it has no entries, and the API may allow duplicate entries for the same number.

Common commands:

./voipms-cli.php getPhonebookGroups
./voipms-cli.php getPhonebook Spam
./voipms-cli.php setPhonebook name="Jane Smith" number=5553334444 group=16389
./voipms-cli.php setPhonebookGroup group=16389 name=Spam members="32207;32208"
./voipms-cli.php delPhonebook phonebook=32207
./voipms-cli.php delPhonebookGroup group=16389

CallerID Filtering commands are also included:

./voipms-cli.php getCallerIDFiltering
./voipms-cli.php setCallerIDFiltering callerid=p:16389 did=all routing=sys:busy note="Spam group"
./voipms-cli.php delCallerIDFiltering filtering=18915

Library Overview

The CLI is built on the reusable VoipMs\VoipMsClient class. The client can be used directly in PHP scripts:

<?php

require __DIR__ . '/src/VoipMsClient.php';

use VoipMs\VoipMsClient;

$client = new VoipMsClient(
    getenv('VOIPMS_API_USERNAME'),
    getenv('VOIPMS_API_PASSWORD'),
);

$response = $client->getPhonebookGroups();

if (!$response->successful()) {
    throw new RuntimeException($response->message() ?? 'VoIP.ms request failed.');
}

print_r($response->data());

The generic library API is:

$response = $client->request('getDIDsInfo', ['did' => '5551234567']);

For compatibility with the CLI internals, call() still returns the older array shape:

$result = $client->call('getBalance');
echo $result['raw'];

Convenience methods are available for common workflows, including balance, DID lookup, CDR lookup, phonebook management, CallerID Filtering, call account filters, and SMS sending. See docs/library.md for examples.

The library also includes helpers for safer phonebook group membership changes:

$result = $client->addNumberToPhonebookGroup('5553334444', 'Spam');
$result = $client->removePhonebookNumberFromGroup('16389', '5553334444');
echo implode(', ', $result->removedEntryIds());

These helpers are standalone library features. They create or reuse phonebook groups and entries where appropriate, avoid adding duplicate group membership, and can remove matching phonebook entry IDs from a group without deleting the entries themselves.

For call detail records and call recordings, getAccounts is provided as a friendly alias for VoIP.ms getCallAccounts. It returns account filter values, not VoIP.ms portal login users. Use the returned value field as the account argument for CDR and call recording commands.

Test MCP Server

For remote-agent testing, the project includes a small HTTP JSON-RPC MCP server that wraps the standalone PHP library. It is meant for development and should be run behind a trusted network, firewall, VPN, or tunnel.

Start it with:

export VOIPMS_API_USERNAME='you@example.com'
export VOIPMS_API_PASSWORD='your-api-password'
export MCP_AUTH_TOKEN='choose-a-long-random-token'

./bin/serve-mcp.sh

By default it listens on:

http://0.0.0.0:8787/mcp

The server exposes narrow tools for balance lookup, phonebook groups, phonebook entries, CallerID Filtering, CDR lookup, and dry-run-safe phonebook group mutations. See docs/mcp.md for curl examples and tool details.

Requirements

• PHP 8.1 or newer.
• PHP curl extension.
• PHP json extension.

Composer metadata is included for PSR-4 autoloading and bin registration, but the CLI can run directly without Composer:

./voipms-cli.php help