Visão Geral
Use estes endpoints para enviar mensagens diretamente a um contato usando seu identificador específico do canal. Toda requisição deve incluir seu token Bearer e o ID da API do seu workspace. URL BaseConceitos-Chave
O Campo number
O campo number carrega o identificador específico do canal do destinatário. O valor que você fornece depende do canal que você está direcionando:
Conversas de Webchat e Mercado Livre não podem ser endereçadas por número. Use o endpoint Enviar por Ticket para esses canais.
O Campo externalKey
O externalKey é opcional: é uma chave de idempotência única gerada pelo seu sistema. Quando enviado, ele tem dois propósitos:
- Correlação: vincula o envio de saída ao callback de webhook correspondente, para que você possa relacionar chamadas de API a eventos de entrega.
- Deduplicação: ajuda a evitar envios duplicados quando você repete a mesma requisição. Na rota Enviar por Ticket, a mesma chave repetida em até 120 segundos devolve
idempotent: trueeskipped: trueem vez de enviar de novo. Nas rotas de localização (/sendLocation) e de vCard (/sendVcard), porém, a chave não impede o envio repetido.
externalKey para envios diferentes.
O Campo validateNumber
Controla a normalização do 9º dígito para números de celular brasileiros.
Defina
validateNumber: false ao enviar para canais WABA para evitar a criação de contatos duplicados causada pela normalização automática de dígitos.Como a mensagem aparece para a equipe
No atendimento, as mensagens enviadas pela API aparecem com o autor Sistema (ícone de robô), e não com o nome do administrador que criou a API nem do responsável pelo atendimento. Ao passar o mouse sobre o ícone, a equipe vê a dica Mensagem enviada pela API (integração externa)., que diferencia esses envios das mensagens automáticas do sistema (chatbot, transferência) e das mensagens digitadas pelos atendentes.Nos canais oficiais (como WABA), arquivos e templates enviados pela API podem continuar aparecendo com o nome de um usuário da equipe.
Endpoints
Enviar uma Mensagem de Texto
Envie uma mensagem de texto simples a um contato.Request
O conteúdo de texto da mensagem. Se enviar um número, ele vira texto; objeto ou lista responde
400 ERR_INVALID_BODY.Identificador específico do canal do destinatário. Veja a tabela do campo
number acima.Chave de idempotência única gerada pelo seu sistema. Fortemente recomendada para evitar envios duplicados.
Defina como
true para fechar automaticamente o ticket imediatamente após o envio da mensagem.Controla a normalização do 9º dígito brasileiro. Defina como
false para canais WABA.Opcional. Força a mensagem a entrar em um ticket existente específico. Só é respeitado se o ticket pertencer ao mesmo contato e canal, e estiver atualmente aberto ou pendente.
Enviar um Arquivo via URL
Envie um arquivo hospedado em uma URL pública como anexo.Request
Legenda ou corpo de mensagem opcional para acompanhar o arquivo. Se enviar um número, ele vira texto; objeto ou lista responde
400 ERR_INVALID_BODY.Enviar um Arquivo via Upload Multipart
Envie um arquivo diretamente do seu sistema usandomultipart/form-data.
Enviar um Arquivo via Base64
Envie um arquivo codificado como uma string base64. Útil quando você tem o conteúdo do arquivo em memória e não deseja hospedá-lo externamente.Request
O conteúdo do arquivo codificado em base64, sem o prefixo
data:...;base64,. O corpo JSON da requisição, já com o base64, pode ter até 50 MB.Legenda opcional para acompanhar o arquivo. Se enviar um número, ele vira texto; objeto ou lista responde
400 ERR_INVALID_BODY.Enviar uma Mensagem de Áudio / Voz
Envie um arquivo de áudio que é renderizado como uma mensagem de voz nos canais compatíveis (por exemplo, WhatsApp).Request
Enviar via Parâmetros de Consulta na URL
Um endpoint de conveniência para integrações simples que não podem enviar um corpo JSON: passe todos os parâmetros como valores de query string.Enviar uma Localização
Envie uma localização (coordenadas, nome do local e endereço) para um contato.Request
ID do atendimento em que a mensagem fica registrada. É obrigatório (veja o aviso acima) e não muda o destinatário.
Enviar um Cartão de Contato (vCard)
Compartilhe um ou mais cartões de contato como uma mensagem vCard. Os destinatários no WhatsApp podem salvar o contato diretamente pelo chat.Request
ID do atendimento em que a mensagem fica registrada. É obrigatório (veja o aviso acima) e não muda o destinatário.
ID de usuário do WhatsApp no formato JID, por exemplo
5511999990002@s.whatsapp.net.Consultar uma Mensagem por ID
Recupera os detalhes de uma mensagem específica usando o ID atribuído pelo provedor do canal (por exemplo, owamid retornado pela Meta para canais WABA).
ID da mensagem no canal: o
wamid devolvido pela Meta nos canais WABA (por exemplo, wamid.xxxxx) ou o id da mensagem no WhatsApp nos canais Baileys (por exemplo, 3EB0EB8AA91A57A2F44861). Também pode ser o data.messageId retornado por Enviar por Ticket.data o registro da mensagem: id interno, messageId, body, ack, status, read, fromMe, mediaType, mediaUrl, o ticket (com id, status e o contact), o user que enviou e as datas createdAt e updatedAt.
Resposta de Sucesso
A resposta de sucesso sempre trazsuccess: true e um bloco data, mas o conteúdo de data muda conforme a rota:
Guarde o
ticketId, quando vier, para usar em Enviar por Ticket nas mensagens seguintes, sem precisar do número de novo. As rotas por número não devolvem o id da mensagem no canal: para localizá-la depois, use /searchMessages ou /showAllMessages, descritas em Tickets.
No
/showAllMessages, a lista traz também mensagens de sistema que nunca foram enviadas ao contato: notas internas (mediaType notes ou callNotes) e divisórias de transferência do atendimento (mediaType transfer). Ao procurar o envio feito pela API ou ao ler as respostas do contato, desconsidere esses itens. Veja Obter todas as mensagens de um ticket.{"success": false, "error": "ERR_..."}.

