Z-API (WhatsApp)

Receber e enviar mensagens, mídias, botões, listas e catálogo do WhatsApp por uma instância Z-API.

Integrações e ferramentasComunicaçãoConexão: Credencial protegida

O que faz

WhatsApp pela sua instância Z-API: recebe as mensagens dos clientes e envia texto, mídias, botões, listas e catálogo.

Quando usar: Use quando o seu fluxo precisar receber e enviar mensagens, mídias, botões, listas e catálogo do WhatsApp por uma instância Z-API.

Exemplo de situação: Enviar uma confirmação ao cliente ou à equipe no canal correto.

Antes de começar

Conexão necessária: Credencial protegida.

Escolha uma conexão ou credencial já cadastrada no workspace. Nunca cole senhas ou chaves em campos de texto comuns.

Passo a passo

Adicione Z-API (WhatsApp) ao desenho a partir da aba Blocos e ligue a entrada dele à etapa anterior.
Escolha uma conexão ou credencial já cadastrada no workspace. Nunca cole senhas ou chaves em campos de texto comuns.
Escolha a operação. O painel mostra só os campos que essa operação usa.
Preencha os campos obrigatórios. Para usar um dado de uma etapa anterior, digite < e escolha o bloco e o campo.
Clique em Executar com dados de teste e confira, no terminal, o que entrou e o que saiu do bloco.
Só publique depois de conferir o resultado da execução de teste.

Operações

Operação	O que faz
Enviar texto	Envia texto com o bloco Z-API (WhatsApp).
Enviar imagem	Envia imagem com o bloco Z-API (WhatsApp).
Enviar áudio	Envia áudio com o bloco Z-API (WhatsApp).
Enviar vídeo	Envia vídeo com o bloco Z-API (WhatsApp).
Enviar documento	Envia documento com o bloco Z-API (WhatsApp).
Enviar link com prévia	Envia link com prévia com o bloco Z-API (WhatsApp).
Enviar produto do catálogo	Envia produto do catálogo com o bloco Z-API (WhatsApp).
Enviar botões de resposta rápida	Envia botões de resposta rápida com o bloco Z-API (WhatsApp).
Enviar lista de opções	Envia lista de opções com o bloco Z-API (WhatsApp).
Enviar catálogo	Envia catálogo com o bloco Z-API (WhatsApp).
Status da instância	Executa a operação “Status da instância” com o bloco Z-API (WhatsApp).

Campos

Mostrar campos de

Operação
Escolhe qual ação este bloco executará.
Opções:
Enviar texto · Enviar imagem · Enviar áudio · Enviar vídeo · Enviar documento · Enviar link com prévia · Enviar produto do catálogo · Enviar botões de resposta rápida · Enviar lista de opções · Enviar catálogo · Status da instância
Padrão:
Enviar texto
Instância Z-API
Obrigatório
Escolha uma instância conectada.
Exemplo:
(escolha na lista do campo)
ID da instância
ObrigatórioEm campos adicionais
Painel Z-API → sua instância → Editar.
Exemplo:
id-do-recurso
Token da instância
ObrigatórioEm campos adicionaisDado protegido
Informa uma credencial secreta. Guarde-a no cofre de credenciais e nunca a exponha em texto livre.
Padrão:
Segredo protegido
Token de segurança da conta (Client-Token)
Em campos adicionaisDado protegido
Só se você ativou em Segurança no painel Z-API.
Padrão:
Segredo protegido
Telefone / ID do chat
Identifica a conversa, o canal ou o telefone de destino.
Quando aparece:
Quando o campo “Operação” for diferente de “Status da instância” ou “update_webhook_received” ou “update_every_webhooks”
Exemplo:
+5511999999999
Mensagem
Informa a mensagem que será enviada ou processada.
Aparece em:
Enviar texto, Enviar link com prévia, Enviar catálogo, Enviar botões de resposta rápida, Enviar lista de opções
Exemplo:
Olá! Sua solicitação foi processada com sucesso.
Imagem (URL ou base64)
Imagem a enviar pela Z-API, como link público ou conteúdo em base64; em Enviar link com prévia, é a miniatura que aparece no cartão do link (ex.: https://minhaempresa.com.br/promo.jpg).
Aparece em:
Enviar imagem, Enviar link com prévia
Áudio (URL ou base64)
Áudio a enviar pela Z-API, como link público do arquivo ou conteúdo em base64 (ex.: https://minhaempresa.com.br/aviso.mp3).
Aparece em:
Enviar áudio
Vídeo (URL ou base64)
Vídeo a enviar pela Z-API, como link público do arquivo ou conteúdo em base64 (ex.: https://minhaempresa.com.br/tutorial.mp4).
Aparece em:
Enviar vídeo
Endereço HTTPS do link
Obrigatório conforme a operação
Informa o endereço seguro do serviço ou recurso que será acessado.
Aparece em:
Enviar link com prévia
Exemplo:
https://api.exemplo.com/v1/recurso
Título
Obrigatório conforme a operação
Define o nome ou título usado para identificar o recurso.
Aparece em:
Enviar link com prévia, Enviar catálogo
Exemplo:
Exemplo de atendimento
Descrição da prévia
Obrigatório conforme a operação
Informa o conteúdo de texto que será enviado ou processado.
Aparece em:
Enviar link com prévia
Exemplo:
https://api.exemplo.com/v1/recurso
Telefone da conta dona do catálogo
Obrigatório conforme a operação
Identifica a conversa, o canal ou o telefone de destino.
Aparece em:
Enviar produto do catálogo, Enviar catálogo
Exemplo:
+5511999999999
Descrição do catálogo
Informa o conteúdo de texto que será enviado ou processado.
Aparece em:
Enviar catálogo
Idioma do cartão
Escolhe uma das opções aceitas por este campo.
Aparece em:
Enviar catálogo
Opções:
Português · Inglês
Padrão:
Português
Identificador do produto existente
Obrigatório conforme a operação
Informa o identificador exato do recurso na plataforma conectada.
Aparece em:
Enviar produto do catálogo
Exemplo:
id-do-recurso
Documento (URL ou base64)
Informa ou seleciona o arquivo usado nesta operação.
Aparece em:
Enviar documento
Extensão do arquivo
Extensão do documento enviado pela Z-API, sem o ponto, para o WhatsApp abrir no formato certo (ex.: pdf, xlsx ou docx).
Aparece em:
Enviar documento
Exemplo:
pdf, xlsx, docx…
Nome do arquivo
Informa ou seleciona o arquivo usado nesta operação.
Aparece em:
Enviar documento
Exemplo:
Exemplo de atendimento
Legenda
Em campos adicionais
Informa o conteúdo de texto que será enviado ou processado.
Aparece em:
Enviar imagem, Enviar vídeo, Enviar documento
Exemplo:
Olá! Sua solicitação foi processada com sucesso.
Botões de resposta rápida (JSON)
Informa dados estruturados ou código no formato exigido pelo campo.
Aparece em:
Enviar botões de resposta rápida
Exemplo:
{ "chave": "valor" }
Lista de opções (JSON)
Informa dados estruturados ou código no formato exigido pelo campo.
Aparece em:
Enviar lista de opções
Exemplo:
{ "chave": "valor" }
ID da mensagem (responder citando)
Em campos adicionais
Informa o identificador exato do recurso na plataforma conectada.
Aparece em:
Enviar imagem, Enviar texto, Enviar documento
Exemplo:
id-do-recurso
Visualização única
Em campos adicionais
Ativa ou desativa este comportamento.
Aparece em:
Enviar imagem, Enviar áudio, Enviar vídeo
Exemplo:
false
Atraso antes de enviar (s)
Em campos adicionais
Informa o conteúdo de texto que será enviado ou processado.
Aparece em:
Enviar texto, Enviar imagem, Enviar áudio
Exemplo:
Olá! Sua solicitação foi processada com sucesso.
Tempo "digitando" (s)
Em campos adicionais
Por quantos segundos o contato vê o aviso “digitando…” antes de a mensagem chegar, para a conversa parecer mais natural (ex.: 3).
Aparece em:
Enviar texto, Enviar áudio

Saídas

Para usar um resultado deste bloco em uma etapa seguinte, digite < no campo e escolha o bloco e o campo. A referência tem o formato <zapiwhatsapp.response>: antes do ponto vai o nome do bloco no seu fluxo, em minúsculas, sem espaços e sem acentos.

Referência	Tipo	O que contém
`<zapiwhatsapp.response>`	json	Mensagem enviada, status da instância ou confirmação de webhook.

Exemplo de uso

Objetivo: Enviar uma confirmação ao cliente ou à equipe no canal correto.

InícioZ-API (WhatsApp)próxima etapa

Operação: Enviar texto
Instância Z-API: (escolha na lista do campo)
Telefone / ID do chat: +5511999999999
Mensagem: Olá! Sua solicitação foi processada com sucesso.

Os valores são ilustrativos. Teste primeiro com dados fictícios ou de homologação.

Erros comuns e como resolver

O bloco não executa: Confira se existe um caminho de setas que parte do gatilho (ou do Início) até este bloco. Blocos soltos no desenho são ignorados.
Aparece “Validação do fluxo” no terminal: Há campo obrigatório vazio. Clique no aviso, abra o bloco indicado e preencha o campo marcado.
Um campo chega vazio na etapa seguinte: Confira se a referência aponta para um bloco que já executou e para um campo que existe, como <zapiwhatsapp.response>. O nome antes do ponto é o nome do bloco no seu fluxo, em minúsculas, sem espaços e sem acentos.
O campo que eu procuro não aparece: Os campos mudam conforme a operação escolhida. Escolha a operação primeiro; campos menos usados ficam em “Mostrar campos adicionais”.
Credencial ausente ou recusada: Escolha uma conexão válida do workspace. Se a senha ou a chave mudou no serviço, atualize a conexão cadastrada em vez de colar o segredo no bloco.
O serviço recusou a chamada ou devolveu erro: Leia a mensagem no terminal: ela traz o motivo informado pelo serviço. Confira IDs, limites de uso e permissões, e teste antes com um recurso de homologação.

O que faz

Antes de começar

Passo a passo

Operações

Campos

Operação

Instância Z-API

ID da instância

Token da instância

Token de segurança da conta (Client-Token)

Telefone / ID do chat

Mensagem

Imagem (URL ou base64)

Áudio (URL ou base64)

Vídeo (URL ou base64)

Endereço HTTPS do link

Título

Descrição da prévia

Telefone da conta dona do catálogo

Descrição do catálogo

Idioma do cartão

Identificador do produto existente

Documento (URL ou base64)

Extensão do arquivo

Nome do arquivo

Legenda

Botões de resposta rápida (JSON)

Lista de opções (JSON)

ID da mensagem (responder citando)

Visualização única

Atraso antes de enviar (s)

Tempo "digitando" (s)

Saídas

Exemplo de uso

Erros comuns e como resolver

Blocos relacionados