> ## 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 Python, payloads aceitos e exemplos completos

Todas as funções de envio ficam em `client.messages`.

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

```python theme={null}
base = {
    "instance_id": "VZ...",
    "instance_token": "instance-token",
    "phone": "5511999999999",
}
```

## Campos comuns

Quase todos os envios aceitam os campos abaixo:

| Campo                 | Tipo        | Obrigatório | Descrição                                                   |
| --------------------- | ----------- | ----------- | ----------------------------------------------------------- |
| `instance_id`         | `string`    | Sim         | ID da instância VZaps.                                      |
| `instance_token`      | `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.                 |
| `mentioned_ids`       | `list[str]` | Não         | IDs citados no WhatsApp.                                    |
| `reply_to_message_id` | `string`    | Não         | ID da mensagem do WhatsApp a ser respondida ou citada.      |

<Note>
  Os dicts de request aceitam campos adicionais do contrato público além dos listados aqui. Use os campos documentados nesta página quando precisar de recursos avançados como `id`, `delay` ou `reply_to_message_id`.
</Note>

## Texto

Função: `client.messages.send_text()`

Payload:

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

```python theme={null}
client.messages.send_text(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Olá, sua instância está conectada.",
    id="MSG-TXT-001",
    reply_to_message_id="3EB020510113BAA6561C",
)
```

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

## Imagem

Função: `client.messages.send_image()`

Payload:

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

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

```python theme={null}
client.messages.send_image(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    image="https://cdn.example.com/foto.jpg",
    caption="Legenda opcional",
)
```

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

## Áudio

Função: `client.messages.send_audio()`

Payload:

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

`audio` aceita URL pública ou data URL em base64 (`data:audio/<mime>;base64,...`). Use `ptt=True` para enviar nota de voz, se suportado no fluxo da conta.

```python theme={null}
client.messages.send_audio(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    audio="https://cdn.example.com/audio.mp3",
    ptt=False,
)
```

## Documento

Função: `client.messages.send_document()`

Payload:

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

```python theme={null}
client.messages.send_document(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    document="https://cdn.example.com/contrato.pdf",
    file_name="contrato.pdf",
    caption="Aqui está o contrato",
)
```

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

## Vídeo

Função: `client.messages.send_video()`

Payload:

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

```python theme={null}
client.messages.send_video(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    video="https://cdn.example.com/video.mp4",
    caption="Vídeo de demonstração",
)
```

## Sticker

Função: `client.messages.send_sticker()`

Payload:

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

```python theme={null}
client.messages.send_sticker(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    sticker="https://cdn.example.com/sticker.webp",
)
```

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

## GIF

Função: `client.messages.send_gif()`

Payload:

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

```python theme={null}
client.messages.send_gif(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    gif="https://media.giphy.com/media/exemplo/giphy.gif",
    caption="GIF animado",
)
```

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

## Localização

Função: `client.messages.send_location()`

Payload:

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

```python theme={null}
client.messages.send_location(
    instance_id="VZ...",
    instance_token="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: `client.messages.send_contact()`

Payload:

| Campo           | Tipo     | Obrigatório |
| --------------- | -------- | ----------- |
| `phone`         | `string` | Sim         |
| `contact_name`  | `string` | Sim         |
| `contact_phone` | `string` | Sim         |

```python theme={null}
client.messages.send_contact(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    contact_name="Maria Silva",
    contact_phone="5511888888888",
)
```

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

## Botões

Função: `client.messages.send_buttons()`

Payload:

| Campo     | Tipo         | Obrigatório |
| --------- | ------------ | ----------- |
| `phone`   | `string`     | Sim         |
| `message` | `string`     | Sim         |
| `buttons` | `list[dict]` | Sim         |
| `footer`  | `string`     | Não         |

Cada botão: `{"id": "...", "text": "..."}`.

```python theme={null}
client.messages.send_buttons(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Escolha uma opção",
    footer="VZaps",
    buttons=[
        {"id": "vendas", "text": "Vendas"},
        {"id": "suporte", "text": "Suporte"},
    ],
)
```

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

## Lista

Função: `client.messages.send_list()`

Payload:

| Campo         | Tipo         | Obrigatório |
| ------------- | ------------ | ----------- |
| `phone`       | `string`     | Sim         |
| `title`       | `string`     | Sim         |
| `description` | `string`     | Sim         |
| `button_text` | `string`     | Sim         |
| `sections`    | `list[dict]` | Sim         |
| `footer`      | `string`     | Não         |

```python theme={null}
client.messages.send_list(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    title="Menu principal",
    description="Escolha uma opção",
    button_text="Abrir menu",
    sections=[
        {
            "title": "Departamentos",
            "rows": [
                {"id": "vendas", "title": "Vendas", "description": "Falar com vendas"},
                {"id": "suporte", "title": "Suporte", "description": "Falar com suporte"},
            ],
        },
    ],
)
```

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

## Link com preview

Função: `client.messages.send_link()`

Payload:

| Campo              | Tipo     | Obrigatório |
| ------------------ | -------- | ----------- |
| `phone`            | `string` | Sim         |
| `message`          | `string` | Sim         |
| `link_url`         | `string` | Sim         |
| `title`            | `string` | Sim         |
| `link_description` | `string` | Sim         |
| `jpeg_thumbnail`   | `string` | Não         |

```python theme={null}
client.messages.send_link(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Confira este link",
    link_url="https://vzaps.com",
    title="VZaps",
    link_description="API WhatsApp para integrações",
)
```

## Enquete

Função: `client.messages.send_poll()`

Payload:

| Campo                      | Tipo        | Obrigatório |
| -------------------------- | ----------- | ----------- |
| `phone`                    | `string`    | Sim         |
| `name`                     | `string`    | Sim         |
| `options`                  | `list[str]` | Sim         |
| `selectable_options_count` | `number`    | Não         |
| `hide_participant_names`   | `boolean`   | Não         |
| `end_time`                 | `string`    | Não         |
| `allow_add_option`         | `boolean`   | Não         |

```python theme={null}
client.messages.send_poll(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    name="Qual canal você prefere?",
    options=["WhatsApp", "E-mail", "Telefone"],
    selectable_options_count=1,
)
```

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

## Votar em enquete

Função: `client.messages.poll_vote()`

```python theme={null}
client.messages.poll_vote(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message_id="3EB020510113BAA6561C",
    selected_options=["WhatsApp"],
)
```

## Reagir e remover reação

Funções:

* `client.messages.react()`
* `client.messages.remove_reaction()`

```python theme={null}
client.messages.react(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message_id="3EB020510113BAA6561C",
    reaction="👍",
)

client.messages.remove_reaction(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message_id="3EB020510113BAA6561C",
)
```

## Presença e leitura

Funções:

* `client.messages.presence()`
* `client.messages.mark_read()`

```python theme={null}
client.messages.presence(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    state="composing",
)

client.messages.mark_read(
    instance_id="VZ...",
    instance_token="instance-token",
    id=["3EB020510113BAA6561C"],
    chat="5511999999999@s.whatsapp.net",
)
```

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

## Editar e deletar mensagem

Funções:

* `client.messages.edit()`
* `client.messages.delete()`

```python theme={null}
client.messages.edit(
    instance_id="VZ...",
    instance_token="instance-token",
    message_id="3EB020510113BAA6561C",
    message="Texto editado",
)

client.messages.delete(
    instance_id="VZ...",
    instance_token="instance-token",
    message_id="3EB020510113BAA6561C",
)
```

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

## Download de mídia

Funções:

* `download_image()`
* `download_video()`
* `download_audio()`
* `download_document()`

```python theme={null}
media = client.messages.download_image(
    instance_id="VZ...",
    instance_token="instance-token",
)

print(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 ou enfileirada.

```python theme={null}
result = client.messages.send_text(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Olá",
)

print(result)
```

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