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.
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 é
402comcode: subscription_inactive(essa verificação vem antes da do plano). - Conexão aberta. Enquanto a conexão não está
open, a resposta é400comConnection 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 ojidde um evento de webhook, que pode ser um…@lid. Se o telefone não está no WhatsApp, a resposta é400comcode: not_on_whatsapp. - Resposta
200com{ "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 seuclientRefpara você saber de qual envio se trata.message.outgoing, quando o projeto ativouemitOutgoing:data.messageId, comorigin: "API"e oclientRef.
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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to | string | sim | A conversa para onde a mensagem foi enviada. |
text | string | sim | O 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."}'const res = await fetch(
`https://api.apiwpp.com/connections/${connectionId}/messages/${messageId}/edit`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to: '5511988887777', text: 'Seu horário foi confirmado para as 15h.' }),
},
)
const body = await res.json()
if (res.status === 409 && body.code === 'edit_window_closed') {
// Passou dos 15 minutos: envie uma mensagem nova com a correção
} else if (!res.ok) {
throw new Error(`${res.status}: ${body.error}`)
}{ "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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to | string | sim | A 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"}'const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/messages/${messageId}`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to: '5511988887777' }),
})
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`)Marcar mensagens como lidas
POST /connections/{id}/read envia as confirmações de leitura (os tiques azuis) de mensagens recebidas em uma conversa.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to | string | sim | A conversa: o data.jid dos eventos message.incoming (pode ser um …@lid). Em um grupo, o JID do grupo. |
messageIds | string[] | sim | Os ids das mensagens recebidas (data.raw.key.id), de 1 a 100 por chamada. Ids repetidos são enviados uma vez só. |
participant | string | não | Só 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"]}'// No seu receptor de webhooks, depois de processar um message.incoming
async function markRead(event) {
const res = await fetch(`https://api.apiwpp.com/connections/${event.connectionId}/read`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: event.data.jid,
messageIds: [event.data.raw.key.id],
// Em grupo, quem enviou a mensagem
...(event.data.raw.key.participant && { participant: event.data.raw.key.participant }),
}),
})
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`)
}Mostrar presença
POST /connections/{id}/presence mostra um estado na conversa.
state | O 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. |
paused | Encerra o composing ou o recording. |
available | O 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"}'async function presence(to, state) {
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/presence`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to, state }),
})
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`)
}
// O atendente começou a escrever...
await presence('5511988887777', 'composing')
// ...e desistiu sem enviar
await presence('5511988887777', 'paused')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:
| Status | code | Quando | O que fazer |
|---|---|---|---|
400 | FST_ERR_VALIDATION | O 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. |
400 | not_on_whatsapp | O telefone em to não está no WhatsApp. | Confira o número; não repita. |
402 | subscription_inactive | O teste acabou ou uma fatura venceu e passou da carência. | Regularize o pagamento no painel. |
403 | plan_feature_required | O 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. |
409 | edit_window_closed | Só 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. |
501 | unsupported_by_provider | A 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
- Enviar mensagens: texto, mídia, localização, templates e a fila.
- Idempotência: o
clientRefe como ele liga o envio aos eventos que trazem omessageId. - Reagir a uma mensagem: as reações estão em todos os planos.
- Referência: Mensagens: os parâmetros e as respostas de cada operação.