> ## Documentation Index
> Fetch the complete documentation index at: https://ajuda.pandazap.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Envie texto, arquivos, áudio, mídia em base64 ou por URL para contatos do WhatsApp, Instagram, Telegram e e-mail usando a API externa do PanÐá Zap.

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

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**

```text theme={null}
https://{BaseUrl}/v2/api/external/{ApiID}/
```

**Autenticação**

```text theme={null}
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` |

<Note>
  Conversas de Webchat e Mercado Livre não podem ser endereçadas por número. Use o endpoint [Enviar por Ticket](/api/send-by-ticket) para esses canais.
</Note>

### 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                                                              |

<Note>
  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.
</Note>

***

## Endpoints

### Enviar uma Mensagem de Texto

<ParamField path="POST" type="string">
  `https://{BaseUrl}/v2/api/external/{ApiID}`
</ParamField>

Envie uma mensagem de texto simples a um contato.

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

<ParamField body="body" type="string" required>
  O conteúdo de texto da mensagem.
</ParamField>

<ParamField body="number" type="string" required>
  Identificador específico do canal do destinatário. Veja a tabela do campo `number` acima.
</ParamField>

<ParamField body="externalKey" type="string">
  Chave de idempotência única gerada pelo seu sistema. Fortemente recomendada para evitar envios duplicados.
</ParamField>

<ParamField body="isClosed" type="boolean" default="false">
  Defina como `true` para fechar automaticamente o ticket imediatamente após o envio da mensagem.
</ParamField>

<ParamField body="validateNumber" type="boolean" default="true">
  Controla a normalização do 9º dígito brasileiro. Defina como `false` para canais WABA.
</ParamField>

<ParamField body="ticketId" type="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.
</ParamField>

***

### Enviar um Arquivo via URL

<ParamField path="POST" type="string">
  `https://{BaseUrl}/v2/api/external/{ApiID}/url`
</ParamField>

Envie um arquivo hospedado em uma URL pública como anexo.

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

<ParamField body="mediaUrl" type="string" required>
  URL de acesso público do arquivo a ser enviado. Deve usar `http` ou `https`.
</ParamField>

<ParamField body="body" type="string">
  Legenda ou corpo de mensagem opcional para acompanhar o arquivo.
</ParamField>

<ParamField body="number" type="string" required>
  Identificador específico do canal do destinatário.
</ParamField>

<ParamField body="externalKey" type="string">
  Chave de idempotência única gerada pelo seu sistema.
</ParamField>

<ParamField body="isClosed" type="boolean" default="false">
  Fecha o ticket após o envio.
</ParamField>

<ParamField body="validateNumber" type="boolean" default="true">
  Controla a normalização do 9º dígito brasileiro.
</ParamField>

***

### Enviar um Arquivo via Upload Multipart

<ParamField path="POST" type="string">
  `https://{BaseUrl}/v2/api/external/{ApiID}`
</ParamField>

Envie um arquivo diretamente do seu sistema usando `multipart/form-data`.

```text theme={null}
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

<ParamField path="POST" type="string">
  `https://{BaseUrl}/v2/api/external/{ApiID}/base64`
</ParamField>

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.

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

<ParamField body="base64Data" type="string" required>
  O conteúdo do arquivo codificado como uma string base64. Tamanho máximo: **50 MB**.
</ParamField>

<ParamField body="mimeType" type="string" required>
  Tipo MIME do arquivo — por exemplo, `application/pdf`, `image/png`, `image/jpeg`.
</ParamField>

<ParamField body="fileName" type="string" required>
  Nome do arquivo sem extensão — por exemplo, `invoice`.
</ParamField>

<ParamField body="body" type="string">
  Legenda opcional para acompanhar o arquivo.
</ParamField>

<ParamField body="number" type="string" required>
  Identificador específico do canal do destinatário.
</ParamField>

<ParamField body="externalKey" type="string">
  Chave de idempotência única gerada pelo seu sistema.
</ParamField>

<ParamField body="validateNumber" type="boolean" default="true">
  Controla a normalização do 9º dígito brasileiro.
</ParamField>

***

### Enviar uma Mensagem de Áudio / Voz

<ParamField path="POST" type="string">
  `https://{BaseUrl}/v2/api/external/{ApiID}/voice`
</ParamField>

Envie um arquivo de áudio que é renderizado como uma mensagem de voz nos canais compatíveis (por exemplo, WhatsApp).

```json Request theme={null}
{
  "audio": "https://example.com/audio.ogg",
  "number": "5511999999999",
  "externalKey": "unique-key-004",
  "isClosed": false
}
```

<ParamField body="audio" type="string" required>
  URL de acesso público do arquivo de áudio a ser enviado.
</ParamField>

<ParamField body="number" type="string" required>
  Identificador específico do canal do destinatário.
</ParamField>

<ParamField body="externalKey" type="string">
  Chave de idempotência única gerada pelo seu sistema.
</ParamField>

<ParamField body="isClosed" type="boolean" default="false">
  Fecha o ticket após o envio.
</ParamField>

***

### Enviar via Parâmetros de Consulta na URL

<ParamField path="GET" type="string">
  `https://{BaseUrl}/v2/api/external/{ApiID}/params/`
</ParamField>

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.

```text theme={null}
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

<ParamField path="POST" type="string">
  `https://{BaseUrl}/v2/api/external/{ApiID}/sendLocation`
</ParamField>

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

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

<ParamField body="number" type="string" required>
  Identificador específico do canal do destinatário.
</ParamField>

<ParamField body="latitude" type="number" required>
  Latitude da localização em graus decimais.
</ParamField>

<ParamField body="longitude" type="number" required>
  Longitude da localização em graus decimais.
</ParamField>

<ParamField body="name" type="string">
  Nome de exibição do pin de localização — por exemplo, `"Our Office"`.
</ParamField>

<ParamField body="address" type="string">
  Endereço legível exibido abaixo do nome da localização.
</ParamField>

<ParamField body="externalKey" type="string">
  Chave de idempotência única gerada pelo seu sistema.
</ParamField>

***

### Enviar um Cartão de Contato (vCard)

<ParamField path="POST" type="string">
  `https://{BaseUrl}/v2/api/external/{ApiID}/sendVcard`
</ParamField>

Compartilhe um ou mais cartões de contato como uma mensagem vCard. Os destinatários no WhatsApp podem salvar o contato diretamente pelo chat.

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

<ParamField body="number" type="string" required>
  Identificador específico do canal do destinatário.
</ParamField>

<ParamField body="contact" type="array" required>
  Array de objetos de contato a incluir na mensagem vCard.
</ParamField>

<ParamField body="contact[].fullName" type="string" required>
  Nome completo de exibição do contato.
</ParamField>

<ParamField body="contact[].wuid" type="string">
  ID de usuário do WhatsApp no formato JID — por exemplo, `5511999990002@s.whatsapp.net`.
</ParamField>

<ParamField body="contact[].phoneNumber" type="string" required>
  Número de telefone do contato, com código do país e DDD.
</ParamField>

<ParamField body="externalKey" type="string">
  Chave de idempotência única gerada pelo seu sistema.
</ParamField>

***

## Resposta de Sucesso

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

```json theme={null}
{
  "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](/api/send-by-ticket) em mensagens de acompanhamento sem precisar do número de telefone novamente. |