Apagar mensagemPRO
Apaga para todos uma mensagem que este número enviou pela API: os destinatários passam a ver “mensagem apagada”. A API não confere o horário do envio, mas o WhatsApp só atende o pedido até cerca de dois dias depois dele. Escopo necessário: messages:send.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador da conexão (o número) que enviou a mensagem.
messageIdstringobrigatórioO id do WhatsApp da mensagem, como veio em message.outgoing ou message.delivery.
Corpo da requisição
tostringobrigatórioA 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.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | O pedido de exclusão foi enviado: {"success": true}. |
| 400 | FST_ERR_VALIDATIONO 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_whatsappO 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_inactiveA 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_requiredO 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. |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere Retry-After segundos.Cabeçalho: Retry-After |
| 500 | O WhatsApp recusou a operação ou não respondeu (Failed to delete the message). Pode repetir. |
| 501 | unsupported_by_providerO 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çalho: Retry-After |
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.
O DELETE leva um corpo JSON com to: confira se o seu cliente HTTP envia corpo nesse método.
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