> ## 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 Python SDK send function, accepted payloads, and complete examples

All send functions live under `client.messages`.

In the SDK, the instance `id` becomes `instance_id`, and the `X-Instance-Token` header becomes `instance_token`.

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

## Common fields

Most send operations accept these fields:

| Field                 | Type        | Required | Description                                            |
| --------------------- | ----------- | -------- | ------------------------------------------------------ |
| `instance_id`         | `string`    | Yes      | VZaps instance ID.                                     |
| `instance_token`      | `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.                 |
| `mentioned_ids`       | `list[str]` | No       | WhatsApp IDs to mention.                               |
| `reply_to_message_id` | `string`    | No       | WhatsApp message ID to reply to or quote.              |

<Note>
  Request dicts accept additional public API fields beyond those listed here. Use the fields documented on this page when you need advanced options such as `id`, `delay`, or `reply_to_message_id`.
</Note>

## Text

Function: `client.messages.send_text()`

Payload:

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

```python theme={null}
client.messages.send_text(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Hello, your instance is connected.",
    id="MSG-TXT-001",
    reply_to_message_id="3EB020510113BAA6561C",
)
```

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

## Image

Function: `client.messages.send_image()`

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

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

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.

```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,
)
```

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

## Document

Function: `client.messages.send_document()`

Payload:

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

```python theme={null}
client.messages.send_document(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    document="https://cdn.example.com/contract.pdf",
    file_name="contract.pdf",
    caption="Here is the contract",
)
```

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

## Video

Function: `client.messages.send_video()`

Payload:

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

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

Payload:

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

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

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

## GIF

Function: `client.messages.send_gif()`

Payload:

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

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

Payload:

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

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

Payload:

| Field           | Type     | Required |
| --------------- | -------- | -------- |
| `phone`         | `string` | Yes      |
| `contact_name`  | `string` | Yes      |
| `contact_phone` | `string` | Yes      |

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

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

## Buttons

Function: `client.messages.send_buttons()`

Payload:

| Field     | Type         | Required |
| --------- | ------------ | -------- |
| `phone`   | `string`     | Yes      |
| `message` | `string`     | Yes      |
| `buttons` | `list[dict]` | Yes      |
| `footer`  | `string`     | No       |

Each button: `{"id": "...", "text": "..."}`.

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

Payload:

| Field         | Type         | Required |
| ------------- | ------------ | -------- |
| `phone`       | `string`     | Yes      |
| `title`       | `string`     | Yes      |
| `description` | `string`     | Yes      |
| `button_text` | `string`     | Yes      |
| `sections`    | `list[dict]` | Yes      |
| `footer`      | `string`     | No       |

```python theme={null}
client.messages.send_list(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    title="Main menu",
    description="Choose an option",
    button_text="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: `client.messages.send_link()`

Payload:

| Field              | Type     | Required |
| ------------------ | -------- | -------- |
| `phone`            | `string` | Yes      |
| `message`          | `string` | Yes      |
| `link_url`         | `string` | Yes      |
| `title`            | `string` | Yes      |
| `link_description` | `string` | Yes      |
| `jpeg_thumbnail`   | `string` | No       |

```python theme={null}
client.messages.send_link(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Check this link",
    link_url="https://vzaps.com",
    title="VZaps",
    link_description="WhatsApp API for integrations",
)
```

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

## Poll

Function: `client.messages.send_poll()`

Payload:

| Field                      | Type        | Required |
| -------------------------- | ----------- | -------- |
| `phone`                    | `string`    | Yes      |
| `name`                     | `string`    | Yes      |
| `options`                  | `list[str]` | Yes      |
| `selectable_options_count` | `number`    | No       |
| `hide_participant_names`   | `boolean`   | No       |
| `end_time`                 | `string`    | No       |
| `allow_add_option`         | `boolean`   | No       |

```python theme={null}
client.messages.send_poll(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    name="Which channel do you prefer?",
    options=["WhatsApp", "Email", "Phone"],
    selectable_options_count=1,
)
```

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

## Vote in a poll

Function: `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"],
)
```

## React and remove reaction

Functions:

* `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",
)
```

## Presence and read receipts

Functions:

* `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",
)
```

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

## Edit and delete message

Functions:

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

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

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

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

## Download media

Functions:

* `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)
```

## Standard response

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

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

print(result)
```

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