Tipos de mensagem do WhatsApp via API: enquete, localização, contato, evento e mais

Quase todo tutorial de "WhatsApp via API" para no envio de texto e, no máximo, imagem. Mas a API REST de mensagens vai muito além: você consegue mandar enquetes, localização, cartão de contato, eventos com confirmação de presença, figurinhas e links com pré-visualização — cada um com um corpo JSON específico. Este artigo é o catálogo completo, com o campo exato de cada tipo e um exemplo pronto para copiar.

Todos os envios usam o mesmo endpoint, mudando apenas o campo type e os campos do corpo:

POST https://api.zap-api.tech/v1/instances/{id}/send
Authorization: Bearer tk_SEU_TOKEN
Content-Type: application/json

Dois campos são comuns a todos: phone (só dígitos, com DDI, sem "+" nem espaços — ex.: 5511999998888; também aceita o JID de um grupo terminado em @g.us) e type. O campo quotedMessageId é opcional e cita/responde uma mensagem.

Texto, mídia e figurinha

// texto
{"phone":"5511999998888","type":"text","body":"Olá!"}

// imagem (mediaUrl precisa ser URL pública)
{"phone":"5511999998888","type":"image","mediaUrl":"https://site.com/foto.jpg","caption":"Promo de hoje"}

// documento (fileName é obrigatório)
{"phone":"5511999998888","type":"document","mediaUrl":"https://site.com/nota.pdf","fileName":"NotaFiscal.pdf"}

// figurinha
{"phone":"5511999998888","type":"sticker","mediaUrl":"https://site.com/fig.webp"}

Os tipos de mídia são image, video, gif (todos aceitam caption opcional), audio e document. O segredo é a mediaUrl: precisa abrir sem login num navegador anônimo. Se não abrir lá, a API também não baixa.

Enquete (poll)

Enquete nativa do WhatsApp, com 2 a 12 opções. selectableCount define quantas o destinatário pode marcar (1 = escolha única).

{
  "phone": "5511999998888",
  "type": "poll",
  "name": "Qual o melhor horário para a reunião?",
  "options": ["09h", "14h", "18h"],
  "selectableCount": 1
}

Localização

{
  "phone": "5511999998888",
  "type": "location",
  "latitude": -23.561414,
  "longitude": -46.655881,
  "name": "Nossa loja",
  "address": "Av. Paulista, 1000 - São Paulo"
}

Contato (vCard)

{
  "phone": "5511999998888",
  "type": "contact",
  "contactName": "Suporte ZAP",
  "contactPhone": "5511988887777",
  "contactOrganization": "Minha Empresa"
}

Evento com confirmação de presença

O event aparece como um card nativo com botão de confirmar presença e opção de adicionar ao calendário. startAt usa ISO 8601.

{
  "phone": "5511999998888",
  "type": "event",
  "name": "Live de lançamento",
  "startAt": "2026-07-10T19:00:00Z",
  "location": "Online",
  "callLink": "https://meet.exemplo.com/live"
}

Link com pré-visualização

{
  "phone": "5511999998888",
  "type": "link",
  "url": "https://minhaloja.com/oferta",
  "title": "Oferta da semana",
  "description": "Até 40% off"
}

Perguntas frequentes

Posso enviar vários tipos numa só chamada? Cada chamada de /send envia uma mensagem de um tipo. Para volume, use o endpoint de batch ou de campanhas.

Por que minha mídia não envia? Quase sempre a mediaUrl não é pública (exige login) ou falta o fileName no documento. Teste a URL no anônimo.

Como respondo/cito uma mensagem? Inclua quotedMessageId com o ID da mensagem citada no corpo de qualquer tipo.

Enquete funciona em grupo? Sim — basta usar o JID do grupo ([email protected]) no campo phone.

Existe limite de envio? Há limite por minuto conforme o plano (trial menor, plano pago maior). Não há limite mensal.