php-voip.ms/README.md

# 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:

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

## Authentication

The CLI reads credentials from environment variables:

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

Credentials can also be passed directly:

```bash
./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:

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

Examples:

```bash
./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:

```bash
./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:

```bash
./voipms-cli.php help
```

Command help works in both directions:

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

List locally documented commands:

```bash
./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:

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

After sourcing it, command completion works for both:

```bash
./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:

```bash
./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:

```bash
./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:

```bash
./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:

```bash
./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
<?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:

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

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

```php
$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:

```php
$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:

```bash
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:

```text
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:

```bash
./voipms-cli.php help
```