At this stage, the code is known to work and has been thoroughly tested

2026-04-27 22:24:04 +00:00
parent a11fa3b142
commit 16feb51b12
15 changed files with 2899 additions and 0 deletions
@@ -0,0 +1,161 @@
+# 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',
+]);
+```