Como escolher a rota de envio?

Comece pelo conteúdo que sua aplicação já tem e pelo destino que precisa receber a mensagem. Para formatos simples, texto e mídia cobrem os usos mais comuns. Para dados estruturados, uma rota específica reduz a necessidade de representar tudo como texto corrido. As rotas de envio usam autenticação da instância pelo header token ou por Authorization: Bearer SEU_TOKEN.

Rota O que faz
POST /send/text Envia texto com number ou chatid e text.
POST /send/media Envia imagem, vídeo, áudio, sticker ou documento por type e URL/Base64.
POST /send/contact Compartilha um contato por telefone ou vCard, com nome opcional.
POST /send/location Envia coordenadas e, opcionalmente, nome e endereço.
POST /send/poll Cria uma enquete com nome e opções.
POST /send/menu, /send/button, /send/list Envia formatos de menu, botões ou lista usando o modelo de menu.
POST /send/event Envia evento com nome e início em Unix segundos.
POST /send/carousel Envia cartões em carrossel.
POST /send/rich, /send/table, /send/code-block Formata conteúdo estruturado, tabela ou bloco de código.
POST /send/album Envia uma coleção de imagens ou vídeos, com até 20 itens.
POST /send/request-payment Envia uma solicitação de pagamento com valor positivo.

O guia reúne dez grupos de uso. A rota básica contempla texto e mídia; as demais cobrem contatos, coordenadas, escolhas, eventos, cartões, conteúdo estruturado, álbuns e pedidos de pagamento. A existência da rota não define por si só como o destinatário verá o conteúdo em cada cliente WhatsApp.

Como enviar contato, localização ou enquete?

Contato aceita number ou chatid, um nome entre as alternativas documentadas e um telefone ou vCard. O destinatário é necessário; o exemplo usa telefone e nome:

curl -X POST 'https://SEU-DOMINIO/send/contact' \
  -H 'Content-Type: application/json' \
  -H 'token: SEU_TOKEN' \
  --data '{"number":"5511999999999","displayName":"Equipe de suporte","phone":"5511888888888"}'

Localização requer latitude e longitude em conjunto. Valores precisam estar nos intervalos geográficos válidos; nome e endereço são opcionais.

curl -X POST 'https://SEU-DOMINIO/send/location' \
  -H 'Content-Type: application/json' \
  -H 'token: SEU_TOKEN' \
  --data '{"number":"5511999999999","latitude":-23.5505,"longitude":-46.6333,"name":"Praça da Sé","address":"São Paulo, SP"}'

Enquete usa name e uma lista options com ao menos duas opções não vazias. selectableCount define quantas alternativas podem ser escolhidas; se for zero, o serviço usa uma opção, e o valor não pode exceder a quantidade enviada.

curl -X POST 'https://SEU-DOMINIO/send/poll' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  --data '{"number":"5511999999999","name":"Qual horário funciona?","options":["Manhã","Tarde","Noite"],"selectableCount":1}'

Nos três casos, o número pode ser substituído por chatid com o identificador da conversa. Os telefones dos exemplos são fictícios. Um teste de integração deve usar um destino autorizado pela sua operação.

Contato e localização são adequados quando a aplicação tem dados estruturados e quer preservar sua forma: um número e nome para contato, ou coordenadas e descrição para um ponto. Enquete é uma pergunta com alternativas e regras de seleção. Antes de enviar, valide os dados localmente, em especial o par de coordenadas e a relação entre alternativas e selectableCount, para receber erros de entrada no seu próprio fluxo.

Quando usar eventos, carrossel ou conteúdo formatado?

Use /send/event quando a mensagem representar um evento: os campos requeridos incluem name e startTime, que recebe Unix em segundos. Descrição, fim, localização, link e opções de convite são complementos opcionais. Para um evento criado, há também /send/event-response, com o identificador da mensagem do evento e a resposta going, not_going ou maybe.

O carrossel usa /send/carousel, com destino, textos e uma coleção de cards ou carousel. Os cartões comportam cabeçalho, texto, imagem, vídeo e botões. A estrutura interna completa dos cartões deve seguir o formato de integração usado pela aplicação.

Para conteúdo legível e organizado, /send/rich recebe items[] tipados; entre os tipos descritos estão texto, código, tabela e LaTeX. Se a aplicação já tem linhas e cabeçalhos, /send/table recebe title, headers, rows e textos opcionais. Um bloco de código pode ser enviado por /send/code-block com code e language requeridos.

curl -X POST 'https://SEU-DOMINIO/send/table' \
  -H 'Content-Type: application/json' \
  -H 'token: SEU_TOKEN' \
  --data '{"number":"5511999999999","title":"Plantão","headers":["Dia","Horário"],"rows":[["Segunda","9h às 17h"],["Terça","9h às 17h"]],"footer":"Horário local"}'

O corpo usa uma lista de listas de strings para linhas e uma lista de strings para cabeçalhos. O mesmo conteúdo pode ser montado pelo seu sistema e serializado como JSON; mantenha a estrutura da tabela alinhada entre cabeçalhos e valores.

Uma tabela funciona bem quando cada registro possui as mesmas colunas. Se os valores forem descritivos ou tiverem comprimentos diferentes, avalie se uma mensagem de texto é mais clara para quem recebe. Para código, o endpoint dedicado recebe linguagem e conteúdo, enquanto /send/rich agrupa itens de mais de um tipo no mesmo formato. Use o formato que corresponde aos dados que sua aplicação precisa compartilhar.

Como funcionam álbum, pagamento e fila?

POST /send/album recebe jid e items[]; cada item contém tipo, URL e legenda opcional. Há até 20 itens, e o tipo pode ser imagem ou vídeo. A rota de pagamento /send/request-payment aceita destino e amount positivo, além de textos e dados de pagamento opcionais. Existe também /send/payment-request, com um corpo de pedido distinto e campos obrigatórios próprios.

Esses dois usos têm contratos diferentes: o álbum agrupa mídias em itens, enquanto o pedido de pagamento transmite um valor e campos próprios da solicitação. Não reutilize automaticamente o corpo de uma rota em outra. Quando um recurso possui várias rotas parecidas, confira qual endpoint corresponde à operação e serialize apenas os campos associados àquele contrato. A resposta comum também pode diferir da resposta de álbum ou pagamento, por isso o cliente deve interpretar o corpo da rota chamada.

Para consultar exemplos adicionais de texto, documento e mídia, acesse como enviar mensagem pela API. O guia de grupos, comunidades, canais e status detalha rotas para outros destinos, enquanto webhooks e SSE aborda eventos da integração.

Os handlers comuns respondem com HTTP 200 e campos success e message; álbum, pagamento e comércio usam success e result. Isso descreve a resposta da API. Não trata a resposta como confirmação de entrega ou leitura no WhatsApp.

Quando não escolher a GoZAP

Não escolha a GoZAP se a operação precisa enviar apenas pela API oficial da Meta ou se os formatos e os campos publicados não atendem ao contrato que seu produto exige. Compare também o modelo hospedado com os requisitos de controle de infraestrutura da sua equipe. A GoZAP oferece conexão nativa Web e Mobile, e ambos os modos ficam fora da API oficial da Meta.