Pular para o conteúdo

Marcar como lidasPRO

POST/connections/{id}/read

Envia as confirmações de leitura (os tiques azuis) de mensagens recebidas em uma conversa. Use os ids das mensagens dos eventos message.incoming e, como to, o jid desses eventos. Em um grupo, to é o grupo e participant o JID de quem enviou as mensagens. Até 100 mensagens por chamada. Escopo necessário: messages:send.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número) que recebeu as mensagens.

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
messageIdsstring[]obrigatório

Os ids do WhatsApp das mensagens recebidas nesta conversa.

de 1 a 100 itens
participantstring

Só em um grupo: o JID de quem enviou as mensagens.

mínimo de 1 caractere

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200As confirmações de leitura foram enviadas: {"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).
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 mark the messages read). Pode repetir: marcar de novo como lidas não muda nada.
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

O evento message.incoming não tem um campo messageId: o id da mensagem está em data.raw.key.id, e, em um grupo, o remetente em data.raw.key.participant. Ids repetidos em messageIds contam uma vez só.

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