Editar e apagar mensagens enviadas pela API (PRO)
Corrija em até 15 minutos ou apague para todos uma mensagem de WhatsApp enviada pela API, usando o messageId. Recurso do plano PRO da apiwpp.
Atualizado em
Toda integração um dia envia uma mensagem errada: o valor do boleto saiu com o desconto de outro cliente, o lembrete marcou 14h quando a consulta era às 15h, o link de pagamento apontava para o pedido anterior. No celular, a pessoa corrigiria em dois toques. Pela API, até pouco tempo, a única saída era mandar uma segunda mensagem pedindo desculpas pela primeira.
No plano PRO, a apiwpp permite editar e apagar para todos as mensagens que o seu número enviou pela API. O destinatário vê o texto corrigido com a marca de "editada", ou o aviso de que a mensagem foi apagada, exatamente como acontece quando alguém faz isso no aplicativo.
O que dá para fazer
São duas operações, ambas pela API e ambas referenciando a mensagem pelo messageId, o identificador que o WhatsApp dá a cada mensagem:
| Operação | Rota | Limite |
|---|---|---|
| Editar o texto | POST /connections/{id}/messages/{messageId}/edit | Até 15 minutos depois do envio |
| Apagar para todos | DELETE /connections/{id}/messages/{messageId} | Mensagens enviadas pela API nas últimas 72 horas |
As duas valem só para mensagens que esse número enviou pela API. Uma mensagem digitada no celular, uma mensagem recebida ou uma mensagem de outra conexão responde 404. É uma proteção: a chave de API de um sistema não consegue alterar o que uma pessoa escreveu à mão no aparelho.
Editar troca o texto da mensagem. O novo texto vai no campo text, com até 4096 caracteres, e o campo to indica a conversa, com o número no mesmo formato do envio (só dígitos, com país e DDD).
Onde conseguir o messageId
O envio pela API não devolve o messageId na hora: POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. O identificador do WhatsApp só existe depois que a mensagem sai, e chega pelos webhooks:
message.deliverytraz omessageId, o novo status (sent,delivered,readoufailed) e o seuclientRef;message.outgoing, se você ativou esse evento no projeto, traz omessageIdcomorigin: "API"e o mesmoclientRef.
Por isso vale mandar sempre um clientRef no envio. Ele é a ponte entre o registro do seu sistema (o pedido, a cobrança, o agendamento) e a mensagem no WhatsApp. Quando o evento chega, guarde o messageId junto do registro; na hora de corrigir, você já sabe qual mensagem alterar. Veja como o clientRef funciona.
// Webhook: guarda o messageId de cada envio, ligado ao registro de origem
app.post('/webhooks/apiwpp', async (req, res) => {
res.sendStatus(204) // responda rápido; a assinatura HMAC é verificada antes, num middleware
const { type, connectionId, data } = req.body
if (type === 'message.delivery' && data.clientRef && data.messageId) {
await db.mensagens.upsert({
clientRef: data.clientRef,
connectionId,
messageId: data.messageId,
to: data.recipient,
})
}
})
Editar uma mensagem
Com o messageId em mãos, a correção é uma chamada:
curl -X POST "https://api.apiwpp.com/connections/$CONNECTION_ID/messages/3EB0C767D26A1D8A3F52/edit" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511988887777", "text": "Olá, Maria! Sua consulta está confirmada para amanhã às 15h."}'
A resposta é 200 com { "success": true }. Algumas respostas que o seu código deve tratar:
409comcode: "edit_window_closed": já passaram 15 minutos do envio e o WhatsApp não aplica mais a edição. Envie uma nova mensagem com a correção ou apague a original;404: a mensagem não foi enviada pela API por essa conexão, ou foi enviada há mais de 72 horas;400: a conexão não estáopenno momento, ou o destinatário não está no WhatsApp;403comcode: "plan_feature_required": a organização está no plano LITE (veja abaixo).
A chave de API precisa do escopo messages:send, o mesmo usado para enviar.
Apagar para todos
Apagar segue o mesmo formato, com o método DELETE e só o destinatário no corpo:
curl -X DELETE "https://api.apiwpp.com/connections/$CONNECTION_ID/messages/3EB0C767D26A1D8A3F52" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511988887777"}'
Na conversa, a mensagem é substituída pelo aviso de mensagem apagada. Use quando o conteúdo não deveria ter saído: o boleto de outro cliente, um link interno, um dado pessoal que foi para a pessoa errada. Nesses casos, apagar rápido importa mais do que corrigir.
Casos em que isso resolve
- Valor errado numa cobrança. O seu sistema recalcula o desconto e edita a mensagem em vez de mandar uma segunda com "desconsidere a anterior".
- Horário ou endereço de um agendamento. A clínica remarcou antes de o cliente ler; a mensagem editada mostra o horário certo, sem duas versões na conversa.
- Link quebrado ou do pedido errado. Troque o link pela versão correta ou apague a mensagem se ela expôs algo que não deveria.
- Mensagem enviada para o cliente errado. Apague para todos e registre o incidente no seu sistema.
A edição só vale para texto e dentro da janela de 15 minutos. Para correções depois disso, o caminho continua sendo uma nova mensagem, que entra na fila como qualquer envio.
Disponível no plano PRO
Editar e apagar fazem parte das operações de mensagem do plano PRO, junto com marcar como lida e mostrar presença. No plano LITE, essas rotas respondem 403 com code: "plan_feature_required" e feature: "message_ops", e o restante da integração continua funcionando normalmente.
O teste grátis de 7 dias já inclui os recursos do PRO, com 1 número e sem cartão, então dá para validar o fluxo de correção antes de decidir o plano. Os valores por número estão em preços.
Perguntas frequentes
Consigo editar uma mensagem que digitei no celular?
Não. Editar e apagar valem só para mensagens que o número enviou pela API. Uma mensagem digitada no aparelho, mesmo que apareça no evento message.outgoing com origin: "PHONE", responde 404 nessas rotas.
O que acontece se eu tentar editar depois de 15 minutos?
A API responde 409 com code: "editwindowclosed" e nada muda na conversa, porque o WhatsApp não aplica edições depois desse prazo. Nesse caso, envie uma nova mensagem com a correção ou apague a original.
Editar ou apagar conta nos limites de envio da fila?
Não. Essas operações alteram uma mensagem que já está na conversa e respondem na hora, sem entrar na fila. Só um novo envio pelo /send passa pelos limites de ritmo do número.
Como saber qual messageId corresponde ao meu pedido?
Mande um clientRef com o identificador do pedido em cada envio. O evento message.delivery devolve o clientRef junto com o messageId; guarde os dois no seu banco e use o messageId quando precisar corrigir.
Posso testar sem assinar o PRO?
Sim. O teste grátis de 7 dias inclui os recursos do PRO para 1 número, sem cartão de crédito. Depois do teste, editar e apagar ficam disponíveis apenas no plano PRO.
Outros recursos
Todos: Recursos →Reaja a mensagens com emoji e receba as reações dos clientes pelo evento message.reaction em qualquer plano. Todo texto enviado mostra "digitando…" antes. No PRO, marque mensagens como lidas e controle a presença do número.
O clientRef é o seu identificador de um envio. Repetir a requisição com o mesmo valor devolve o job original com duplicate: true, sem enfileirar outra mensagem, e o clientRef volta nos eventos de entrega e de falha.
Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.