Reações, confirmação de leitura e "digitando"
Reaja a mensagens, receba reações no webhook, marque mensagens como lidas e mostre "digitando…" pela API do WhatsApp. Veja o que vale em cada plano.
Atualizado em
Uma conversa no WhatsApp não é feita só de mensagens. O cliente vê o "digitando…" antes da resposta, os tiques azuis quando a mensagem foi lida e uma reação com emoji quando basta um "ok". Quando um sistema responde sem nada disso, a conversa parece automática, e é exatamente essa impressão que você quer evitar num atendimento.
A apiwpp expõe esses sinais pela API: reações nos dois sentidos, o indicador de "digitando…" antes de cada texto e, no plano PRO, confirmação de leitura e controle de presença.
O que vale em cada plano
| Recurso | LITE | PRO |
|---|---|---|
Reagir a mensagens (POST /connections/{id}/react) | Sim | Sim |
Receber reações (evento message.reaction) | Sim | Sim |
"Digitando…" antes de cada texto (typingDelay) | Sim | Sim |
Marcar como lida (POST /connections/{id}/read) | Não | Sim |
Presença sob demanda (POST /connections/{id}/presence) | Não | Sim |
No LITE, as rotas de leitura e de presença respondem 403 plan_feature_required. O teste grátis de 7 dias inclui os recursos do PRO, então dá para experimentar tudo antes de escolher o plano. Os detalhes de cada plano estão em preços.
Reagir a mensagens e receber reações
Para reagir, informe o messageId da mensagem (o que chega em message.incoming ou em message.delivery), o número da conversa e o emoji:
curl -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/react \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{ "messageId": "3EB0C767D26A1D8A3F52", "to": "5511988887777", "emoji": "👍" }'
Um emoji vazio remove a reação. É um jeito leve de confirmar que um comprovante foi recebido ou que um pedido foi anotado, sem mandar mais uma mensagem.
Quando alguém reage a uma mensagem do número, o seu webhook recebe o evento message.reaction:
{
"type": "message.reaction",
"data": {
"messageId": "3EB0C767D26A1D8A3F52",
"from": "5511988887777",
"jid": "[email protected]",
"phone": "+5511988887777",
"emoji": "👍"
}
}
O envelope completo também traz connectionId, tenantId, externalId e timestamp. Um emoji vazio quer dizer que a pessoa removeu a reação. Com o messageId, o seu sistema sabe a qual mensagem ela reagiu: um 👍 num lembrete de consulta pode, por exemplo, ser tratado como confirmação.
"Digitando…" antes de cada envio
Todo texto enviado pela API mostra "digitando…" para o destinatário antes de chegar. O padrão é 1,5 segundo, e o campo typingDelay, em milissegundos, muda esse tempo por envio:
{ "to": "5511988887777", "message": "Seu pedido saiu para entrega.", "typingDelay": 3000 }
Uma resposta longa com um typingDelay um pouco maior fica mais natural. Isso vale nos dois planos e não exige nenhuma chamada extra.
Marcar como lida (PRO)
Quando o seu sistema processa uma mensagem recebida, você pode enviar a confirmação de leitura, os tiques azuis. Use os messageId dos eventos message.incoming e, em to, o jid desses eventos:
curl -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/read \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{ "to": "[email protected]", "messageIds": ["3EB0C767D26A1D8A3F52"] }'
São até 100 mensagens por chamada. Num grupo, to é o grupo e participant é o JID de quem enviou as mensagens. Um bom momento para marcar como lida é quando um atendente abre a conversa no seu sistema, e não no instante em que o webhook chega: assim o cliente vê que alguém realmente leu.
Presença: "digitando" e "gravando" sob demanda (PRO)
O "digitando…" do envio cobre respostas automáticas. Quando uma pessoa está escrevendo a resposta no seu sistema, a rota de presença deixa você controlar o indicador:
curl -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/presence \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{ "to": "5511988887777", "state": "composing" }'
composingmostra "digitando…" erecordingmostra "gravando áudio…", até você enviarpausedou a mensagem sair;availablemostra o número on-line para todos.
Leitura e presença não são mensagens novas para ninguém. Por isso não entram na fila do número e não contam para os limites de envio.
Quando usar para a conversa parecer humana
Esses sinais funcionam melhor quando refletem o que realmente acontece:
- Atendimento com pessoas: marque como lida quando o atendente abrir a conversa e envie
composingenquanto ele escreve. O cliente sabe que está sendo atendido. - Respostas automáticas: deixe o
typingDelayfazer o trabalho e ajuste o tempo ao tamanho do texto. Não é preciso chamar a rota de presença. - Confirmações rápidas: uma reação resolve o que seria um "recebido, obrigado" e evita mais uma mensagem na conversa.
- Evite exageros: um "digitando…" eterno ou mensagens marcadas como lidas sem resposta deixam a pessoa esperando. Use os sinais para informar, não para prender a atenção.
Para montar um atendimento completo, com tickets abertos a partir do webhook, veja o caso de uso de atendimento e suporte. Para corrigir uma mensagem já enviada, o PRO também permite editar e apagar mensagens.
Perguntas frequentes
O plano LITE mostra "digitando…"?
Sim. O indicador antes de cada texto, controlado pelo typingDelay, vale nos dois planos. O que é exclusivo do PRO é a rota de presença, que liga e desliga o indicador quando você quiser, e a confirmação de leitura.
Recebo um evento quando o cliente lê a minha mensagem?
Sim, em qualquer plano. O evento message.delivery informa cada mudança de status das mensagens enviadas, incluindo read. A rota de marcar como lida é o caminho inverso: é o seu número confirmando a leitura das mensagens que recebeu.
Reações contam como mensagens para os limites?
A reação é uma chamada própria, POST /connections/{id}/react, e não entra na fila de envio com o POST /send. Mesmo assim, reagir em massa a mensagens de desconhecidos não é um comportamento de pessoa; use reações nas conversas que já existem.
Consigo saber quando o cliente está digitando?
Não. A apiwpp não envia eventos de presença dos contatos para o webhook. Você recebe as mensagens, as reações e os status de entrega e leitura.
Outros recursos
Todos: Recursos →POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.
Errou o valor, o horário ou o link? Com o plano PRO, o seu sistema altera o texto de uma mensagem enviada pela API em até 15 minutos ou apaga a mensagem para todos, sempre pelo messageId.
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.