Messages - VZaps Docs

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.

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.

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.

Text

Function: client.messages.send_text() Payload:

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

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

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.

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

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

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

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

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

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

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": "..."}.

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

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

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

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

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

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

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

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

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.

result = client.messages.send_text(
    instance_id="VZ...",
    instance_token="instance-token",
    phone="5511999999999",
    message="Hello",
)

print(result)

See the API reference for the latest response schemas.