# Operações de mensagem

Fonte: https://apiwpp.com/docs/guias/operacoes-de-mensagem
Seção: Guias
Atualizado em: 2026-09-29

Edite e apague para todos as mensagens enviadas pela API, marque as recebidas como lidas e mostre digitando ou gravando. Recursos do plano PRO.

Além de enviar, a API age sobre as conversas que já existem: edita o texto de uma mensagem que o número enviou, apaga uma mensagem para todos, confirma a leitura das mensagens recebidas (os tiques azuis) e mostra ao contato que alguém está digitando ou gravando um áudio.

> **Recurso do plano PRO**
>
> As quatro operações exigem que a organização dona da conexão tenha o plano **PRO** (o recurso `message_ops`). No plano LITE elas respondem `403` com `code: plan_feature_required` e `feature: message_ops`, antes de a API consultar a mensagem ou o WhatsApp. O período de teste inclui os recursos do PRO.

## O que as quatro têm em comum

- **Escopo** `messages:send`, o mesmo do envio.
- **Organização em dia.** Se o período de teste acabou ou uma fatura venceu e passou da carência, a resposta é `402` com `code: subscription_inactive` (essa verificação vem antes da do plano).
- **Conexão aberta.** Enquanto a conexão não está `open`, a resposta é `400` com `Connection not ready (status: …)`.
- **O campo `to`** é a conversa: um telefone com DDI, só dígitos (a API usa o JID que o WhatsApp registrou para ele, como no envio), ou um JID usado como está: o de um grupo (`…@g.us`) ou o `jid` de um evento de webhook, que pode ser um `…@lid`. Se o telefone não está no WhatsApp, a resposta é `400` com `code: not_on_whatsapp`.
- **Resposta** `200` com `{ "success": true }`.
- **Fora da fila.** Nenhuma delas é uma mensagem nova para alguém, então não passam pela fila do número: o ritmo de envio, o aquecimento e o limite de destinatários novos (veja [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio)) não se aplicam.
- **Sem evento de volta.** O WhatsApp informa uma edição ou uma exclusão como uma mensagem de protocolo, que a API ignora: nenhum webhook novo é enviado.

## Encontre o messageId

Editar e apagar pedem o `messageId` do WhatsApp de uma mensagem que **esta conexão enviou pela API**. A resposta `202` do `/send` traz o `jobId` da fila, não o `messageId`: ele chega nos eventos do envio.

- [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery): `data.messageId`, com o seu `clientRef` para você saber de qual envio se trata.
- [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing), quando o projeto ativou `emitOutgoing`: `data.messageId`, com `origin: "API"` e o `clientRef`.

Para marcar como lidas, você precisa do id das mensagens **recebidas**. O evento [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming) não tem um campo `messageId`: o id está em `data.raw.key.id`, e a conversa em `data.jid`. Em um grupo, o remetente está em `data.raw.key.participant`. O `raw` segue o formato do WhatsApp, não o contrato da API: leia dele só o que os outros campos não trazem.

> **Só envios da API, das últimas 72 horas**
>
> A API guarda por 72 horas o registro das mensagens que cada conexão enviou por ela, e é esse registro que prova que a mensagem é sua. Uma mensagem enviada por outra conexão, digitada no celular ou enviada há mais de 72 horas responde `404` (`Message not found: this connection did not send it through the API, or not in the last 72 hours`).

## Editar uma mensagem

`POST /connections/{id}/messages/{messageId}/edit` substitui o texto de uma mensagem enviada pela API. Os destinatários a veem marcada como editada.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `to` | string | sim | A conversa para onde a mensagem foi enviada. |
| `text` | string | sim | O novo texto, de 1 a 4096 caracteres. |

O WhatsApp só aplica uma edição feita até **15 minutos** depois do envio e descarta as posteriores sem aviso. Por isso a API recusa antes: passado esse prazo, a resposta é `409` com `code: edit_window_closed`, e a mensagem continua como estava.

**cURL**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/messages/$MESSAGE_ID/edit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "text": "Seu horário foi confirmado para as 15h."}'
```

**Node.js**

```javascript
const res = await fetch(
  `https://api.apiwpp.com/connections/${connectionId}/messages/${messageId}/edit`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ to: '5511988887777', text: 'Seu horário foi confirmado para as 15h.' }),
  },
)
const body = await res.json()

if (res.status === 409 && body.code === 'edit_window_closed') {
  // Passou dos 15 minutos: envie uma mensagem nova com a correção
} else if (!res.ok) {
  throw new Error(`${res.status}: ${body.error}`)
}
```

Resposta `200`

```json
{ "success": true }
```

## Apagar uma mensagem para todos

`DELETE /connections/{id}/messages/{messageId}` apaga para todos uma mensagem enviada pela API: os destinatários passam a ver "mensagem apagada". A API não confere o horário do envio, mas o próprio WhatsApp só atende o pedido até cerca de dois dias depois dele.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `to` | string | sim | A conversa para onde a mensagem foi enviada. |

O `DELETE` leva um corpo JSON. Um cliente HTTP que não envia corpo em `DELETE` recebe `400`: confira se o seu envia (com `fetch` e cURL, basta passar o corpo, como abaixo).

**cURL**

```bash
curl -s -X DELETE https://api.apiwpp.com/connections/$CONNECTION_ID/messages/$MESSAGE_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777"}'
```

**Node.js**

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/messages/${messageId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: '5511988887777' }),
})
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`)
```

## Marcar mensagens como lidas

`POST /connections/{id}/read` envia as confirmações de leitura (os tiques azuis) de mensagens recebidas em uma conversa.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `to` | string | sim | A conversa: o `data.jid` dos eventos `message.incoming` (pode ser um `…@lid`). Em um grupo, o JID do grupo. |
| `messageIds` | string[] | sim | Os ids das mensagens recebidas (`data.raw.key.id`), de 1 a 100 por chamada. Ids repetidos são enviados uma vez só. |
| `participant` | string | não | Só em grupo: o JID de quem enviou as mensagens (`data.raw.key.participant`). |

Como `participant` é um só por chamada, marque as mensagens de um grupo em uma chamada por remetente.

**cURL**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/read \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777@s.whatsapp.net", "messageIds": ["3EB0C8A1F2D4B6E8A0C2"]}'
```

**Node.js**

```javascript
// No seu receptor de webhooks, depois de processar um message.incoming
async function markRead(event) {
  const res = await fetch(`https://api.apiwpp.com/connections/${event.connectionId}/read`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: event.data.jid,
      messageIds: [event.data.raw.key.id],
      // Em grupo, quem enviou a mensagem
      ...(event.data.raw.key.participant && { participant: event.data.raw.key.participant }),
    }),
  })
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`)
}
```

## Mostrar presença

`POST /connections/{id}/presence` mostra um estado na conversa.

| `state` | O que o contato vê |
| --- | --- |
| `composing` | "digitando…", até um `paused` ou até uma mensagem ser enviada. |
| `recording` | "gravando áudio…", até um `paused` ou até uma mensagem ser enviada. |
| `paused` | Encerra o `composing` ou o `recording`. |
| `available` | O número online para todos os contatos, não só para a conversa. |

Os dois campos, `to` e `state`, são obrigatórios. Com `available`, o `to` não é usado, mas ainda precisa vir preenchido.

Todo envio pela API já mostra "digitando…" antes de a mensagem sair (o `typingDelay` de [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens)). A presença serve para uma pausa que você controla, como um atendente escrevendo uma resposta no seu sistema.

**cURL**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/presence \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "state": "composing"}'
```

**Node.js**

```javascript
async function presence(to, state) {
  const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/presence`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ to, state }),
  })
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`)
}

// O atendente começou a escrever...
await presence('5511988887777', 'composing')
// ...e desistiu sem enviar
await presence('5511988887777', 'paused')
```

## Erros

Além dos erros de qualquer chamada (`401` sem chave válida, `403` sem o escopo, `429` do limite por IP; veja [Erros](https://apiwpp.com/docs/guias/erros)), estas são as respostas das quatro operações:

| Status | `code` | Quando | O que fazer |
| --- | --- | --- | --- |
| `400` | `FST_ERR_VALIDATION` | O corpo não segue o schema: falta `to`, `text` vazio ou com mais de 4096 caracteres, `messageIds` vazio ou com mais de 100, `state` fora da lista. | Corrija a requisição. |
| `400` | — | A conexão não está `open`. | Espere o `connection.status` com `open`. |
| `400` | `not_on_whatsapp` | O telefone em `to` não está no WhatsApp. | Confira o número; não repita. |
| `402` | `subscription_inactive` | O teste acabou ou uma fatura venceu e passou da carência. | Regularize o pagamento no painel. |
| `403` | `plan_feature_required` | O plano da organização não inclui `message_ops`. | Mude para o PRO. |
| `404` | — | A conexão não existe ou é de outra pessoa; ou, em editar e apagar, a mensagem não foi enviada por esta conexão pela API nas últimas 72 horas. | Confira os ids. |
| `409` | `edit_window_closed` | Só em editar: passaram-se mais de 15 minutos desde o envio. | Envie uma mensagem nova. |
| `500` | — | O WhatsApp recusou a operação. | Tente de novo mais tarde. |
| `501` | `unsupported_by_provider` | A conexão usa um provedor que não oferece a operação (vem no campo `error`). | Não repita nesta conexão. |
| `503` | — | A conexão está mudando de instância, com o cabeçalho `Retry-After` (5 segundos). | Repita depois do `Retry-After`. |

Os códigos estão todos em [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro).

## Próximos passos

- [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens): texto, mídia, localização, templates e a fila.
- [Idempotência](https://apiwpp.com/docs/guias/idempotencia): o `clientRef` e como ele liga o envio aos eventos que trazem o `messageId`.
- [Reagir a uma mensagem](https://apiwpp.com/docs/api/mensagens/reagir): as reações estão em todos os planos.
- [Referência: Mensagens](https://apiwpp.com/docs/api/mensagens/editar-mensagem): os parâmetros e as respostas de cada operação.
