# Editar mensagem

Fonte: https://apiwpp.com/docs/api/mensagens/editar-mensagem
Seção: Mensagens
Atualizado em: 2026-09-28

`POST /connections/{id}/messages/{messageId}/edit`

Substitui o texto de uma mensagem que este número enviou pela API, em até 15 minutos depois do envio, como o WhatsApp permite; os destinatários a veem marcada como editada. O `messageId` chega nos eventos `message.outgoing` (com `origin: "API"`) e `message.delivery` do envio: a resposta do `/send` traz só o `jobId`. Escopo necessário: `messages:send`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |
| `Content-Type` | sim | `application/json` |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador da conexão (o número) que enviou a mensagem. |
| `messageId` | `string` | sim | O id do WhatsApp da mensagem, como veio em `message.outgoing` ou `message.delivery`. (mínimo de 1 caractere) |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `to` | `string` | sim | A conversa: um número de telefone com código do país e DDD, só dígitos (a API usa o endereço 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`. (mínimo de 1 caractere) |
| `text` | `string` | sim | O novo texto da mensagem. (de 1 a 4096 caracteres) |

## Exemplo de requisição

### cURL

```bash
curl -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 ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '5511988887777',
    text: 'Seu horário foi confirmado para as 15h.',
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/connections/{$connectionId}/messages/{$messageId}/edit", [
        'to' => '5511988887777',
        'text' => 'Seu horário foi confirmado para as 15h.',
    ]);
```

### Python

```python
import requests

response = requests.post(
    f"https://api.apiwpp.com/connections/{connection_id}/messages/{message_id}/edit",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "to": "5511988887777",
        "text": "Seu horário foi confirmado para as 15h.",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | A edição foi enviada: `{"success": true}`. |
| 400 | `FST_ERR_VALIDATION` | O corpo não segue o schema da operação (um campo obrigatório ausente, ou um valor fora dos limites); `message` diz o que está errado. |
| 400 |  | A conexão não está `open`: o corpo traz `Connection not ready (status: …)`. Espere o evento `connection.status` com `open` e repita. |
| 400 | `not_on_whatsapp` | O número de `to` não está no WhatsApp: o corpo traz `code: not_on_whatsapp`. |
| 401 |  | Sem chave de API, ou com uma chave inválida (desconhecida, revogada ou expirada). |
| 402 | `subscription_inactive` | A organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Regularize o pagamento no painel e repita. |
| 403 |  | A chave de API não tem o escopo `messages:send`; a mensagem do erro cita o escopo que falta. |
| 403 | `plan_feature_required` | O plano da organização dona da conexão não inclui as operações de mensagem: o corpo traz `code: plan_feature_required` e `feature: message_ops`. Elas fazem parte do plano PRO (e do período de teste). |
| 404 |  | A conexão não existe ou não é de quem chama (o recurso de outra pessoa responde igual a um que não existe). Também quando esta conexão não enviou a mensagem pela API, ou a enviou há mais de 72 horas. |
| 409 | `edit_window_closed` | A mensagem foi enviada há mais de 15 minutos e o WhatsApp não aplica mais a edição; ela continua como estava. Para corrigir, envie uma mensagem nova. |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere Retry-After segundos. Cabeçalhos: `Retry-After`. |
| 500 |  | O WhatsApp recusou a operação ou não respondeu (`Failed to edit the message`). Pode repetir enquanto os 15 minutos desde o envio não passaram. |
| 501 | `unsupported_by_provider` | O provedor da conexão não oferece esta operação. |
| 503 |  | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere Retry-After segundos e tente de novo. Cabeçalhos: `Retry-After`. |

### 200 OK

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

## Detalhes

Só mensagens enviadas pela API: a API guarda por 72 horas o registro do que cada conexão enviou por ela. Uma mensagem enviada por outra conexão, digitada no celular ou enviada há mais de 72 horas responde `404`. Depois de 15 minutos, `409` com `code: edit_window_closed`: o WhatsApp descartaria a edição sem aviso.

Recurso do plano PRO: exige que a organização dona da conexão tenha o recurso `message_ops`; sem ele, a resposta é `403` com `code: plan_feature_required`. A verificação da organização em dia (`402 subscription_inactive`) vem antes da do plano.

Não passa pela fila: não é uma mensagem nova para ninguém, então o ritmo de envio, o aquecimento e o limite de destinatários novos não se aplicam. Se o WhatsApp recusar a operação, a resposta é `500`.

**Plano PRO:** exige um plano com o recurso `message_ops`; sem ele, a resposta é `403` com `code: plan_feature_required`.

Guia: [Operações de mensagem](https://apiwpp.com/docs/guias/operacoes-de-mensagem).
