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

# Enviando Mensagens

> Envie texto, mídia, localizações, enquetes, contatos, reações e mais através da API Wappfy.

# Enviando Mensagens

Todas as mensagens são enviadas através de um único endpoint. O campo `type` determina que tipo de mensagem será enviada, e os demais campos variam de acordo.

**Endpoint:**

```
POST https://api.wappfy.io/api/instances/{instanceId}/messages/send
```

**Headers:**

| Header         | Valor              |
| -------------- | ------------------ |
| `X-Api-Key`    | Sua chave de API   |
| `Content-Type` | `application/json` |

***

## Mensagem de Texto

Envie uma mensagem de texto simples.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "text",
      "text": "Olá da Wappfy!"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "text",
        text: "Olá da Wappfy!",
      }),
    }
  );

  const result = await response.json();
  console.log(result.data.message_id);
  ```
</CodeGroup>

**Resposta:**

```json theme={null}
{
  "data": {
    "message_id": "BAE5F2C4D3B2A1",
    "status": "sent"
  }
}
```

***

## Mensagem de Imagem

Envie uma imagem com legenda opcional.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "image",
      "media_url": "https://example.com/foto.jpg",
      "caption": "Veja esta foto!"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "image",
        media_url: "https://example.com/foto.jpg",
        caption: "Veja esta foto!",
      }),
    }
  );
  ```
</CodeGroup>

***

## Mensagem de Vídeo

Envie um arquivo de vídeo com legenda opcional.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "video",
      "media_url": "https://example.com/video.mp4",
      "caption": "Assista isso!"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "video",
        media_url: "https://example.com/video.mp4",
        caption: "Assista isso!",
      }),
    }
  );
  ```
</CodeGroup>

***

## Mensagem de Áudio

Envie um arquivo de áudio. Mensagens de áudio aparecem como mensagens de voz no WhatsApp.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "audio",
      "media_url": "https://example.com/mensagem-voz.ogg"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "audio",
        media_url: "https://example.com/mensagem-voz.ogg",
      }),
    }
  );
  ```
</CodeGroup>

<Note>
  Para melhor compatibilidade, use arquivos `.ogg` codificados com o codec Opus para mensagens de voz.
</Note>

***

## Mensagem de Documento

Envie um arquivo como anexo de documento.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "document",
      "media_url": "https://example.com/relatorio.pdf",
      "filename": "Relatorio-T1.pdf",
      "caption": "Aqui está o relatório trimestral"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "document",
        media_url: "https://example.com/relatorio.pdf",
        filename: "Relatorio-T1.pdf",
        caption: "Aqui está o relatório trimestral",
      }),
    }
  );
  ```
</CodeGroup>

***

## Mensagem de Localização

Envie um pino de localização geográfica.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "location",
      "latitude": -23.5505,
      "longitude": -46.6333,
      "name": "São Paulo",
      "address": "São Paulo, SP, Brasil"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "location",
        latitude: -23.5505,
        longitude: -46.6333,
        name: "São Paulo",
        address: "São Paulo, SP, Brasil",
      }),
    }
  );
  ```
</CodeGroup>

***

## Mensagem de Enquete

Crie uma enquete interativa. Os destinatários podem votar nas opções diretamente no WhatsApp.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "poll",
      "poll_name": "Qual dia é melhor para a reunião?",
      "poll_options": ["Segunda", "Quarta", "Sexta"],
      "poll_allow_multiple": false
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "poll",
        poll_name: "Qual dia é melhor para a reunião?",
        poll_options: ["Segunda", "Quarta", "Sexta"],
        poll_allow_multiple: false,
      }),
    }
  );
  ```
</CodeGroup>

***

## Mensagem de Contato / vCard

Compartilhe um cartão de contato.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "contact",
      "contact_name": "Maria Silva",
      "contact_phone": "+5511988887777"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "contact",
        contact_name: "Maria Silva",
        contact_phone: "+5511988887777",
      }),
    }
  );
  ```
</CodeGroup>

***

## Encaminhar Mensagem

Encaminhe uma mensagem existente para outro chat.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511888887777@s.whatsapp.net",
      "type": "forward",
      "forward_message_id": "BAE5F2C4D3B2A1",
      "forward_chat_id": "5511999998888@s.whatsapp.net"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511888887777@s.whatsapp.net",
        type: "forward",
        forward_message_id: "BAE5F2C4D3B2A1",
        forward_chat_id: "5511999998888@s.whatsapp.net",
      }),
    }
  );
  ```
</CodeGroup>

***

## Reação

Reaja a uma mensagem com um emoji.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "reaction",
      "reaction_message_id": "BAE5F2C4D3B2A1",
      "reaction": "\ud83d\udc4d"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "reaction",
        reaction_message_id: "BAE5F2C4D3B2A1",
        reaction: "\ud83d\udc4d",
      }),
    }
  );
  ```
</CodeGroup>

<Tip>
  Para remover uma reação, envie uma string vazia como valor do campo `reaction`.
</Tip>

***

## Recursos Avançados

### Responder a uma Mensagem

Cite uma mensagem anterior incluindo o `quoted_message_id`. Funciona com qualquer tipo de mensagem.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "text",
      "text": "Sim, concordo com isso!",
      "quoted_message_id": "BAE5F2C4D3B2A1"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "text",
        text: "Sim, concordo com isso!",
        quoted_message_id: "BAE5F2C4D3B2A1",
      }),
    }
  );
  ```
</CodeGroup>

### Editar uma Mensagem Enviada

Edite uma mensagem que você enviou anteriormente fornecendo o `edit_message_id`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "5511999998888@s.whatsapp.net",
      "type": "text",
      "text": "Conteúdo da mensagem atualizado",
      "edit_message_id": "BAE5F2C4D3B2A1"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "5511999998888@s.whatsapp.net",
        type: "text",
        text: "Conteúdo da mensagem atualizado",
        edit_message_id: "BAE5F2C4D3B2A1",
      }),
    }
  );
  ```
</CodeGroup>

<Warning>
  Você só pode editar mensagens que você enviou. A edição tem uma janela de tempo imposta pelo WhatsApp (aproximadamente 15 minutos após o envio).
</Warning>

### Menções

Mencione contatos específicos em uma mensagem de grupo. Os contatos mencionados receberão uma notificação.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/messages/send \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "chat_id": "120363012345678901@g.us",
      "type": "text",
      "text": "Ei @Maria e @Carlos, por favor revisem isso.",
      "mentions": [
        "5511999998888@s.whatsapp.net",
        "5511888887777@s.whatsapp.net"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/messages/send",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "SUA_CHAVE_API",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        chat_id: "120363012345678901@g.us",
        type: "text",
        text: "Ei @Maria e @Carlos, por favor revisem isso.",
        mentions: [
          "5511999998888@s.whatsapp.net",
          "5511888887777@s.whatsapp.net",
        ],
      }),
    }
  );
  ```
</CodeGroup>

***

## Formatos de Chat ID

| Formato                     | Descrição       | Exemplo                        |
| --------------------------- | --------------- | ------------------------------ |
| `{telefone}@s.whatsapp.net` | Chat individual | `5511999998888@s.whatsapp.net` |
| `{id}@g.us`                 | Chat de grupo   | `120363012345678901@g.us`      |

***

## Números de Telefone Brasileiros

<Note>
  A Wappfy trata automaticamente a questão do 9o dígito brasileiro. Se uma mensagem falhar com o erro "no LID found", o sistema automaticamente tenta novamente com o formato alternativo (adicionando ou removendo o 9o dígito).

  Por exemplo, se `5511999998888` falhar, será tentado `551199998888`, e vice-versa. Isso acontece de forma transparente -- você não precisa tratar isso manualmente.
</Note>

***

## Referência de Tipos de Mensagem

| Tipo       | Campos Obrigatórios                     | Campos Opcionais                                   |
| ---------- | --------------------------------------- | -------------------------------------------------- |
| `text`     | `text`                                  | `quoted_message_id`, `edit_message_id`, `mentions` |
| `image`    | `media_url`                             | `caption`, `quoted_message_id`                     |
| `video`    | `media_url`                             | `caption`, `quoted_message_id`                     |
| `audio`    | `media_url`                             | `quoted_message_id`                                |
| `document` | `media_url`                             | `filename`, `caption`, `quoted_message_id`         |
| `location` | `latitude`, `longitude`                 | `name`, `address`, `quoted_message_id`             |
| `poll`     | `poll_name`, `poll_options`             | `poll_allow_multiple`                              |
| `contact`  | `contact_name`, `contact_phone`         | `quoted_message_id`                                |
| `forward`  | `forward_message_id`, `forward_chat_id` | --                                                 |
| `reaction` | `reaction_message_id`, `reaction`       | --                                                 |

***

## Tratamento de Erros

| Código de Status | Descrição                                                                              |
| ---------------- | -------------------------------------------------------------------------------------- |
| `400`            | Payload de mensagem inválido (ex: campos obrigatórios ausentes para o tipo informado). |
| `404`            | Instância não encontrada ou não conectada.                                             |
| `422`            | Validação da mensagem falhou (ex: formato de número de telefone inválido).             |
| `429`            | Limite de requisições excedido. Veja [Limites de Requisição](/rate-limits).            |
| `502`            | O provedor WhatsApp retornou um erro. Verifique a mensagem de erro para detalhes.      |