Envie Mensagens por Número de Telefone ou Identificador de Canal

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. O PanÐá Zap suporta oito variantes de envio — texto simples, arquivo via URL, upload multipart, base64, áudio/voz, parâmetros de consulta, localização e vCard — para que você possa escolher o formato que melhor se adapta à sua integração.

Visão Geral

https://{BaseUrl}/v2/api/external/{ApiID}/

Autenticação

Authorization: Bearer {BearerToken}

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:

Canal	Valor para `number`
WhatsApp (todos os tipos)	Número de telefone — por exemplo, `5511999999999`
Instagram	IGSID — de `showcontact` ou do webhook `contact.instagramPK`
Messenger	PSID — de `showcontact` ou do webhook `messengerId`
Telegram	`telegramId` numérico
E-mail (webmail)	Use o campo `email` + o campo opcional `subject` em vez de `number`

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 é uma chave de idempotência única gerada pelo seu sistema. 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: se o mesmo externalKey for enviado duas vezes, a segunda requisição é ignorada silenciosamente — a mensagem não é enviada novamente.

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.

Valor	Comportamento
`true` (padrão)	Corrige automaticamente números brasileiros — adiciona ou remove o 9º dígito com base na regra do DDD
`false`	Envia o número exatamente como fornecido

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.

Endpoints

Enviar uma Mensagem de Texto

string

https://{BaseUrl}/v2/api/external/{ApiID}

Envie uma mensagem de texto simples a um contato.

Request

{
  "body": "Hello! How can we help you?",
  "number": "5511999999999",
  "externalKey": "unique-key-001",
  "isClosed": false,
  "validateNumber": true
}

string

obrigatório

O conteúdo de texto da mensagem.

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

{
  "mediaUrl": "https://example.com/document.pdf",
  "body": "Here is your document.",
  "number": "5511999999999",
  "externalKey": "unique-key-002",
  "isClosed": false,
  "validateNumber": true
}

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.

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.

Content-Type: multipart/form-data

Campo do Formulário	Tipo	Descrição
`media`	arquivo	O arquivo a ser enviado.
`body`	string	Legenda opcional para acompanhar o arquivo.
`number`	string	Identificador específico do canal do destinatário.
`externalKey`	string	Chave de idempotência única.
`isClosed`	boolean	Fecha o ticket após o envio.
`validateNumber`	boolean	Alternância de normalização do 9º dígito brasileiro.

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

{
  "body": "Your document is attached.",
  "number": "5511999999999",
  "base64Data": "JVBERi0xLjQKJeLjz9MKNSAwIG9...",
  "mimeType": "application/pdf",
  "fileName": "invoice",
  "externalKey": "unique-key-003",
  "validateNumber": true
}

string

obrigatório

O conteúdo do arquivo codificado como uma string base64. Tamanho máximo: 50 MB.

string

obrigatório

Tipo MIME do arquivo — por exemplo, application/pdf, image/png, image/jpeg.

string

obrigatório

Nome do arquivo sem extensão — por exemplo, invoice.

string

Legenda opcional para acompanhar o arquivo.

string

obrigatório

Identificador específico do canal do destinatário.

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

{
  "audio": "https://example.com/audio.ogg",
  "number": "5511999999999",
  "externalKey": "unique-key-004",
  "isClosed": false
}

string

obrigatório

URL de acesso público do arquivo de áudio a ser enviado.

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.

GET https://{BaseUrl}/v2/api/external/{ApiID}/params/?body=Hello&number=5511999999999&externalKey=key-005&bearertoken={BearerToken}&isClosed=false

Parâmetro de Consulta	Descrição
`body`	Conteúdo de texto da mensagem.
`number`	Identificador específico do canal do destinatário.
`externalKey`	Chave de idempotência única.
`bearertoken`	Seu token Bearer (substitui o cabeçalho `Authorization` neste endpoint).
`isClosed`	`true` para fechar o ticket após o envio.

Enviar uma Localização

string

https://{BaseUrl}/v2/api/external/{ApiID}/sendLocation

Envie um pin de mapa com coordenadas, nome do local e endereço — é renderizado como um cartão de localização interativo no WhatsApp.

Request

{
  "number": "5511999999999",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "name": "Our Office",
  "address": "Av. Paulista, 1000, São Paulo",
  "externalKey": "unique-key-006"
}

string

obrigatório

Identificador específico do canal do 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 pin de localização — por exemplo, "Our Office".

string

Endereço legível exibido abaixo do nome da localização.

string

Chave de idempotência única gerada pelo seu sistema.

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

{
  "number": "5511999999999",
  "contact": [
    {
      "fullName": "Jane Smith",
      "wuid": "5511999990002@s.whatsapp.net",
      "phoneNumber": "5511999990002"
    }
  ],
  "externalKey": "unique-key-007"
}

string

obrigatório

Identificador específico do canal do 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

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

Chave de idempotência única gerada pelo seu sistema.

Resposta de Sucesso

Todos os endpoints de envio retornam o mesmo formato de resposta em caso de sucesso:

{
  "success": true,
  "data": {
    "message": "Message sent successfully",
    "ticketId": 123
  }
}

Campo	Tipo	Descrição
`success`	boolean	`true` quando a mensagem foi aceita para entrega.
`data.message`	string	Confirmação legível por humanos.
`data.ticketId`	integer	O ID da conversa na qual a mensagem foi enviada. Salve este valor para usar com o endpoint Enviar por Ticket em mensagens de acompanhamento sem precisar do número de telefone novamente.

Primeiros Passos

Mensagens

Tickets e Contatos

Campanhas e CRM

Webhooks e Eventos

Envie Mensagens por Número de Telefone ou Identificador de Canal

Visão Geral

Conceitos-Chave

O Campo `number`

O Campo `externalKey`

O Campo `validateNumber`

Endpoints

Enviar uma Mensagem de Texto

Enviar um Arquivo via URL

Enviar um Arquivo via Upload Multipart

Enviar um Arquivo via Base64

Enviar uma Mensagem de Áudio / Voz

Enviar via Parâmetros de Consulta na URL

Enviar uma Localização

Enviar um Cartão de Contato (vCard)

Resposta de Sucesso

​Visão Geral

​Conceitos-Chave

​O Campo number

​O Campo externalKey

​O Campo validateNumber

​Endpoints

​Enviar uma Mensagem de Texto

​Enviar um Arquivo via URL

​Enviar um Arquivo via Upload Multipart

​Enviar um Arquivo via Base64

​Enviar uma Mensagem de Áudio / Voz

​Enviar via Parâmetros de Consulta na URL

​Enviar uma Localização

​Enviar um Cartão de Contato (vCard)

​Resposta de Sucesso

Visão Geral

Conceitos-Chave

O Campo `number`

O Campo `externalKey`

O Campo `validateNumber`

Endpoints

Enviar uma Mensagem de Texto

Enviar um Arquivo via URL

Enviar um Arquivo via Upload Multipart

Enviar um Arquivo via Base64

Enviar uma Mensagem de Áudio / Voz

Enviar via Parâmetros de Consulta na URL

Enviar uma Localização

Enviar um Cartão de Contato (vCard)

Resposta de Sucesso