WhatsApp: moderação de mídia

Fila de revisão das fotos, vídeos, áudios e documentos que clientes enviam pelo WhatsApp: listar, decidir e decidir em lote.

Clientes enviam fotos, vídeos, áudios e documentos pelo WhatsApp. A plataforma coloca cada mídia recebida numa fila de moderação, para que alguém da loja confira o que chegou (uma foto de produto danificado, um comprovante, um áudio de reclamação) e registre a decisão. Esta seção documenta a fila.

Como funciona

Todo item começa pending. Um moderador decide e o item vai para um dos outros estados.

pending→approved, rejected, flagged ou escalated

Estado	Significado
`pending`	Recém-chegado, ninguém decidiu ainda.
`approved`	Conferido e aceito.
`rejected`	Não deve ser aceito (impróprio, sem relação com o pedido).
`flagged`	Sinalizado para outra equipe olhar (jurídico, antifraude).
`escalated`	Passou para um superior decidir.

Liste o que está pendente
GET /media-moderation?status=pending traz a fila. Cada item já vem com uma descrição automática (auto_classification) e a confiança dela.
Abra o item
GET /media-moderation/{id} mostra todos os campos, inclusive a conversa e a mensagem de origem.
Registre a decisão
POST /media-moderation/{id}/approve (ou reject, flag, escalate), com notes e tags se quiser deixar rastro.

Conceitos-chave

Classificação automática

Quando a loja tem IA de visão ou transcrição ligada, a plataforma descreve a mídia sozinha e guarda a descrição em auto_classification, com auto_classification_confidence de 0 a 1. É uma ajuda para priorizar, não uma decisão: o estado só muda por uma chamada de decisão.

Estado como palavra ou como letra

Na maioria das lojas o campo status volta como palavra (pending). Em outras o banco guarda uma letra (P, A, R, F, E). Nos filtros e nas decisões você sempre usa a palavra.

Seller e conversa

Cada item pode apontar para o seller (vendor_id) e para a conversa (thread_id) de onde veio. Essas rotas são do administrador da loja e enxergam todos os sellers; filtre por vendor_id para olhar um só.

Endpoints

Método	Caminho	Para que serve	Página
`GET`	`/api/v1/admin/whatsapp/media-moderation`	Lista a fila de moderação de mídias	Fila de mídias
`GET`	`/api/v1/admin/whatsapp/media-moderation/{id}`	Lê um item da fila de moderação	Fila de mídias
`POST`	`/api/v1/admin/whatsapp/media-moderation/{id}/approve`	Marca a mídia como aprovada	Decidir um item
`POST`	`/api/v1/admin/whatsapp/media-moderation/{id}/reject`	Marca a mídia como rejeitada	Decidir um item
`POST`	`/api/v1/admin/whatsapp/media-moderation/{id}/flag`	Marca a mídia como sinalizada	Decidir um item
`POST`	`/api/v1/admin/whatsapp/media-moderation/{id}/escalate`	Marca a mídia como escalada	Decidir um item
`POST`	`/api/v1/admin/whatsapp/media-moderation/bulk-approve`	Aprova vários itens de uma vez	Decisões em lote
`POST`	`/api/v1/admin/whatsapp/media-moderation/bulk-reject`	Rejeita vários itens de uma vez	Decisões em lote

Erros comuns

Passar um id que não é UUID: a plataforma responde 500 em vez de 400.
Achar que limit=500 devolve 500 itens: acima de 200 o limite volta para 50.
Mandar mais de 200 ids no lote: a chamada inteira é recusada com 400.
Ignorar failure_count no lote: com falhas parciais o status HTTP continua 200.
Esperar que rejeitar apague a mídia: a decisão só fica registrada no item.
Procurar uma rota para criar item: os itens nascem do recebimento da mídia.

Próximos passos

Fila de mídias

Listar e abrir itens.

Decidir um item

Aprovar, rejeitar, sinalizar, escalar.

Decisões em lote

Até 200 itens por chamada.