Mensagens
Caixa de entrada do seller: conversas com clientes, respostas, confirmação de leitura, estado da conversa e notificações.
Uma conversa (thread) é um diálogo entre um cliente da loja e um seller (lojista), o vendedor que opera dentro do marketplace. O cliente abre a conversa na vitrine, normalmente a partir de um produto ou de um pedido, e o seller responde por estas rotas, em /api/v1/vendor/messages. A mesma conversa aparece para o administrador da loja, que enxerga todas.
Como funciona
O fluxo típico de um atendimento:
- Ver o que chegou
Chame Contar não lidas para o contador e Listar conversas para a fila. A lista vem da conversa com atividade mais recente para a mais antiga.
- Abrir a conversa
Consultar conversa devolve as mensagens. Se a conversa tem pedido ou produto ligado, o contexto traz os dados dele.
- Responder e confirmar a leitura
Responder grava a mensagem. Leitura e presença marca as mensagens do cliente como lidas.
- Encerrar
Estado da conversa marca como resolvida ou arquivada.
Conceitos-chave
Estados da conversa
O campo status da conversa é uma única letra. A API aceita palavras ao mudar o estado e devolve letras.
| Letra | Palavra ao alterar | Significado |
|---|---|---|
A | open | Aberta (padrão de toda conversa nova). |
R | resolved | Resolvida pelo atendimento. |
C | archived | Arquivada. Não existe uma letra separada de arquivo. |
Mensagens: lida, entregue e ordem
Cada mensagem tem is_read, delivered_at e read_at. "Entregue" significa que o app do destinatário carregou a mensagem; "lida" significa que a pessoa abriu a conversa. A contagem de não lidas do seller ignora as mensagens que o próprio seller enviou.
Tempo real
Ao responder, marcar como lida ou entregue, ou avisar que está digitando, a plataforma envia um evento por WebSocket aos outros participantes (new_message, message.read, message.delivered, thread.typing). Se ninguém estiver conectado, nada se perde: o estado fica gravado e pode ser lido por estas rotas.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/vendor/messages/threads | Lista as conversas do seller. | vendor |
| GET | /api/v1/vendor/messages/unread-count | Conta mensagens não lidas. | vendor |
| GET | /api/v1/vendor/messages/threads/{id} | Devolve a conversa e as mensagens. | vendor |
| GET | /api/v1/vendor/messages/threads/{id}/context | Dados do pedido, produto ou seller ligado. | vendor |
| POST | /api/v1/vendor/messages/threads/{id}/reply | Envia uma mensagem. | vendor |
| PATCH | /api/v1/vendor/messages/threads/{id}/read | Marca as mensagens recebidas como lidas. | vendor |
| PATCH | /api/v1/vendor/messages/threads/{id}/delivered | Marca as mensagens recebidas como entregues. | vendor |
| POST | /api/v1/vendor/messages/threads/{id}/typing | Avisa que o seller está digitando. | vendor |
| GET | /api/v1/vendor/messages/threads/{id}/presence | Diz quem está online na conversa. | vendor |
| PATCH | /api/v1/vendor/messages/threads/{id}/status | Marca como aberta, resolvida ou arquivada. | vendor |
| GET | /api/v1/vendor/notifications | Lista as notificações do usuário. | vendor |
Erros comuns
- Esperar
404para uma conversa inexistente. A checagem de participante vem antes: o id inexistente e o id de outro seller devolvem403. - Mandar a letra ao mudar o estado.
PATCH .../statusaceitaopen,resolvedearchived;Rdá400. - Ler o paginado como se fosse cronológico. Com
pageouper_page, as mensagens vêm da mais nova para a mais antiga. Sem eles, vêm todas, da mais antiga para a mais nova. - Tentar abrir uma conversa. Não há rota de criação para o seller; a conversa nasce no lado do cliente.
- Enviar mensagem sem texto e sem anexo. Responde
400 body or attachments required. - Usar um usuário de equipe. A caixa de entrada é resolvida pelo dono do seller; a equipe não vê as conversas.