> ## 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.

# Messages

> Every PHP SDK send function, accepted payloads, and complete examples

All send functions live under `$vzaps->messages()`.

In the SDK, the instance `id` becomes `instanceId`, and the `X-Instance-Token` header becomes `instanceToken`.

```php theme={null}
$base = [
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
];
```

## Common fields

Most send operations accept these fields:

| Field              | Type       | Required | Description                                            |
| ------------------ | ---------- | -------- | ------------------------------------------------------ |
| `instanceId`       | `string`   | Yes      | VZaps instance ID.                                     |
| `instanceToken`    | `string`   | Yes      | Instance token.                                        |
| `phone`            | `string`   | Yes      | Destination phone in international digits-only format. |
| `id`               | `string`   | No       | Optional message identifier for the request.           |
| `delay`            | `number`   | No       | Send delay, when supported by the API.                 |
| `mentionedIds`     | `string[]` | No       | WhatsApp IDs to mention.                               |
| `replyToMessageId` | `string`   | No       | WhatsApp message ID to reply to or quote.              |

<Note>
  The SDK supports DTOs for main requests and arrays for additional public API fields. Use the fields documented here when you need advanced options such as `id`, `delay`, or `replyToMessageId`.
</Note>

## Text

Function: `$vzaps->messages()->sendText()`

Payload:

| Field     | Type     | Required |
| --------- | -------- | -------- |
| `phone`   | `string` | Yes      |
| `message` | `string` | Yes      |

```php theme={null}
$vzaps->messages()->sendText([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'message' => 'Hello, your instance is connected.',
    'id' => 'MSG-TXT-001',
    'replyToMessageId' => '3EB020510113BAA6561C',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

You can also use the DTO:

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

$vzaps->messages()->sendText(new SendTextMessageRequest(
    instanceId: 'VZ...',
    instanceToken: 'instance-token',
    phone: '5511999999999',
    message: 'Hello, your instance is connected.',
));
```

## Image

Function: `$vzaps->messages()->sendImage()`

Payload:

| Field     | Type     | Required |
| --------- | -------- | -------- |
| `phone`   | `string` | Yes      |
| `image`   | `string` | Yes      |
| `caption` | `string` | No       |

`image` accepts a public `https://...` URL or a base64 data URL (`data:image/<mime>;base64,<data>`).

```php theme={null}
$vzaps->messages()->sendImage([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'image' => 'https://cdn.example.com/photo.jpg',
    'caption' => 'Optional caption',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Audio

Function: `$vzaps->messages()->sendAudio()`

Payload:

| Field   | Type      | Required |
| ------- | --------- | -------- |
| `phone` | `string`  | Yes      |
| `audio` | `string`  | Yes      |
| `ptt`   | `boolean` | No       |

`audio` accepts a public URL or base64 data URL (`data:audio/<mime>;base64,...`). Use `ptt: true` when you want to send a voice note, if supported by the account flow.

```php theme={null}
$vzaps->messages()->sendAudio([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'audio' => 'https://cdn.example.com/audio.mp3',
    'ptt' => false,
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Document

Function: `$vzaps->messages()->sendDocument()`

Payload:

| Field      | Type     | Required |
| ---------- | -------- | -------- |
| `phone`    | `string` | Yes      |
| `document` | `string` | Yes      |
| `fileName` | `string` | Yes      |
| `caption`  | `string` | No       |

```php theme={null}
$vzaps->messages()->sendDocument([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'document' => 'https://cdn.example.com/contract.pdf',
    'fileName' => 'contract.pdf',
    'caption' => 'Here is the contract',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Video

Function: `$vzaps->messages()->sendVideo()`

Payload:

| Field           | Type     | Required |
| --------------- | -------- | -------- |
| `phone`         | `string` | Yes      |
| `video`         | `string` | Yes      |
| `caption`       | `string` | No       |
| `jpegThumbnail` | `string` | No       |

```php theme={null}
$vzaps->messages()->sendVideo([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'video' => 'https://cdn.example.com/video.mp4',
    'caption' => 'Demo video',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Sticker

Function: `$vzaps->messages()->sendSticker()`

Payload:

| Field          | Type     | Required |
| -------------- | -------- | -------- |
| `phone`        | `string` | Yes      |
| `sticker`      | `string` | Yes      |
| `pngThumbnail` | `string` | No       |

```php theme={null}
$vzaps->messages()->sendSticker([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'sticker' => 'https://cdn.example.com/sticker.webp',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## GIF

Function: `$vzaps->messages()->sendGif()`

Payload:

| Field     | Type     | Required |
| --------- | -------- | -------- |
| `phone`   | `string` | Yes      |
| `gif`     | `string` | Yes      |
| `caption` | `string` | No       |

```php theme={null}
$vzaps->messages()->sendGif([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'gif' => 'https://media.giphy.com/media/example/giphy.gif',
    'caption' => 'Animated GIF',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Location

Function: `$vzaps->messages()->sendLocation()`

Payload:

| Field       | Type     | Required |
| ----------- | -------- | -------- |
| `phone`     | `string` | Yes      |
| `latitude`  | `number` | Yes      |
| `longitude` | `number` | Yes      |
| `name`      | `string` | No       |
| `address`   | `string` | No       |

```php theme={null}
$vzaps->messages()->sendLocation([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'latitude' => -23.55052,
    'longitude' => -46.633308,
    'name' => 'Sao Paulo',
    'address' => 'Sao Paulo, SP',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Contact

Function: `$vzaps->messages()->sendContact()`

Payload:

| Field          | Type     | Required |
| -------------- | -------- | -------- |
| `phone`        | `string` | Yes      |
| `contactName`  | `string` | Yes      |
| `contactPhone` | `string` | Yes      |

```php theme={null}
$vzaps->messages()->sendContact([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'contactName' => 'Maria Silva',
    'contactPhone' => '5511888888888',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Buttons

Function: `$vzaps->messages()->sendButtons()`

Payload:

| Field     | Type                                          | Required |
| --------- | --------------------------------------------- | -------- |
| `phone`   | `string`                                      | Yes      |
| `message` | `string`                                      | Yes      |
| `buttons` | `array<int, array{id: string, text: string}>` | Yes      |
| `footer`  | `string`                                      | No       |

```php theme={null}
$vzaps->messages()->sendButtons([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'message' => 'Choose an option',
    'footer' => 'VZaps',
    'buttons' => [
        ['id' => 'sales', 'text' => 'Sales'],
        ['id' => 'support', 'text' => 'Support'],
    ],
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## List

Function: `$vzaps->messages()->sendList()`

Payload:

| Field         | Type     | Required |
| ------------- | -------- | -------- |
| `phone`       | `string` | Yes      |
| `title`       | `string` | Yes      |
| `description` | `string` | Yes      |
| `buttonText`  | `string` | Yes      |
| `sections`    | `array`  | Yes      |
| `footer`      | `string` | No       |

```php theme={null}
$vzaps->messages()->sendList([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'title' => 'Main menu',
    'description' => 'Choose an option',
    'buttonText' => 'Open menu',
    'sections' => [
        [
            'title' => 'Departments',
            'rows' => [
                ['id' => 'sales', 'title' => 'Sales', 'description' => 'Talk to sales'],
                ['id' => 'support', 'title' => 'Support', 'description' => 'Talk to support'],
            ],
        ],
    ],
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Link preview

Function: `$vzaps->messages()->sendLink()`

Payload:

| Field             | Type     | Required |
| ----------------- | -------- | -------- |
| `phone`           | `string` | Yes      |
| `message`         | `string` | Yes      |
| `linkUrl`         | `string` | Yes      |
| `title`           | `string` | Yes      |
| `linkDescription` | `string` | Yes      |
| `jpegThumbnail`   | `string` | No       |

```php theme={null}
$vzaps->messages()->sendLink([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'message' => 'Check this link',
    'linkUrl' => 'https://vzaps.com',
    'title' => 'VZaps',
    'linkDescription' => 'WhatsApp API for integrations',
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Poll

Function: `$vzaps->messages()->sendPoll()`

Payload:

| Field                    | Type       | Required |
| ------------------------ | ---------- | -------- |
| `phone`                  | `string`   | Yes      |
| `name`                   | `string`   | Yes      |
| `options`                | `string[]` | Yes      |
| `selectableOptionsCount` | `number`   | No       |
| `hideParticipantNames`   | `boolean`  | No       |
| `endTime`                | `string`   | No       |
| `allowAddOption`         | `boolean`  | No       |

```php theme={null}
$vzaps->messages()->sendPoll([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'name' => 'Which channel do you prefer?',
    'options' => ['WhatsApp', 'Email', 'Phone'],
    'selectableOptionsCount' => 1,
]);
```

**Return:** envelope `{ code, success, data.message_id }` — message accepted/queued.

## Vote in a poll

Function: `$vzaps->messages()->pollVote()`

```php theme={null}
$vzaps->messages()->pollVote([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'messageId' => '3EB020510113BAA6561C',
    'selectedOptions' => ['WhatsApp'],
]);
```

## React and remove reaction

Functions:

* `$vzaps->messages()->react()`
* `$vzaps->messages()->removeReaction()`

```php theme={null}
$vzaps->messages()->react([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'messageId' => '3EB020510113BAA6561C',
    'reaction' => '+1',
]);

$vzaps->messages()->removeReaction([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'messageId' => '3EB020510113BAA6561C',
]);
```

## Presence and read receipts

Functions:

* `$vzaps->messages()->presence()`
* `$vzaps->messages()->markRead()`

```php theme={null}
$vzaps->messages()->presence([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'state' => 'composing',
]);

$vzaps->messages()->markRead([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'id' => ['3EB020510113BAA6561C'],
    'chat' => '5511999999999@s.whatsapp.net',
]);
```

**Return:** envelope `{ code, success, data.details }`.

## Edit and delete message

Functions:

* `$vzaps->messages()->edit()`
* `$vzaps->messages()->delete()`

```php theme={null}
$vzaps->messages()->edit([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'messageId' => '3EB020510113BAA6561C',
    'message' => 'Edited text',
]);

$vzaps->messages()->delete([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'messageId' => '3EB020510113BAA6561C',
]);
```

**Return:** envelope `{ code, success, data.details }`.

## Download media

Functions:

* `downloadImage()`
* `downloadVideo()`
* `downloadAudio()`
* `downloadDocument()`

```php theme={null}
$media = $vzaps->messages()->downloadImage([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
]);

print_r($media);
```

**Return:** envelope `{ code, success, data }` with `data.mimetype` and `data.data` (base64 or data URL).

## Standard response

Send methods return an API envelope indicating that the message was accepted/queued.

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

print_r($result);
```

See the [API reference](/en/api-reference/introduction) for the latest response schemas.