php-voip.ms/docs/library.md

Library Usage

The CLI uses the same client class that application code can use directly.

<?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.');
}

foreach ($response->data()['phonebook_groups'] ?? [] as $group) {
    echo $group['phonebook_group'] . ' ' . $group['name'] . PHP_EOL;
}

If a command does not have a convenience method yet, use the generic request method:

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

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

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

Convenience Methods

General:

$client->getBalance();
$client->getBalance(advanced: true);
$client->getDidsInfo();
$client->getDidsInfo('5551234567');

Phonebook:

$client->getPhonebook();
$client->getPhonebookByGroup('16389');
$client->getPhonebookByGroupName('Spam');
$client->getPhonebookGroups();
$client->findPhonebookGroupByName('Spam');
$client->findOrCreatePhonebookGroup('Spam');
$client->findPhonebookEntriesByNumber('5553334444');
$client->setPhonebook([
    'name' => 'Jane Smith',
    'number' => '5553334444',
    'group' => '16389',
]);
$client->deletePhonebook('32207');
$client->setPhonebookGroup('Spam');
$client->deletePhonebookGroup('16389');

To add a number to a named group without creating duplicate entries:

$result = $client->addNumberToPhonebookGroup(
    number: '5553334444',
    groupName: 'Spam',
    name: 'Spam Caller',
    note: 'Marked by automation',
);

if ($result->changed()) {
    echo 'Added entry IDs: ' . implode(', ', $result->addedEntryIds()) . PHP_EOL;
}

The helper creates the group if needed, reuses existing phonebook entries for the same number when possible, and only creates a new phonebook entry when the number does not already exist.

Removing a number from a group is a group membership update. VoIP.ms stores group members as phonebook entry IDs, and it may allow duplicate phonebook entries for the same number. The helper below removes every entry in the group whose number matches, but keeps the phonebook entries themselves:

$result = $client->removePhonebookNumberFromGroup('16389', '5553334444');

echo 'Removed IDs: ' . implode(', ', $result->removedEntryIds()) . PHP_EOL;

if (!$result->response()->successful()) {
    throw new RuntimeException($result->response()->message() ?? 'Group update failed.');
}

If you already know the phonebook entry IDs to remove:

$client->removePhonebookEntriesFromGroup('16389', ['32207', '32208']);

Only pass deleteMatchedEntries: true when you want to delete those phonebook entries from the account entirely after removing them from the group:

$client->removePhonebookNumberFromGroup('16389', '5553334444', deleteMatchedEntries: true);

Caller ID filtering:

$client->getCallerIdFiltering();
$client->setCallerIdFiltering([
    'callerid' => 'p:16389',
    'did' => 'all',
    'routing' => 'sys:busy',
    'note' => 'Spam group',
]);
$client->deleteCallerIdFiltering('18915');

Call records and SMS:

$client->getAccounts();
$client->getCallAccounts();
$client->getCdr('2026-04-01', '2026-04-20', '-4', [
    'calltype' => 'incoming',
    'callbilling' => 'all',
]);
$client->getCallRecordings('all', '2026-04-01', '2026-04-20');
$client->getCallRecording('100000_VoIP', '<value-from-getCallRecordings>');
$client->sendCallRecordingEmail('100000_VoIP', 'you@example.com', '<value-from-getCallRecordings>');
$client->sendSms('5551234567', '5553334444', 'Hello');

getAccounts() is a friendly alias for VoIP.ms getCallAccounts. It does not list VoIP.ms portal login users. It returns account filter values such as all or subaccount identifiers like 100000_VoIP; use the returned value field as the account argument for getCdr(), getCallRecordings(), getCallRecording(), and sendCallRecordingEmail().

getCdr() defaults to all call statuses (answered, noanswer, busy, and failed) because the VoIP.ms API rejects requests where none of those flags are set. Pass one or more status filters to narrow the result:

$client->getCdr('2026-04-01', '2026-04-20', '-4', [
    'answered' => '1',
]);