Pular para o conteúdo

Apagar mensagemPRO

DELETE/connections/{id}/messages/{messageId}

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.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número) que enviou a mensagem.

messageIdstringobrigatório

O id do WhatsApp da mensagem, como veio em message.outgoing ou message.delivery.

mínimo de 1 caractere

Corpo da requisição

tostringobrigatório

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

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200O pedido de exclusão foi enviado: {"success": true}.
400FST_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.
400A conexão não está open: o corpo traz Connection not ready (status: …). Espere o evento connection.status com open e repita.
400not_on_whatsappO número de to não está no WhatsApp: o corpo traz code: not_on_whatsapp.
401Sem chave de API, ou com uma chave inválida (desconhecida, revogada ou expirada).
402subscription_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.
403A chave de API não tem o escopo messages:send; a mensagem do erro cita o escopo que falta.
403plan_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).
404A 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.
429Requisições demais deste IP de origem, ou autenticações com falha demais: espere Retry-After segundos.Cabeçalho: Retry-After
500O WhatsApp recusou a operação ou não respondeu (Failed to delete the message). Pode repetir.
501unsupported_by_providerO provedor da conexão não oferece esta operação.
503A 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

Esta página ajudou? · Atualizado em 28 set 2026