Pular para o conteúdo principal
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. A mensagem sai pelo canal vinculado à API que gerou o token. O PanÐá Zap oferece oito formas de envio (texto simples, arquivo via URL, upload multipart, base64, áudio/voz, parâmetros de consulta, localização e vCard), para que você escolha a que melhor se adapta à sua integração.

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 Base
Autenticação

Conceitos-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: true e skipped: true em 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.
Nunca reutilize o mesmo valor de 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

string
https://{BaseUrl}/v2/api/external/{ApiID}
Envie uma mensagem de texto simples a um contato.
Request
string
obrigatório
O conteúdo de texto da mensagem. Se enviar um número, ele vira texto; objeto ou lista responde 400 ERR_INVALID_BODY.
string
obrigatório
Identificador específico do canal do destinatário. Veja a tabela do campo number acima.
string
Chave de idempotência única gerada pelo seu sistema. Fortemente recomendada para evitar envios duplicados.
boolean
padrão:"false"
Defina como true para fechar automaticamente o ticket imediatamente após o envio da mensagem.
boolean
padrão:"true"
Controla a normalização do 9º dígito brasileiro. Defina como false para canais WABA.
integer
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

string
https://{BaseUrl}/v2/api/external/{ApiID}/url
Envie um arquivo hospedado em uma URL pública como anexo.
Request
string
obrigatório
URL de acesso público do arquivo a ser enviado. Deve usar http ou https.
string
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.
string
obrigatório
Identificador específico do canal do destinatário.
string
Chave de idempotência única gerada pelo seu sistema.
boolean
padrão:"false"
Fecha o ticket após o envio.
boolean
padrão:"true"
Controla a normalização do 9º dígito brasileiro.

Enviar um Arquivo via Upload Multipart

string
https://{BaseUrl}/v2/api/external/{ApiID}
Envie um arquivo diretamente do seu sistema usando multipart/form-data.

Enviar um Arquivo via Base64

string
https://{BaseUrl}/v2/api/external/{ApiID}/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
string
obrigatório
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.
string
obrigatório
Tipo MIME do arquivo, por exemplo application/pdf, image/png ou image/jpeg.
string
obrigatório
Nome exibido do arquivo, por exemplo fatura.
string
Legenda opcional para acompanhar o arquivo. Se enviar um número, ele vira texto; objeto ou lista responde 400 ERR_INVALID_BODY.
string
obrigatório
Identificador específico do canal do destinatário.
boolean
padrão:"false"
Fecha o ticket após o envio.
string
Chave de idempotência única gerada pelo seu sistema.
boolean
padrão:"true"
Controla a normalização do 9º dígito brasileiro.

Enviar uma Mensagem de Áudio / Voz

string
https://{BaseUrl}/v2/api/external/{ApiID}/voice
Envie um arquivo de áudio que é renderizado como uma mensagem de voz nos canais compatíveis (por exemplo, WhatsApp).
Request
string
obrigatório
URL de acesso público do arquivo de áudio a ser enviado (.ogg ou .mp3).
string
obrigatório
Identificador específico do canal do destinatário.
string
Chave de idempotência única gerada pelo seu sistema.
boolean
padrão:"false"
Fecha o ticket após o envio.

Enviar via Parâmetros de Consulta na URL

string
https://{BaseUrl}/v2/api/external/{ApiID}/params/
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.
Como o token vai na URL, ele fica gravado nos logs de acesso do servidor (e de proxies no caminho). Para enviar sem expor o token, prefira as rotas POST de envio, como Enviar uma Mensagem de Texto, com o token no cabeçalho Authorization.

Enviar uma Localização

string
https://{BaseUrl}/v2/api/external/{ApiID}/sendLocation
Envie uma localização (coordenadas, nome do local e endereço) para um contato.
Request
O ticketId é obrigatório: é o atendimento em que a mensagem fica registrada. Sem ele, a rota responde 400 com ERR_MISSING_TICKET; se o atendimento não for da sua empresa, responde 404 com ERR_TICKET_NOT_FOUND. Com o ticketId correto, a resposta de sucesso é {"success": true, "data": {"sent": true}}.
string
obrigatório
Identificador específico do canal do destinatário. É ele que define quem recebe.
integer
obrigatório
ID do atendimento em que a mensagem fica registrada. É obrigatório (veja o aviso acima) e não muda o destinatário.
number
obrigatório
Latitude da localização em graus decimais.
number
obrigatório
Longitude da localização em graus decimais.
string
Nome de exibição do local, por exemplo "Nosso escritório".
string
Endereço legível exibido abaixo do nome da localização.
string
Opcional. Chave do seu sistema; nesta rota ela não impede o envio repetido.

Enviar um Cartão de Contato (vCard)

string
https://{BaseUrl}/v2/api/external/{ApiID}/sendVcard
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
O ticketId é obrigatório: é o atendimento em que a mensagem fica registrada. Sem ele, a rota responde 400 com ERR_MISSING_TICKET; se o atendimento não for da sua empresa, responde 404 com ERR_TICKET_NOT_FOUND. Com o ticketId correto, a resposta de sucesso é {"success": true, "data": {"sent": true}}.
string
obrigatório
Identificador específico do canal do destinatário. É ele que define quem recebe.
integer
obrigatório
ID do atendimento em que a mensagem fica registrada. É obrigatório (veja o aviso acima) e não muda o destinatário.
array
obrigatório
Array de objetos de contato a incluir na mensagem vCard.
string
obrigatório
Nome completo de exibição do contato.
string
obrigatório
ID de usuário do WhatsApp no formato JID, por exemplo 5511999990002@s.whatsapp.net.
string
obrigatório
Número de telefone do contato, com código do país e DDD.
string
Opcional. Chave do seu sistema; nesta rota ela não impede o envio repetido.

Consultar uma Mensagem por ID

Recupera os detalhes de uma mensagem específica usando o ID atribuído pelo provedor do canal (por exemplo, o wamid retornado pela Meta para canais WABA).
string
https://{BaseUrl}/v2/api/external/{ApiID}/getMessageByMessageId
string
obrigatório
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.
A resposta traz em 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 traz success: 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.
Em caso de erro, a resposta vem como {"success": false, "error": "ERR_..."}.

Erros de envio