Mensagens - VZaps Docs

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.

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.

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.

Texto

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

print(result)

Consulte a referência da API para os schemas de resposta mais recentes.

​Campos comuns

​Texto

​Imagem

​Áudio

​Documento

​Vídeo

​Sticker

​GIF

​Localização

​Contato

​Botões

​Lista

​Link com preview

​Enquete

​Votar em enquete

​Reagir e remover reação

​Presença e leitura

​Editar e deletar mensagem

​Download de mídia

​Resposta padrão

Campos comuns

Texto

Imagem

Áudio

Documento

Vídeo

Sticker

GIF

Localização

Contato

Botões

Lista

Link com preview

Enquete

Votar em enquete

Reagir e remover reação

Presença e leitura

Editar e deletar mensagem

Download de mídia

Resposta padrão