Mensagens
Central de mensagens entre clientes, sellers e a loja: conversas, respostas, leitura, vínculo com pedidos e assistente.
A central de mensagens é o chat interno da loja. Um cliente pode escrever para a loja ou para um seller (por exemplo, perguntando sobre um pedido ou um produto), e a conversa fica registrada como uma conversa (thread) com várias mensagens. Esta seção é a visão do administrador: ele enxerga todas as conversas, responde, marca como lida, arquiva e liga a conversa a um pedido.
Como funciona
O atendimento típico: o painel mostra a lista de conversas e o contador de não lidas; o administrador abre uma conversa (GET da conversa, depois PATCH read e PATCH delivered), responde com reply, e ao terminar muda o estado para resolved ou archived. Se a conversa for sobre um pedido, ele a liga ao pedido para ver o resumo ao lado.
| Estado | Letra | Significado |
|---|---|---|
open | A | Aberta (padrão). |
resolved | R | Resolvida. |
archived | C | Arquivada. |
Cada mensagem passa por três marcas: enviada, entregue (delivered_at) e lida (read_at, is_read).
Conceitos importantes
Participantes
Uma conversa tem um cliente e, opcionalmente, um seller. Sem seller, é uma conversa direta com a loja. O administrador responde como admin em qualquer uma.
Ligação com um registro
Uma conversa pode estar ligada a um pedido, produto, seller ou usuário (object_type, object_id). Isso não muda a conversa: só permite mostrar um resumo do registro ao lado do chat.
Tempo real
Respostas, marcas de leitura e o aviso "digitando" são enviados por uma conexão em tempo real (WebSocket) para quem estiver online. As rotas aqui são a forma de originar esses eventos e de consultar o estado salvo; a conexão em si fica fora desta seção.
Texto das mensagens
O corpo é gravado como texto puro: tags HTML e scripts são removidos antes de salvar.
Assistente de atendimento
Lojas que usam o assistente automático (SAC) podem passá-lo para o modo handoff quando um humano assume a conversa.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/admin/messages/threads | Lista todas as conversas da loja | admin |
| GET | /api/v1/admin/messages/threads/{id} | Devolve uma conversa com as mensagens | admin |
| GET | /api/v1/admin/messages/threads/find-for-customer | Devolve a conversa direta de um cliente, criando se não existir | admin |
| GET | /api/v1/admin/messages/unread-count | Devolve o total de mensagens que o administrador ainda não leu | admin |
| POST | /api/v1/admin/messages/threads/{id}/reply | Envia uma mensagem do administrador na conversa | admin |
| PATCH | /api/v1/admin/messages/threads/{id}/read | Marca como lidas as mensagens recebidas | admin |
| PATCH | /api/v1/admin/messages/threads/{id}/delivered | Registra que as mensagens chegaram à tela do administrador | admin |
| PATCH | /api/v1/admin/messages/threads/{id}/status | Marca a conversa como aberta, resolvida ou arquivada | admin |
| POST | /api/v1/admin/messages/threads/{id}/typing | Avisa os outros participantes que o administrador está digitando | admin |
| GET | /api/v1/admin/messages/threads/{id}/presence | Informa se os outros participantes estão conectados | admin |
| PATCH | /api/v1/admin/messages/threads/{id}/link | Associa a conversa a um pedido, produto, seller ou usuário | admin |
| PATCH | /api/v1/admin/messages/threads/{id}/unlink | Remove a ligação da conversa com o registro | admin |
| GET | /api/v1/admin/messages/threads/{id}/context | Devolve dados resumidos do pedido, produto, seller ou usuário ligado | admin |
| PUT | /api/v1/admin/messages/threads/{id}/agent | Define se o assistente automático de atendimento responde nesta conversa | admin |
Erros comuns
- Usar
find-for-customerpara "conferir se existe": ele cria uma conversa vazia. - Mandar o status da conversa como letra (
R): oPATCH statussó aceitaopen,resolvedearchived. - Enviar
replysembodye semattachments: 400. - Esperar que
replyreceba o arquivo do anexo: ele só guarda o endereço, o upload é feito antes. - Ligar uma conversa a um
object_typefora deorder,product,vendoreuser: grava, mas o contexto vemnull. - Esquecer de chamar
readao abrir a conversa: as não lidas continuam contando no sino.