> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vzaps.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> How to install, authenticate, and configure the official VZaps PHP SDK

The official VZaps PHP SDK wraps authentication, HTTP calls, required headers, realtime events, and the main public API resources.

Use this SDK when integrating VZaps into PHP backends, CLIs, workers, Laravel/Symfony commands, jobs, and server-to-server automation.

## Requirements

| Resource  | Version                            |
| --------- | ---------------------------------- |
| PHP       | 8.1 or higher                      |
| Composer  | 2.x recommended                    |
| Extension | `json`                             |
| HTTP      | Guzzle 7, installed by the package |

<Tip>
  Do not expose `clientSecret` or `instanceToken` in a public frontend. Prefer using the SDK in backends, commands, jobs, and server-to-server automation.
</Tip>

## Install

```bash theme={null}
composer require vzaps/sdk
```

For realtime WebSocket usage in CLI/workers, also install the optional transport:

```bash theme={null}
composer require textalk/websocket
```

## Create the client

```php theme={null}
use VZaps\Sdk\VZapsClient;

$vzaps = new VZapsClient(
    clientToken: getenv('VZAPS_CLIENT_TOKEN'),
    clientSecret: getenv('VZAPS_CLIENT_SECRET'),
);
```

## Credentials

The SDK uses two credential groups:

| Credential      | Where to use          | Description                                          |
| --------------- | --------------------- | ---------------------------------------------------- |
| `clientToken`   | `new VZapsClient()`   | Public account token, also sent as `X-Client-Token`. |
| `clientSecret`  | `new VZapsClient()`   | Secret used by the SDK to obtain and refresh JWTs.   |
| `instanceToken` | On each instance call | Instance token, sent as `X-Instance-Token`.          |

`instanceToken` is not stored on the global client. Always pass it in calls that operate an instance:

```php theme={null}
$vzaps->messages()->sendText([
    'instanceId' => 'VZ...',
    'instanceToken' => getenv('VZAPS_INSTANCE_TOKEN'),
    'phone' => '5511999999999',
    'message' => 'Hello from VZaps',
]);
```

## Automatic authentication

The SDK obtains the JWT automatically using `clientToken` and `clientSecret`, caches the token in memory, and refreshes it before expiry.

You rarely need to call the token manually. When integrating with custom HTTP code:

```php theme={null}
$accessToken = $vzaps->auth()->getAccessToken();
```

## Client options

| Option             | Type                              | Default                            | Use                                                |
| ------------------ | --------------------------------- | ---------------------------------- | -------------------------------------------------- |
| `clientToken`      | `string`                          | -                                  | Required. Account token.                           |
| `clientSecret`     | `string`                          | -                                  | Required. Account secret.                          |
| `timeoutSeconds`   | `float`                           | `30.0`                             | HTTP timeout in seconds.                           |
| `tokenSkewSeconds` | `int`                             | `60`                               | Refresh JWT before actual expiry.                  |
| `httpClient`       | `Psr\Http\Client\ClientInterface` | Guzzle                             | Customize HTTP transport for tests, proxy, or TLS. |
| `webSocketFactory` | `callable`                        | `textalk/websocket` when installed | Customize WebSocket transport.                     |
| `userAgent`        | `string`                          | `VZaps.SDK.PHP/<version>`          | `User-Agent` header on HTTP requests.              |

```php theme={null}
use GuzzleHttp\Client;
use VZaps\Sdk\VZapsClient;

$vzaps = new VZapsClient(
    clientToken: getenv('VZAPS_CLIENT_TOKEN'),
    clientSecret: getenv('VZAPS_CLIENT_SECRET'),
    timeoutSeconds: 10,
    httpClient: new Client([
        'timeout' => 10,
        'http_errors' => false,
    ]),
);
```

## Composer autoload

In simple PHP scripts:

```php theme={null}
require __DIR__ . '/vendor/autoload.php';

use VZaps\Sdk\VZapsClient;
```

In Laravel, Symfony, and other frameworks, use your project Composer autoload and register `VZapsClient` as a service/singleton when useful.

## Recommended environment variables

```bash theme={null}
VZAPS_CLIENT_TOKEN=your-client-token
VZAPS_CLIENT_SECRET=your-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=instance-token
```

## Response typing

By default, responses are PHP arrays decoded from API JSON because the contract can evolve.

```php theme={null}
/** @var array<string, mixed> $instances */
$instances = $vzaps->instances()->list([
    'page' => 1,
    'pageSize' => 20,
]);
```

For main requests, you can use DTOs with named arguments:

```php theme={null}
use VZaps\Sdk\Models\Messages\SendTextMessageRequest;

$vzaps->messages()->sendText(new SendTextMessageRequest(
    instanceId: 'VZ...',
    instanceToken: getenv('VZAPS_INSTANCE_TOKEN'),
    phone: '5511999999999',
    message: 'Hello from VZaps',
));
```

For new or advanced public contract fields, use arrays or `GenericInstanceRequest`.

## Next steps

* Follow the [Starter Guide](/en/sdk/php/starter-guide) to create an instance, subscribe, pair, and send the first message.
* See [Messages](/en/sdk/php/messages) for every send type.
* See [Instances and billing](/en/sdk/php/instances-and-billing), [Session](/en/sdk/php/session), and [Chats](/en/sdk/php/chats) for core instance resources.
* See [Webhooks](/en/sdk/php/webhooks), [Queues](/en/sdk/php/queues), [Groups](/en/sdk/php/groups), [TypeBot](/en/sdk/php/typebot), and [Chatwoot](/en/sdk/php/chatwoot) for configuration and integrations.