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

# Mensagens

> Todas as funções de envio do SDK PHP, payloads aceitos e exemplos completos

Todas as funções de envio ficam em `$vzaps->messages()`.

No SDK, o `id` da instância vira `instanceId` e o header `X-Instance-Token` vira `instanceToken`.

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

## Campos comuns

Quase todos os envios aceitam os campos abaixo:

| Campo              | Tipo       | Obrigatório | Descrição                                                   |
| ------------------ | ---------- | ----------- | ----------------------------------------------------------- |
| `instanceId`       | `string`   | Sim         | ID da instância VZaps.                                      |
| `instanceToken`    | `string`   | Sim         | Token da instância.                                         |
| `phone`            | `string`   | Sim         | Telefone destino em formato internacional, somente dígitos. |
| `id`               | `string`   | Não         | Identificador opcional da mensagem no pedido.               |
| `delay`            | `number`   | Não         | Atraso de envio, quando suportado pela API.                 |
| `mentionedIds`     | `string[]` | Não         | IDs citados no WhatsApp.                                    |
| `replyToMessageId` | `string`   | Não         | ID da mensagem do WhatsApp a ser respondida/citada.         |

<Note>
  O SDK aceita DTOs para requests principais e arrays para campos adicionais do contrato público. Use os campos documentados aqui quando precisar de recursos avançados como `id`, `delay` ou `replyToMessageId`.
</Note>

## Texto

Função: `$vzaps->messages()->sendText()`

Payload:

| Campo     | Tipo     | Obrigatório |
| --------- | -------- | ----------- |
| `phone`   | `string` | Sim         |
| `message` | `string` | Sim         |

```php theme={null}
$vzaps->messages()->sendText([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'message' => 'Olá, sua instância está conectada.',
    'id' => 'MSG-TXT-001',
    'replyToMessageId' => '3EB020510113BAA6561C',
]);
```

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

Também pode usar DTO:

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

$vzaps->messages()->sendText(new SendTextMessageRequest(
    instanceId: 'VZ...',
    instanceToken: 'instance-token',
    phone: '5511999999999',
    message: 'Olá, sua instância está conectada.',
));
```

## Imagem

Função: `$vzaps->messages()->sendImage()`

Payload:

| Campo     | Tipo     | Obrigatório |
| --------- | -------- | ----------- |
| `phone`   | `string` | Sim         |
| `image`   | `string` | Sim         |
| `caption` | `string` | Não         |

`image` aceita URL pública `https://...` ou data URL base64 (`data:image/<mime>;base64,<dados>`).

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

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## Áudio

Função: `$vzaps->messages()->sendAudio()`

Payload:

| Campo   | Tipo      | Obrigatório |
| ------- | --------- | ----------- |
| `phone` | `string`  | Sim         |
| `audio` | `string`  | Sim         |
| `ptt`   | `boolean` | Não         |

`audio` aceita URL pública ou data URL base64 (`data:audio/<mime>;base64,...`). Use `ptt: true` quando quiser enviar como áudio de voz, se suportado pelo fluxo da conta.

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

## Documento

Função: `$vzaps->messages()->sendDocument()`

Payload:

| Campo      | Tipo     | Obrigatório |
| ---------- | -------- | ----------- |
| `phone`    | `string` | Sim         |
| `document` | `string` | Sim         |
| `fileName` | `string` | Sim         |
| `caption`  | `string` | Não         |

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

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## Vídeo

Função: `$vzaps->messages()->sendVideo()`

Payload:

| Campo           | Tipo     | Obrigatório |
| --------------- | -------- | ----------- |
| `phone`         | `string` | Sim         |
| `video`         | `string` | Sim         |
| `caption`       | `string` | Não         |
| `jpegThumbnail` | `string` | Não         |

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

## Sticker

Função: `$vzaps->messages()->sendSticker()`

Payload:

| Campo          | Tipo     | Obrigatório |
| -------------- | -------- | ----------- |
| `phone`        | `string` | Sim         |
| `sticker`      | `string` | Sim         |
| `pngThumbnail` | `string` | Não         |

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

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## GIF

Função: `$vzaps->messages()->sendGif()`

Payload:

| Campo     | Tipo     | Obrigatório |
| --------- | -------- | ----------- |
| `phone`   | `string` | Sim         |
| `gif`     | `string` | Sim         |
| `caption` | `string` | Não         |

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

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## Localização

Função: `$vzaps->messages()->sendLocation()`

Payload:

| Campo       | Tipo     | Obrigatório |
| ----------- | -------- | ----------- |
| `phone`     | `string` | Sim         |
| `latitude`  | `number` | Sim         |
| `longitude` | `number` | Sim         |
| `name`      | `string` | Não         |
| `address`   | `string` | Não         |

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

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## Contato

Função: `$vzaps->messages()->sendContact()`

Payload:

| Campo          | Tipo     | Obrigatório |
| -------------- | -------- | ----------- |
| `phone`        | `string` | Sim         |
| `contactName`  | `string` | Sim         |
| `contactPhone` | `string` | Sim         |

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

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## Botões

Função: `$vzaps->messages()->sendButtons()`

Payload:

| Campo     | Tipo                                          | Obrigatório |
| --------- | --------------------------------------------- | ----------- |
| `phone`   | `string`                                      | Sim         |
| `message` | `string`                                      | Sim         |
| `buttons` | `array<int, array{id: string, text: string}>` | Sim         |
| `footer`  | `string`                                      | Não         |

```php theme={null}
$vzaps->messages()->sendButtons([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'message' => 'Escolha uma opção',
    'footer' => 'VZaps',
    'buttons' => [
        ['id' => 'sales', 'text' => 'Comercial'],
        ['id' => 'support', 'text' => 'Suporte'],
    ],
]);
```

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## Lista

Função: `$vzaps->messages()->sendList()`

Payload:

| Campo         | Tipo     | Obrigatório |
| ------------- | -------- | ----------- |
| `phone`       | `string` | Sim         |
| `title`       | `string` | Sim         |
| `description` | `string` | Sim         |
| `buttonText`  | `string` | Sim         |
| `sections`    | `array`  | Sim         |
| `footer`      | `string` | Não         |

```php theme={null}
$vzaps->messages()->sendList([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'title' => 'Menu principal',
    'description' => 'Escolha uma opção',
    'buttonText' => 'Abrir menu',
    'sections' => [
        [
            'title' => 'Departamentos',
            'rows' => [
                ['id' => 'sales', 'title' => 'Comercial', 'description' => 'Falar com vendas'],
                ['id' => 'support', 'title' => 'Suporte', 'description' => 'Falar com suporte'],
            ],
        ],
    ],
]);
```

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## Link com preview

Função: `$vzaps->messages()->sendLink()`

Payload:

| Campo             | Tipo     | Obrigatório |
| ----------------- | -------- | ----------- |
| `phone`           | `string` | Sim         |
| `message`         | `string` | Sim         |
| `linkUrl`         | `string` | Sim         |
| `title`           | `string` | Sim         |
| `linkDescription` | `string` | Sim         |
| `jpegThumbnail`   | `string` | Não         |

```php theme={null}
$vzaps->messages()->sendLink([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'message' => 'Confira este link',
    'linkUrl' => 'https://vzaps.com',
    'title' => 'VZaps',
    'linkDescription' => 'API de WhatsApp para integrações',
]);
```

## Enquete

Função: `$vzaps->messages()->sendPoll()`

Payload:

| Campo                    | Tipo       | Obrigatório |
| ------------------------ | ---------- | ----------- |
| `phone`                  | `string`   | Sim         |
| `name`                   | `string`   | Sim         |
| `options`                | `string[]` | Sim         |
| `selectableOptionsCount` | `number`   | Não         |
| `hideParticipantNames`   | `boolean`  | Não         |
| `endTime`                | `string`   | Não         |
| `allowAddOption`         | `boolean`  | Não         |

```php theme={null}
$vzaps->messages()->sendPoll([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'phone' => '5511999999999',
    'name' => 'Qual canal você prefere?',
    'options' => ['WhatsApp', 'Email', 'Telefone'],
    'selectableOptionsCount' => 1,
]);
```

**Retorno:** envelope `{ code, success, data.message_id }` — mensagem aceita/enfileirada.

## Votar em enquete

Função: `$vzaps->messages()->pollVote()`

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

## Reagir e remover reação

Funções:

* `$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',
]);
```

## Presença e leitura

Funções:

* `$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',
]);
```

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

## Editar e deletar mensagem

Funções:

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

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

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

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

## Download de mídia

Funções:

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

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

print_r($media);
```

**Retorno:** envelope `{ code, success, data }` com `data.mimetype` e `data.data` (base64 ou data URL).

## Resposta padrão

Os métodos de envio retornam um envelope da API indicando que a mensagem foi aceita/enfileirada.

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

print_r($result);
```

Consulte a [Referência da API](/pt-BR/api-reference/introduction) para os schemas de resposta mais recentes.