Jason Thistlethwaite
162 lines
4.4 KiB
Markdown
162 lines
4.4 KiB
Markdown
# Library Usage
|
|
|
|
The CLI uses the same client class that application code can use directly.
|
|
|
|
```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.');
|
|
}
|
|
|
|
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:
|
|
|
|
```php
|
|
$response = $client->request('getDIDsInfo', ['did' => '5551234567']);
|
|
```
|
|
|
|
For backwards compatibility with the CLI, `call()` still returns the older array shape:
|
|
|
|
```php
|
|
$result = $client->call('getBalance');
|
|
echo $result['raw'];
|
|
```
|
|
|
|
## Convenience Methods
|
|
|
|
General:
|
|
|
|
```php
|
|
$client->getBalance();
|
|
$client->getBalance(advanced: true);
|
|
$client->getDidsInfo();
|
|
$client->getDidsInfo('5551234567');
|
|
```
|
|
|
|
Phonebook:
|
|
|
|
```php
|
|
$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:
|
|
|
|
```php
|
|
$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:
|
|
|
|
```php
|
|
$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:
|
|
|
|
```php
|
|
$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:
|
|
|
|
```php
|
|
$client->removePhonebookNumberFromGroup('16389', '5553334444', deleteMatchedEntries: true);
|
|
```
|
|
|
|
Caller ID filtering:
|
|
|
|
```php
|
|
$client->getCallerIdFiltering();
|
|
$client->setCallerIdFiltering([
|
|
'callerid' => 'p:16389',
|
|
'did' => 'all',
|
|
'routing' => 'sys:busy',
|
|
'note' => 'Spam group',
|
|
]);
|
|
$client->deleteCallerIdFiltering('18915');
|
|
```
|
|
|
|
Call records and SMS:
|
|
|
|
```php
|
|
$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:
|
|
|
|
```php
|
|
$client->getCdr('2026-04-01', '2026-04-20', '-4', [
|
|
'answered' => '1',
|
|
]);
|
|
```
|