Message Operations

Operações que modificam mensagens já existentes (envia ou recebida). Todas usam o whatsappMessageId (não o UUID local) e operam de forma assíncrona — retornam 202 Accepted e o Worker executa via Redis pub/sub.

Base path: /v1/messages/:wid onde :wid é o whatsappMessageId.

---

Pré-requisitos

Todos os endpoints abaixo validam:

1. Phone pertence à account → 404 PHONE_NOT_FOUND.
2. Phone está CONNECTED → 409 PHONE_NOT_CONNECTED.
3. Mensagem está no cache de keys (Redis TTL 7d; fallback DB para Baileys via tabela baileys_messages) → 404 MESSAGE_KEY_NOT_FOUND se não.

Importante (Baileys): o gateway só consegue operar em mensagens inbound (recebidas) ou outbound enviadas pelo próprio gateway. Mensagens enviadas por outros aparelhos no mesmo número (ex.: usuário usando o WhatsApp Web em paralelo) não estão no cache — operações sobre elas retornam MESSAGE_KEY_NOT_FOUND.

---

POST /v1/messages/:wid/react

Reage à mensagem com um emoji. Para remover reação, envie emoji: "".

Body

Campo	Tipo	Obrigatório	Limite
phoneId	UUID	sim	—
emoji	string	sim	0-20 chars (0 = remove)

curl -X POST https://wpp.ogmma.com.br/v1/messages/ABCD1234EFGH.../react \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneId": "5f7b2e1c-...", "emoji": "👍" }'

Response 202 — { "status": "enqueued" }

Errors

HTTP	Code	Quando
404	MESSAGE_KEY_NOT_FOUND	Mensagem fora do cache (TTL 7d expirado ou nunca vista pelo gateway)
409	PHONE_NOT_CONNECTED	—

---

POST /v1/messages/:wid/edit

Edita o texto de uma mensagem outbound enviada por você. Apenas mensagens type=text (limitação Meta + Baileys). Janela de edição: 15 minutos (limite WhatsApp).

Body

Campo	Tipo	Obrigatório	Limite
phoneId	UUID	sim	—
text	string	sim	1-4096

curl -X POST https://wpp.ogmma.com.br/v1/messages/ABCD1234EFGH.../edit \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneId": "5f7b2e1c-...", "text": "Texto corrigido!" }'

Response 202 — { "status": "enqueued" }

O destinatário verá o badge "Editada" no WhatsApp. Edits em mensagens > 15min são silenciosamente ignorados pelo WhatsApp (gateway não detecta — você não recebe erro síncrono).

---

DELETE /v1/messages/:wid

Deleta uma mensagem para todos ("Apagar para todos"). Para Baileys, funciona em outbound + inbound; para WABA, apenas outbound. Janela do WhatsApp: ~2 dias para "delete for everyone".

Query

Param	Tipo	Obrigatório
phoneId	UUID	sim

curl -X DELETE 'https://wpp.ogmma.com.br/v1/messages/ABCD1234EFGH...?phoneId=5f7b2e1c-...' \
  -H "X-API-Key: ak_live_..."

Response 202 — { "status": "enqueued" }

---

POST /v1/messages/:wid/read

Marca a mensagem inbound como lida (ack READ ao destinatário). Aciona os "dois ticks azuis" no WhatsApp do remetente.

Body

Campo	Tipo	Obrigatório
phoneId	UUID	sim

curl -X POST https://wpp.ogmma.com.br/v1/messages/ABCD1234EFGH.../read \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneId": "5f7b2e1c-..." }'

Response 202

---

POST /v1/messages/:wid/typing

Mostra "digitando..." para o destinatário daquela mensagem inbound. Dura ~25s ou até a próxima outbound. WABA-only (Meta exige typing + read no mesmo request; Baileys usa um caminho diferente).

Body

Campo	Tipo	Obrigatório
phoneId	UUID	sim

curl -X POST https://wpp.ogmma.com.br/v1/messages/ABCD1234EFGH.../typing \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneId": "5f7b2e1c-..." }'

Response 202

---

Padrão de resposta async

Como essas operações vão para o Worker via Redis, a resposta 202 significa enfileirada, não executada. Para confirmar:

• Algumas operações (react, edit, delete) emitem evento próprio no webhook do phone quando concluídas pelo Worker.
• Outras (read, typing) são fire-and-forget — sem confirmação explícita.

Se houver falha (ex.: token Meta expirado), você verá no evento error:occurred (futuro) ou em webhook:failed se o webhook do cliente também falhar. Em desenvolvimento, monitore os logs do Worker via npm run logs:railway.