Pular para o conteúdo

Operações de mensagem

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

Ver em Markdown

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.

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) 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: data.messageId, com o seu clientRef para você saber de qual envio se trata.
  • 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 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.

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.

CampoTipoObrigatórioDescrição
tostringsimA conversa para onde a mensagem foi enviada.
textstringsimO 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 -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."}'
200
{ "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.

CampoTipoObrigatórioDescrição
tostringsimA 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 -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"}'

Marcar mensagens como lidas

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

CampoTipoObrigatórioDescrição
tostringsimA conversa: o data.jid dos eventos message.incoming (pode ser um …@lid). Em um grupo, o JID do grupo.
messageIdsstring[]simOs ids das mensagens recebidas (data.raw.key.id), de 1 a 100 por chamada. Ids repetidos são enviados uma vez só.
participantstringnãoSó 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 -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/read \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "messageIds": ["3EB0C8A1F2D4B6E8A0C2"]}'

Mostrar presença

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

stateO 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.
pausedEncerra o composing ou o recording.
availableO 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). A presença serve para uma pausa que você controla, como um atendente escrevendo uma resposta no seu sistema.

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"}'

Erros

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

StatuscodeQuandoO que fazer
400FST_ERR_VALIDATIONO 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.
400not_on_whatsappO telefone em to não está no WhatsApp.Confira o número; não repita.
402subscription_inactiveO teste acabou ou uma fatura venceu e passou da carência.Regularize o pagamento no painel.
403plan_feature_requiredO 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.
409edit_window_closedSó 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.
501unsupported_by_providerA 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.

Próximos passos

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