### Install SerwerSMS PHP Client via Composer

Source: https://github.com/serwersmspl/serwersms-php-api-v2/blob/master/README.md

Instructions for installing the SerwerSMS PHP client library using Composer. This is the recommended method for managing project dependencies.

```bash
composer require serwersms/serwersms-php-client
```

--------------------------------

### Initialize SerwerSMS Client

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Instantiate the main SerwerSMS object using your Bearer API token. Ensure you have Composer installed and the autoloader included.

```php
<?php
require_once('vendor/autoload.php');

try {
    $token = 'twoj_token_api_bearer';
    $serwersms = new SerwerSMS\SerwerSMS($token);
    // $serwersms jest gotowy do użycia
} catch (Exception $e) {
    echo 'Błąd inicjalizacji: ' . $e->getMessage();
}
```

--------------------------------

### Send SMS Messages with SerwerSMS PHP API

Source: https://github.com/serwersmspl/serwersms-php-api-v2/blob/master/README.md

Demonstrates sending different types of SMS messages: FULL, ECO, VOICE from text, and MMS. Requires the SerwerSMS client and a valid API token. The MMS example requires pre-uploading files.

```php
require_once('vendor/autoload.php');

try{
  $serwersms = new SerwerSMS\SerwerSMS($token);
  
  // SMS FULL
  $result = $serwersms->messages->sendSms(
            array(
                    '+48500600700',
                    '+48600700800'
            ),
            'Test FULL message',
            'INFORMACJA',
            array(
                    'test' => true,
                    'details' => true
            )
  );
  
  // SMS ECO
  $result = $serwersms->messages->sendSms(
            array(
                    '+48500600700',
                    '+48600700800'
            ),
            'Test ECO message',
            null,
            array(
                    'test' => true,
                    'details' => true
            )
  );

  // VOICE from text
  $result = $serwersms->messages->sendVoice(
            array(
                    '+48500600700',
                    '+48600700800'
            ),
            array(
                    'text' => 'Test message',
                    'test' => true,
                    'details' => true
            )
  );
  
  // MMS
  $list = $serwersms->files->index('mms');
  $result = $serwersms->messages->sendMms(
            array(
                    '+48500600700',
                    '+48600700800'
            ),
            'MMS Title',
            array(
                    'test' => true,
                    'file_id' => $list->items[0]->id,
                    'details' => true
            )
  );
  
  echo 'Skolejkowano: '.$result->queued.'<br />';
  echo 'Niewysłano: '.$result->unsent.'<br />';
  
  foreach($result->items as $sms){
    echo 'ID: '.$sms->id.'<br />';
    echo 'NUMER: '.$sms->phone.'<br />';
    echo 'STATUS: '.$sms->status.'<br />';
    echo 'CZĘŚCI: '.$sms->parts.'<br />';
    echo 'WIADOMOŚĆ: '.$sms->text.'<br />';
  }
    
} catch(Exception $e){
  echo 'ERROR: '.$e->getMessage();
}
```

--------------------------------

### Fetch Incoming Messages with SerwerSMS PHP API

Source: https://github.com/serwersmspl/serwersms-php-api-v2/blob/master/README.md

Retrieves incoming SMS messages. The 'ndi' parameter specifies the type of messages to fetch. Requires the SerwerSMS client and a valid API token. The example iterates through received messages and displays their details.

```php
require_once('vendor/autoload.php');

try{
  $serwersms = new SerwerSMS\SerwerSMS($token);

  // Get recived messages
  $result = $serwersms->messages->recived('ndi');

  foreach($result->items as $sms){
    echo 'ID: '.$sms->id.'<br />';
    echo 'TYP: '.$sms->type.'<br />';
    echo 'NUMER: '.$sms->phone.'<br />';
    echo 'DATA: '.$sms->recived.'<br />';
    echo 'CZARNA LISTA: '.$sms->blacklist.'<br />';
    echo 'WIADOMOŚĆ: '.$sms->text.'<br />';
  }

} catch(Exception $e){
  echo 'ERROR: '.$e->getMessage();
}
```

--------------------------------

### Send Voice Messages (VMS)

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Send a voice message, which can be text-to-speech or a WAV file, to specified phone numbers. Use `details: true` to get status for each message.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Wysyłka głosowa z syntezą mowy
    $result = $serwersms->messages->sendVoice(
        ['+48500600700', '+48600700800'],
        ['text' => 'Twoja przesyłka jest gotowa do odbioru.', 'test' => true, 'details' => true]
    );

    echo 'Skolejkowano: ' . $result->queued . PHP_EOL;
    foreach ($result->items as $msg) {
        echo 'ID: ' . $msg->id . ' Status: ' . $msg->status . PHP_EOL;
    }

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}
```

--------------------------------

### Get Delivery Reports

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Retrieves delivery reports for sent messages. Supports filtering by ID, phone number, status, type, and date range. Pagination is available.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    $result = $serwersms->messages->reports([
        'status'    => 'delivered',
        'type'      => 'full',
        'date_from' => '2024-01-01',
        'date_to'   => '2024-01-31',
        'page'      => 1,
        'limit'     => 50,
        'order'     => 'desc',
    ]);

    echo 'Strona: ' . $result->paging->page . '/' . $result->paging->count . PHP_EOL;
    foreach ($result->items as $sms) {
        echo 'ID: '        . $sms->id        . PHP_EOL;
        echo 'Numer: '     . $sms->phone     . PHP_EOL;
        echo 'Status: '    . $sms->status    . PHP_EOL; // delivered|undelivered|sent|unsent|in_progress
        echo 'Wysłano: '   . $sms->sent      . PHP_EOL;
        echo 'Doręczono: ' . $sms->delivered . PHP_EOL;
        echo 'Koszt: '     . $sms->cost      . PHP_EOL;
    }

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}
?>
```

--------------------------------

### Retrieve SMS Delivery Reports with SerwerSMS PHP API

Source: https://github.com/serwersmspl/serwersms-php-api-v2/blob/master/README.md

Fetches delivery status reports for specified SMS message IDs. Requires the SerwerSMS client and a valid API token. The example shows how to iterate through the reports and display message details.

```php
require_once('vendor/autoload.php');

try{
  $serwersms = new SerwerSMS\SerwerSMS($token);

  // Get messages reports
  $result = $serwersms->messages->reports(array('id' => array('aca3944055')));

  foreach($result->items as $sms){
    echo 'ID: '.$sms->id.'<br />';
    echo 'NUMER: '.$sms->phone.'<br />';
    echo 'STATUS: '.$sms->status.'<br />';
    echo 'SKOLEJKOWANO: '.$sms->queued.'<br />';
    echo 'WYSŁANO: '.$sms->sent.'<br />';
    echo 'DORĘCZONO: '.$sms->delivered.'<br />';
    echo 'NADAWCA: '.$sms->sender.'<br />';
    echo 'TYP: '.$sms->type.'<br />';
    echo 'WIADOMOŚĆ: '.$sms->text.'<br />';
  }

} catch(Exception $e){
  echo 'ERROR: '.$e->getMessage();
}
```

--------------------------------

### Get Sending Statistics

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Retrieve aggregated statistics for sent messages, broken down by type and date range. Requires the SerwerSMS SDK. Specify 'type', 'begin', and 'end' parameters.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS
SerwerSMS('twoj_token_api');

    $stats = $serwersms->stats->index([
        'type'  => 'full',
        'begin' => '2024-01-01',
        'end'   => '2024-12-31',
    ]);

    foreach ($stats->items as $s) {
        echo 'Kampania: '     . $s->name        . PHP_EOL;
        echo 'Doręczone: '    . $s->delivered   . PHP_EOL;
        echo 'Niedoręczone: ' . $s->undelivered . PHP_EOL;
        echo 'Oczekujące: '   . $s->pending     . PHP_EOL;
        echo 'Niewysłane: '   . $s->unsent      . PHP_EOL;
        echo 'Typ: '          . $s->type        . PHP_EOL;
    }

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Client Initialization

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Demonstrates how to create an instance of the main SerwerSMS object using an API Bearer token.

```APIDOC
## Client Initialization

### Description
Creates an instance of the main `SerwerSMS` object with an API Bearer token.

### Method
```php
new SerwerSMS
```

### Parameters
- **token** (string) - Required - Your API Bearer token generated in the Client Panel.

### Request Example
```php
<?php
require_once('vendor/autoload.php');

try {
    $token = 'your_api_bearer_token';
    $serwersms = new SerwerSMS
($token);
    // $serwersms is ready to use
} catch (Exception $e) {
    echo 'Initialization error: ' . $e->getMessage();
}
```
```

--------------------------------

### Manage Subaccounts: Add, List, Set Limits, Delete

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Create and manage subaccounts with separate permissions and sending limits. Requires the SerwerSMS SDK. Subaccount IDs are used for operations.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS
SerwerSMS('twoj_token_api');

    // Tworzenie podkonta (subaccount_id = ID szablonu uprawnień)
    $sub = $serwersms->subaccounts->add('user_test', 'HasloTajne123', 1, [
        'name'  => 'Dział Marketingu',
        'phone' => '+48500000001',
        'email' => 'marketing@firma.pl',
    ]);
    echo 'Podkonto ID: ' . $sub->id . PHP_EOL;

    // Lista podkont
    $list = $serwersms->subaccounts->index();
    foreach ($list->items as $account) {
        echo $account->id . ' | ' . $account->username . PHP_EOL;
    }

    // Ustawienie limitu wysyłki
    $serwersms->subaccounts->limit($sub->id, 'eco', 1000);
    $serwersms->subaccounts->limit($sub->id, 'full', 500);

    // Usunięcie podkonta
    $serwersms->subaccounts->delete($sub->id);

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Files Management (add, index, view, delete)

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Manage MMS and Voice files, including uploading, listing, viewing, and deleting them.

```APIDOC
## files->add() / index() / view() / delete()

### Description
Manages MMS and Voice files, allowing for uploading, listing, viewing, and deleting multimedia files used for sending.

### Method
- `add(string $type, array $params)`: Adds a file (MMS or Voice). `$type` can be 'mms' or 'voice'. `$params` should contain 'url' for MMS files.
- `index(string $type)`: Lists files of a specified type ('mms' or 'voice').
- `view(string $id, string $type)`: Retrieves details of a specific file by its ID and type.
- `delete(string $id, string $type)`: Deletes a file by its ID and type.

### Request Example
```php
// Add an MMS file via URL
$added = $serwersms->files->add('mms', ['url' => 'https://example.com/obraz.jpg']);

// List voice files
$voiceFiles = $serwersms->files->index('voice');

// View a file
$file = $serwersms->files->view($added->id, 'mms');

// Delete a file
$del = $serwersms->files->delete($added->id, 'mms');
```

### Response Example
- `add()`: Returns an object with the `id` of the added file.
- `index()`: Returns an object with an `items` array containing file details.
- `view()`: Returns an object with file details like `name`, `date`, `size`.
- `delete()`: Returns an object with a `success` boolean indicating the outcome.
```

--------------------------------

### Manage Account Details with SerwerSMS PHP API

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

This code snippet demonstrates how to check sending limits, retrieve contact information for your account manager, read messages from the administrator, and register a new account. Remember to include 'vendor/autoload.php' and use your API token.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Limity wysyłki
    $limits = $serwersms->account->limits(['show_type' => true]);
    foreach ($limits->items as $limit) {
        echo $limit->type . ': ' . $limit->value . ' szt. (maks. ' . $limit->chars_limit . ' znaków)' . PHP_EOL;
    }

    // Dane kontaktowe opiekuna
    $help = $serwersms->account->help();
    echo 'Telefon: ' . $help->telephone . PHP_EOL;
    echo 'Email: '   . $help->email     . PHP_EOL;

    // Wiadomości od administratora
    $msgs = $serwersms->account->messages();
    if ($msgs->new) {
        echo 'Nowa wiadomość: ' . $msgs->message . PHP_EOL;
    }

    // Rejestracja nowego konta
    $new = $serwersms->account->add([
        'phone'      => '+48500000099',
        'email'      => 'nowy@firma.pl',
        'first_name' => 'Nowy',
        'last_name'  => 'Użytkownik',
        'company'    => 'Nowa Firma Sp. z o.o.',
    ]);
    echo $new->success ? 'Konto zarejestrowane.' : 'Błąd rejestracji.';

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Manage MMS and Voice Files with SerwerSMS PHP API

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Use this snippet to add, list, view, and delete MMS or Voice files. Ensure the 'vendor/autoload.php' is included and your API token is correctly set.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Dodanie pliku MMS przez URL
    $added = $serwersms->files->add('mms', ['url' => 'https://example.com/obraz.jpg']);
    echo 'Dodano plik ID: ' . $added->id . PHP_EOL;

    // Lista plików głosowych
    $voiceFiles = $serwersms->files->index('voice');
    foreach ($voiceFiles->items as $file) {
        echo $file->id . ' | ' . $file->name . ' | ' . $file->size . ' B' . PHP_EOL;
    }

    // Podgląd pliku
    $file = $serwersms->files->view($added->id, 'mms');
    echo 'Nazwa: ' . $file->name . ' | Data: ' . $file->date . PHP_EOL;

    // Usunięcie pliku
    $del = $serwersms->files->delete($added->id, 'mms');
    echo $del->success ? 'Plik usunięty.' : 'Błąd usuwania.';

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Manage Payments and Invoices with SerwerSMS PHP API

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Use this snippet to retrieve a list of invoices, view details of a specific invoice, or download an invoice PDF. Ensure you have the 'vendor/autoload.php' included and replace 'twoj_token_api' with your actual API token.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Lista faktur
    $list = $serwersms->payments->index();
    foreach ($list->items as $inv) {
        echo $inv->number . ' | ' . $inv->state . ' | Kwota: ' . $inv->total . ' PLN' . PHP_EOL;
        // state: paid|not_paid
    }

    // Szczegóły faktury
    $invoice = $serwersms->payments->view($list->items[0]->id);
    echo 'Do zapłaty do: ' . $invoice->payment_to . PHP_EOL;
    echo 'URL płatności: ' . $invoice->url         . PHP_EOL;

    // Pobranie PDF faktury
    $pdf = $serwersms->payments->invoice($list->items[0]->id);
    file_put_contents('faktura.pdf', $pdf);

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Manage Contact Groups with SerwerSMS PHP API

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

This snippet covers creating, listing, editing, checking membership, and deleting contact groups. It requires the SerwerSMS library and API token.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Tworzenie grupy
    $group = $serwersms->groups->add('Klienci VIP');
    echo 'Nowa grupa ID: ' . $group->id . PHP_EOL;

    // Lista grup
    $list = $serwersms->groups->index(null, ['limit' => 10]);
    foreach ($list->items as $g) {
        echo $g->id . ' | ' . $g->name . ' | Kontaktów: ' . $g->count . PHP_EOL;
    }

    // Edycja grupy
    $serwersms->groups->edit($group->id, 'Klienci Premium');

    // Sprawdzenie przynależności numeru
    $check = $serwersms->groups->check('+48500600700');
    echo 'Należy do grupy: ' . $check->group_name . PHP_EOL;

    // Usunięcie grupy
    $serwersms->groups->delete($group->id);

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Handle Premium SMS with SerwerSMS PHP API

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

This snippet covers managing incoming Premium SMS messages, sending replies, and retrieving quiz results associated with Premium numbers. Ensure 'vendor/autoload.php' is included and your API token is correctly set.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Lista przychodzących SMS Premium
    $incoming = $serwersms->premium->index();
    foreach ($incoming->items as $sms) {
        echo 'Numer Premium: ' . $sms->to_number   . PHP_EOL;
        echo 'Nadawca: '       . $sms->from_number . PHP_EOL;
        echo 'Treść: '         . $sms->text        . PHP_EOL;

        // Wysyłka odpowiedzi
        $reply = $serwersms->premium->send(
            $sms->from_number,
            'Dziękujemy za udział w konkursie!',
            $sms->to_number,
            $sms->id
        );
        echo $reply->success ? 'Odpowiedź wysłana.' : 'Błąd.';
    }

    // Wyniki quizu powiązanego z numerem Premium
    $quiz = $serwersms->premium->quiz(42);
    echo 'Quiz: ' . $quiz->name . PHP_EOL;
    foreach ($quiz->items as $option) {
        echo 'Opcja ' . $option->id . ': ' . $option->count . ' głosów' . PHP_EOL;
    }

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Manage Blacklist: Add, Check, List, Delete Numbers

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Use this to block numbers from receiving messages, check their status, and manage the blocked list. Ensure the SerwerSMS SDK is included via Composer.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS
SerwerSMS('twoj_token_api');

    // Dodanie numeru do czarnej listy
    $serwersms->blacklist->add('+48500600700');

    // Sprawdzenie czy numer jest na czarnej liście
    $check = $serwersms->blacklist->check('+48500600700');
    echo $check->exists ? 'Numer zablokowany.' : 'Numer aktywny.' . PHP_EOL;

    // Lista wszystkich zablokowanych numerów
    $list = $serwersms->blacklist->index(null, ['page' => 1, 'limit' => 50]);
    foreach ($list->items as $item) {
        echo $item->phone . ' | Dodano: ' . $item->added . PHP_EOL;
    }

    // Usunięcie z czarnej listy
    $del = $serwersms->blacklist->delete('+48500600700');
    echo $del->success ? 'Odblokowano.' : 'Błąd.';

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Manage Contacts with SerwerSMS PHP API

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

This code shows how to add, list, import, edit, and delete contacts within groups. It requires the SerwerSMS library and a valid API token.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Dodanie kontaktu do grupy
    $contact = $serwersms->contacts->add(
        5,
        '+48500600700',
        ['first_name' => 'Jan', 'last_name' => 'Kowalski', 'email' => 'jan@example.com', 'company' => 'Acme Sp. z o.o.']
    );
    echo 'Kontakt ID: ' . $contact->id . PHP_EOL;

    // Lista kontaktów z wyszukiwaniem
    $list = $serwersms->contacts->index(5, 'Kowalski', ['limit' => 20, 'order' => 'asc']);
    foreach ($list->items as $c) {
        echo $c->first_name . ' ' . $c->last_name . ' | ' . $c->phone . PHP_EOL;
    }

    // Masowy import kontaktów
    $importData = [
        ['phone' => '500111222', 'first_name' => 'Alicja', 'last_name' => 'Nowak', 'email' => 'a@example.com'],
        ['phone' => '600222333', 'first_name' => 'Piotr',  'last_name' => 'Wiśniewski'],
    ];
    $imported = $serwersms->contacts->import('Nowa Grupa Import', $importData);
    echo 'Zaimportowano: ' . $imported->correct . ', Błędów: ' . $imported->failed . PHP_EOL;

    // Edycja kontaktu
    $serwersms->contacts->edit($contact->id, 5, '+48500600700', ['company' => 'Nowa Firma']);

    // Usunięcie kontaktu
    $serwersms->contacts->delete($contact->id);

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### messages->recived()

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Fetches a list of incoming messages, including ECO replies, messages to ND/NDI numbers, and incoming MMS.

```APIDOC
## messages->recived()

### Description
Fetches a list of incoming messages, supporting filtering by type and date.

### Method
GET (assumed, based on typical API patterns for retrieving data)

### Endpoint
`/messages/recived` (assumed, based on method name)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **type** (string) - Required - The type of incoming messages to retrieve ('eco', 'nd', 'ndi', 'mms').
- **date_from** (string) - Optional - Filters messages from a specific date (YYYY-MM-DD).
- **read** (boolean) - Optional - Filters by read status (true for read, false for unread).
- **limit** (integer) - Optional - The number of results to return. Defaults to a system default.

### Request Example
```php
{
  "type": "ndi",
  "date_from": "2024-06-01",
  "read": true,
  "limit": 20
}
```

### Response
#### Success Response (200)
- **items** (array) - An array of incoming message objects:
  - **phone** (string) - The sender's phone number.
  - **text** (string) - The content of the message.
  - **recived** (string) - Timestamp when the message was received.
  - **blacklist** (boolean) - Indicates if the sender is on the blacklist.
```

--------------------------------

### Contacts Management (add, index, edit, delete, import)

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Manage contacts within groups, including adding, listing, editing, deleting, and bulk importing.

```APIDOC
## contacts->add() / index() / edit() / delete() / import()

### Description
Handles adding, editing, searching, deleting, and bulk importing contacts assigned to groups.

### Method
- `add(int $groupId, string $phone, array $params = null)`: Adds a contact to a specified group. `$params` can include `first_name`, `last_name`, `email`, `company`.
- `index(int $groupId, string $searchQuery = null, array $params = null)`: Lists contacts within a group, with optional search and pagination parameters like `['limit' => 20, 'order' => 'asc']`.
- `edit(string $id, int $groupId, string $phone, array $params)`: Edits an existing contact's details using its ID, group ID, phone number, and new parameters.
- `delete(string $id)`: Deletes a contact by its ID.
- `import(string $groupName, array $data)`: Imports multiple contacts into a new or existing group. `$data` is an array of contact objects.

### Request Example
```php
// Add a contact to a group
$contact = $serwersms->contacts->add(5, '+48500600700', ['first_name' => 'Jan', 'last_name' => 'Kowalski', 'email' => 'jan@example.com', 'company' => 'Acme Sp. z o.o.']);

// List contacts with search
$list = $serwersms->contacts->index(5, 'Kowalski', ['limit' => 20, 'order' => 'asc']);

// Bulk import contacts
$importData = [
    ['phone' => '500111222', 'first_name' => 'Alicja', 'last_name' => 'Nowak', 'email' => 'a@example.com'],
    ['phone' => '600222333', 'first_name' => 'Piotr',  'last_name' => 'Wiśniewski'],
];
$imported = $serwersms->contacts->import('Nowa Grupa Import', $importData);

// Edit a contact
$serwersms->contacts->edit($contact->id, 5, '+48500600700', ['company' => 'Nowa Firma']);

// Delete a contact
$serwersms->contacts->delete($contact->id);
```

### Response Example
- `add()`: Returns an object with the `id` of the added contact.
- `index()`: Returns an object with an `items` array containing contact details.
- `import()`: Returns an object with `correct` and `failed` counts for the import operation.
- `edit()`: No explicit return value mentioned, assumed success if no exception is thrown.
- `delete()`: No explicit return value mentioned, assumed success if no exception is thrown.
```

--------------------------------

### Manage Senders with SerwerSMS PHP API

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

This code demonstrates how to add and list sender names for FULL SMS messages. It requires the SerwerSMS library and a valid API token.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Dodanie nowego nadawcy
    $result = $serwersms->senders->add('MOJAFIRMA');
    echo $result->success ? 'Nadawca dodany.' : 'Błąd.';

    // Lista nadawców
    $list = $serwersms->senders->index(['order' => 'asc']);
    foreach ($list->items as $sender) {
        echo $sender->name . ' | Status: ' . $sender->status . PHP_EOL;
        // Status: pending_authorization|authorized|rejected|deactivated
    }

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### Subaccount Management

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Manage subaccounts with separate permissions and sending limits.

```APIDOC
## subaccounts->add() / index() / view() / limit() / delete()

### Description
The subaccount module allows creating and managing subaccounts with individual sending permissions and limits.

### Methods
- `add(string $username, string $password, int $subaccountId, array $options = [])`: Creates a new subaccount.
- `index()`: Retrieves a list of all subaccounts.
- `view(int $id)`: Retrieves details for a specific subaccount.
- `limit(int $id, string $type, int $value)`: Sets the sending limit for a subaccount.
- `delete(int $id)`: Deletes a subaccount.

### Request Example (PHP)
```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Tworzenie podkonta (subaccount_id = ID szablonu uprawnień)
    $sub = $serwersms->subaccounts->add('user_test', 'HasloTajne123', 1, [
        'name'  => 'Dział Marketingu',
        'phone' => '+48500000001',
        'email' => 'marketing@firma.pl',
    ]);
    echo 'Podkonto ID: ' . $sub->id . PHP_EOL;

    // Lista podkont
    $list = $serwersms->subaccounts->index();
    foreach ($list->items as $account) {
        echo $account->id . ' | ' . $account->username . PHP_EOL;
    }

    // Ustawienie limitu wysyłki
    $serwersms->subaccounts->limit($sub->id, 'eco', 1000);
    $serwersms->subaccounts->limit($sub->id, 'full', 500);

    // Usunięcie podkonta
    $serwersms->subaccounts->delete($sub->id);

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}
?>
```
```

--------------------------------

### Account Management

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Manage your account by checking sending limits, retrieving contact information for your account manager, viewing administrator messages, and registering a new account.

```APIDOC
## account->limits() / help() / messages() / add()

### Description
Manages your account by checking sending limits, retrieving contact information for your account manager, viewing administrator messages, and registering a new account.

### Method
```php
$serwersms->account->limits(['show_type' => true]);
$serwersms->account->help();
$serwersms->account->messages();
$serwersms->account->add(array $params);
```

### Parameters
- `limits()` accepts an optional array with `show_type` (bool).
- `add()` accepts an array with the following parameters:
  - `phone` (string) - Required - User's phone number.
  - `email` (string) - Required - User's email address.
  - `first_name` (string) - Required - User's first name.
  - `last_name` (string) - Required - User's last name.
  - `company` (string) - Optional - User's company name.

### Request Example
```php
// Check sending limits
$limits = $serwersms->account->limits(['show_type' => true]);

// Get help contact info
$help = $serwersms->account->help();

// Check for messages
$msgs = $serwersms->account->messages();

// Register a new account
$new = $serwersms->account->add([
    'phone'      => '+48500000099',
    'email'      => 'nowy@firma.pl',
    'first_name' => 'Nowy',
    'last_name'  => 'Użytkownik',
    'company'    => 'Nowa Firma Sp. z o.o.',
]);
```

### Response
- `limits()` returns an object with sending limits, including `type`, `value`, and `chars_limit`.
- `help()` returns an object with contact details like `telephone` and `email`.
- `messages()` returns an object with `new` (bool) and `message` (string).
- `add()` returns an object with a `success` (bool) property indicating the result of the registration.
```

--------------------------------

### Groups Management (add, index, edit, delete, check)

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Manage contact groups, including creation, editing, deletion, and checking contact group membership.

```APIDOC
## groups->add() / index() / edit() / delete() / check()

### Description
Enables the creation, editing, deletion, and checking of contact group memberships.

### Method
- `add(string $name)`: Creates a new contact group with the given name.
- `index(array $params = null)`: Lists existing contact groups. `$params` can include options like `['limit' => 10]`.
- `edit(string $id, string $name)`: Edits an existing group's name using its ID.
- `check(string $phone)`: Checks which group a given phone number belongs to.
- `delete(string $id)`: Deletes a group by its ID.

### Request Example
```php
// Create a group
$group = $serwersms->groups->add('Klienci VIP');

// List groups
$list = $serwersms->groups->index(null, ['limit' => 10]);

// Edit a group
$serwersms->groups->edit($group->id, 'Klienci Premium');

// Check phone number membership
$check = $serwersms->groups->check('+48500600700');

// Delete a group
$serwersms->groups->delete($group->id);
```

### Response Example
- `add()`: Returns an object with the `id` of the newly created group.
- `index()`: Returns an object with an `items` array containing group details like `id`, `name`, and `count` (number of contacts).
- `check()`: Returns an object with `group_name`.
- `delete()`: No explicit return value mentioned, assumed success if no exception is thrown.
```

--------------------------------

### Payments Management

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Manage payments and invoices by retrieving a list of invoices, viewing details of a specific invoice, or downloading an invoice PDF.

```APIDOC
## payments->index() / view() / invoice()

### Description
Retrieves a list of invoices, details of a single invoice, or an invoice PDF file from your SerwerSMS account.

### Method
```php
$serwersms->payments->index();
$serwersms->payments->view($invoice_id);
$serwersms->payments->invoice($invoice_id);
```

### Parameters
- `view()` and `invoice()` methods require an `$invoice_id` (string) as a parameter.

### Request Example
```php
// List invoices
$list = $serwersms->payments->index();

// View invoice details
$invoice = $serwersms->payments->view($list->items[0]->id);

// Download invoice PDF
$pdf = $serwersms->payments->invoice($list->items[0]->id);
file_put_contents('faktura.pdf', $pdf);
```

### Response
- `index()` returns a list of invoice objects, each with properties like `number`, `state`, and `total`.
- `view()` returns a detailed invoice object with properties like `payment_to` and `url`.
- `invoice()` returns the PDF content of the invoice.
```

--------------------------------

### Retrieve Incoming Messages

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Fetches a list of incoming messages, including ECO replies, ND/NDI messages, and incoming MMS. Supports filtering by type, date, read status, and limit.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    // Typy: 'eco' | 'nd' | 'ndi' | 'mms'
    $result = $serwersms->messages->recived('ndi', [
        'date_from' => '2024-06-01',
        'read'      => true,
        'limit'     => 20,
    ]);

    foreach ($result->items as $sms) {
        echo 'Od: '         . $sms->phone     . PHP_EOL;
        echo 'Treść: '      . $sms->text      . PHP_EOL;
        echo 'Data: '       . $sms->recived   . PHP_EOL;
        echo 'Czarna lista: ' . ($sms->blacklist ? 'tak' : 'nie') . PHP_EOL;
    }

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}
?>
```

--------------------------------

### Manage Message Templates: Add, List, Edit, Delete

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Store and reuse predefined SMS message content. Requires the SerwerSMS SDK. Templates can be identified by their ID.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS
SerwerSMS('twoj_token_api');

    // Dodanie szablonu
    $tpl = $serwersms->templates->add('Potwierdzenie zamówienia', 'Twoje zamówienie nr {nr} zostało przyjęte.');
    echo 'Szablon ID: ' . $tpl->id . PHP_EOL;

    // Lista szablonów
    $list = $serwersms->templates->index(['sort' => 'name', 'order' => 'asc']);
    foreach ($list->items as $t) {
        echo $t->id . ' | ' . $t->name . ': ' . $t->text . PHP_EOL;
    }

    // Edycja szablonu
    $serwersms->templates->edit($tpl->id, 'Potwierdzenie zamówienia v2', 'Zamówienie #{nr} przyjęte. Dziękujemy!');

    // Usunięcie szablonu
    $serwersms->templates->delete($tpl->id);

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}

```

--------------------------------

### View Single Message Details

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Fetches detailed information for a specific message, including its full delivery status and optional contact data. Requires the message ID.

```php
<?php
require_once('vendor/autoload.php');

try {
    $serwersms = new SerwerSMS\SerwerSMS('twoj_token_api');

    $msg = $serwersms->messages->view('aca3944055', ['show_contact' => true]);

    echo 'ID: '        . $msg->id        . PHP_EOL;
    echo 'Status: '    . $msg->status    . PHP_EOL;
    echo 'Typ: '       . $msg->type      . PHP_EOL; // eco|full|mms|voice
    echo 'Nadawca: '   . $msg->sender    . PHP_EOL;
    echo 'Wysłano: '   . $msg->sent      . PHP_EOL;
    echo 'Doręczono: ' . $msg->delivered . PHP_EOL;

    if (isset($msg->contact)) {
        echo 'Kontakt: ' . $msg->contact->first_name . ' ' . $msg->contact->last_name . PHP_EOL;
    }

} catch (Exception $e) {
    echo 'Błąd: ' . $e->getMessage();
}
?>
```

--------------------------------

### messages->view()

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Retrieves detailed information for a single message, including its full delivery status and optional contact data.

```APIDOC
## messages->view()

### Description
Retrieves details of a single message, including delivery status and contact information.

### Method
GET (assumed, based on typical API patterns for retrieving data)

### Endpoint
`/messages/view/{id}` (assumed, based on method name and parameter)

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique ID of the message to retrieve.

#### Query Parameters
- **show_contact** (boolean) - Optional - If true, includes contact details in the response. Defaults to false.

### Request Example
```php
{
  "id": "aca3944055",
  "show_contact": true
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique ID of the message.
- **status** (string) - The current status of the message.
- **type** (string) - The type of the message (e.g., 'eco', 'full', 'mms', 'voice').
- **sender** (string) - The sender's identifier.
- **sent** (string) - Timestamp when the message was sent.
- **delivered** (string) - Timestamp when the message was delivered.
- **contact** (object) - Optional - Contact details if `show_contact` was true:
  - **first_name** (string) - The first name of the contact.
  - **last_name** (string) - The last name of the contact.
```

--------------------------------

### Premium SMS Handling

Source: https://context7.com/serwersmspl/serwersms-php-api-v2/llms.txt

Handle incoming premium SMS messages, send replies, and retrieve quiz results associated with premium numbers.

```APIDOC
## premium->index() / send() / quiz()

### Description
Handles incoming premium SMS messages, sends replies, and retrieves quiz results associated with premium numbers.

### Method
```php
$serwersms->premium->index();
$serwersms->premium->send(string $from_number, string $text, string $to_number, string $message_id);
$serwersms->premium->quiz(int $quiz_id);
```

### Parameters
- `send()` requires:
  - `$from_number` (string) - The sender's phone number.
  - `$text` (string) - The reply message content.
  - `$to_number` (string) - The premium number.
  - `$message_id` (string) - The ID of the incoming message.
- `quiz()` requires:
  - `$quiz_id` (int) - The ID of the quiz.

### Request Example
```php
// List incoming premium SMS
$incoming = $serwersms->premium->index();

// Send a reply
$reply = $serwersms->premium->send($sms->from_number, 'Dziękujemy za udział w konkursie!', $sms->to_number, $sms->id);

// Get quiz results
$quiz = $serwersms->premium->quiz(42);
```

### Response
- `index()` returns a list of incoming SMS objects, each with properties like `to_number`, `from_number`, `text`, and `id`.
- `send()` returns an object with a `success` (bool) property.
- `quiz()` returns a quiz object with properties like `name` and `items` (an array of options with `id` and `count`).
```