Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://developer.z-api.io/llms.txt

Use this file to discover all available pages before exploring further.

Retorno do webhook

Atributos do retorno

Todos os retornos do webhook Ao enviar possuem os seguintes atributos:
phone
string
Número de telefone de destino da mensagem
messageId
string
Identificador da mensagem no WhatsApp
zaapId
string
Identificador da mensagem na conversa
instanceId
string
Identificador da instância
momment
integer
Momento em que o evento foi disparado (timestamp em milissegundos)
type
string
Tipo do evento da instância, nesse caso será sempre DeliveryCallback
error
string
Presente apenas em casos de erro. Contém a descrição do erro ocorrido no envio da mensagem

Exemplos de retorno

Sucesso

Quando a mensagem é enviada com sucesso, o retorno não contém o campo error:
{
  "phone": "554499999999",
  "messageId": "A800FB3697F1DE58C48D",
  "instanceId": "instance.id",
  "zaapId": "A20DA9C0183A2D35A260F53F5D2B9244",
  "momment": 1777494009341,
  "type": "DeliveryCallback"
}

Erro

Quando ocorre um erro no envio, o retorno inclui o campo error com a descrição do problema:
{
  "phone": "554499999999",
  "messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
  "error": "Phone number does not exist",
  "instanceId": "instance.id",
  "zaapId": "A20DA9C0183A2D35A260F53F5D2B9244",
  "momment": 1777494091684,
  "type": "DeliveryCallback"
}
Não é possível filtrar os eventos recebidos pelo webhook. Todos os eventos de envio — sejam de sucesso ou erro — são disparados juntos, sem distinção de tipo no disparo. O tratamento deve ser feito na sua aplicação verificando a presença ou ausência do campo error no payload recebido.

Erros possíveis no campo error

Permissão e Restrições do WhatsApp

O WhatsApp bloqueou o envio desta mensagem por restrições de permissão.
O WhatsApp rejeitou o envio. Isso pode ocorrer por restrições na conta, como shadow ban ou limitações para iniciar conversas.
O WhatsApp não permitiu o envio desta mensagem.
Sua conta não tem autorização para enviar esta mensagem.
Você não tem permissão para enviar mensagens neste grupo.
Este tipo de mensagem só pode ser enviado em grupos, não em conversas privadas.
É necessário aceitar os termos de uso de mensagens com botões no painel antes de enviar.

Timeout e Conexão

O tempo para enviar a mensagem expirou. Isso pode acontecer por instabilidade na conexão com o WhatsApp.
Ocorreu um erro de conexão no sistema ao tentar enviar a mensagem.

Número de Telefone Inválido

O número de telefone informado não existe no WhatsApp.
O número de telefone está em um formato inválido. Verifique e tente novamente.

Mídia e URL

A URL da mídia (imagem, vídeo, áudio ou documento) é inválida ou está inacessível.
A URL da mídia não foi encontrada (erro 404). Verifique se o link está correto.
A URL informada não aponta para um arquivo de mídia. O link retorna uma página web em vez de um arquivo.
O formato do arquivo de sticker não é suportado. O WhatsApp aceita apenas imagens como sticker.

Edição e Tempo Limite de Mensagens

Não é possível editar uma mensagem enviada há mais de 7 dias. O WhatsApp só permite edições dentro desse prazo.
Não é possível comentar em uma mensagem enviada há mais de 7 dias.
O ID do produto informado não foi encontrado. Verifique se o produto existe no seu catálogo.
O catálogo informado não foi encontrado. Verifique se o catálogo está configurado corretamente.
O número usado para buscar o produto no catálogo não pode ser um identificador temporário. Use o número real do telefone.

Pedidos (Orders)

O código da moeda informado no pedido é inválido. Verifique se está usando um código de moeda válido (ex: BRL, USD).
Os dados enviados para atualizar o pedido estão inválidos. Verifique as informações e tente novamente.

Eventos e Newsletter

Não foi possível enviar o voto na enquete porque o identificador da enquete está faltando.
Mensagens de evento só podem ser enviadas em grupos, não em conversas privadas.
A data e hora informadas para o evento são inválidas. Verifique o formato e tente novamente.

Status e Respostas

A mensagem de status original que você tentou responder não foi encontrada.

Encaminhamento

A mensagem que você tentou encaminhar não foi encontrada. Ela pode ter sido deletada.

Conversão e Parâmetros

Ocorreu um erro ao converter a mensagem para o formato compatível com o WhatsApp.
Os parâmetros enviados na requisição estão inválidos. Verifique os dados e tente novamente.

Tipos de Mensagem Não Suportados em Canais (Newsletters)

Não é possível modificar configurações de chat em canais.
Não é possível fazer chamadas para canais.
Não é possível enviar chamadas com áudio para canais.
Não é possível enviar documentos para canais.
Não é possível enviar respostas de botões para canais.
Não é possível enviar vídeos PTV para canais.
Não é possível enviar localização para canais.
Não é possível enviar contatos para canais.
Não é possível enviar botões de ação para canais.
Não é possível enviar mensagens com botões para canais.
Não é possível enviar listas de opções para canais.
Não é possível enviar solicitações de pagamento para canais.
Não é possível configurar expiração de chat em canais.
Não é possível fixar mensagens em canais.
Não é possível enviar botões de Pix para canais.

Falha no Processamento da Fila

A mensagem foi recebida pelo sistema, mas ocorreu uma falha no processamento interno de enfileiramento. A mensagem não foi adicionada à fila de envio.