> ## 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 TypeScript, 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`.

```ts theme={null}
const 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 é tipado, mas também permite campos adicionais do contrato público em objetos de request. 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         |

```ts theme={null}
await 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.messageId }` — mensagem aceita/enfileirada.

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

```ts theme={null}
await 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.messageId }` — 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.

```ts theme={null}
await 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         |

```ts theme={null}
await 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.messageId }` — 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         |

```ts theme={null}
await 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         |

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

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

## GIF

Função: `vzaps.messages.sendGif()`

Payload:

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

```ts theme={null}
await 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.messageId }` — 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         |

```ts theme={null}
await 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.messageId }` — mensagem aceita/enfileirada.

## Contato

Função: `vzaps.messages.sendContact()`

Payload:

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

```ts theme={null}
await vzaps.messages.sendContact({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  contactName: 'Maria Silva',
  contactPhone: '5511888888888',
});
```

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

## Botões

Função: `vzaps.messages.sendButtons()`

Payload:

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

```ts theme={null}
await 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.messageId }` — 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`    | `MessageListSection[]` | Sim         |
| `footer`      | `string`               | Não         |

```ts theme={null}
await 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.messageId }` — 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         |

```ts theme={null}
await 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         |

```ts theme={null}
await 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.messageId }` — mensagem aceita/enfileirada.

## Votar em enquete

Função: `vzaps.messages.pollVote()`

```ts theme={null}
await 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()`

```ts theme={null}
await vzaps.messages.react({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  messageId: '3EB020510113BAA6561C',
  reaction: '👍',
});

await vzaps.messages.removeReaction({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  messageId: '3EB020510113BAA6561C',
});
```

## Presença e leitura

Funções:

* `vzaps.messages.presence()`
* `vzaps.messages.markRead()`

```ts theme={null}
await vzaps.messages.presence({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  state: 'composing',
});

await 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()`

```ts theme={null}
await vzaps.messages.edit({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  messageId: '3EB020510113BAA6561C',
  message: 'Texto editado',
});

await 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()`

```ts theme={null}
const media = await vzaps.messages.downloadImage({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
});

console.dir(media, { depth: null });
```

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

```ts theme={null}
const result = await vzaps.messages.sendText({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  message: 'Olá',
});

console.dir(result, { depth: null });
```

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