VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Mensagens

Listar e abrir conversas

Lista as conversas da loja, abre uma com as mensagens, acha a conversa de um cliente e conta as não lidas.

Listar conversas

Devolve as conversas entre clientes, sellers e a loja, com a contagem de mensagens não lidas por conversa. O administrador vê todas, não só as suas.

GET/api/v1/admin/messages/threadsAdmin

Lista todas as conversas da loja

Exige o privilégio manage_settings. O administrador enxerga e responde qualquer conversa da loja.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, 1 a 100; fora disso vale 20.

Exemplo de requisição (Listar conversas)

bash
curl "$BASE_URL/api/v1/admin/messages/threads?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar conversas)

200Conversas
json
{
  "threads": [
    {
      "id": "02b7a358-6061-4d51-84c0-8044dbb6db6e",
      "subject": "Dúvida sobre produto",
      "status": "A",
      "object_type": "order",
      "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "object_name": "Pedido PEDIDO-20261011-0002",
      "customer_user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "customer_name": "Maria Souza",
      "last_message_preview": "Olá! Seu pedido já saiu para entrega.",
      "last_message_at": "2026-10-11T19:25:56.593566Z",
      "unread_count": 1,
      "created_at": "2026-10-11T18:11:59.835461Z",
      "updated_at": "2026-10-11T19:25:56.593566Z"
    }
  ],
  "total": 28,
  "page": 1,
  "per_page": 20,
  "total_pages": 2
}

Campos da resposta

threadsarray

Conversas da página, sem as mensagens.

iduuid
Identificador da conversa.
subjectstring
Assunto.
statusstring
Letra do estado: A aberta, R resolvida, C arquivada. Conversas antigas podem ter outras letras (por exemplo D).
object_typestring
Tipo do registro ligado à conversa (order, product, vendor, user). Ausente se não há.
object_idstring
Id do registro ligado. Ausente se não há.
object_namestring
Nome do registro ligado, para exibir.
customer_user_iduuid
Cliente da conversa.
vendor_iduuid
Seller da conversa. Ausente numa conversa direta com a loja.
vendor_namestring
Nome do seller.
customer_namestring
Nome do cliente.
last_message_previewstring
Prévia da última mensagem.
last_message_atstring
Hora da última mensagem, RFC 3339.
unread_countinteger
Mensagens ainda não lidas pelo administrador.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
totalinteger
Total de conversas.
pageinteger
Página devolvida.
per_pageinteger
Itens por página usados.
total_pagesinteger
Total de páginas.

Erros (Listar conversas)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio manage_settings.{"error":"insufficient privileges","required":"manage_settings"}
500Falha de banco.{"error":"failed to list threads","detail":"..."}

Consultar conversa

Devolve a conversa e as mensagens dela. Sem parâmetros, devolve todas as mensagens em ordem cronológica. Com page ou per_page as mensagens vêm paginadas, e a resposta ganha page, per_page, total e total_pages.

GET/api/v1/admin/messages/threads/{id}Admin

Devolve uma conversa com as mensagens

Exige o privilégio manage_settings. O administrador enxerga e responde qualquer conversa da loja.

Parâmetros de caminho

iduuidobrigatório
Identificador da conversa.

Parâmetros de consulta

pageintegerpadrão: 1
Ativa a paginação das mensagens. A partir de 1.
per_pageintegerpadrão: 50
Mensagens por página (padrão 50 quando a paginação está ativa).

Exemplo de requisição (Consultar conversa)

bash
curl "$BASE_URL/api/v1/admin/messages/threads/02b7a358-6061-4d51-84c0-8044dbb6db6e" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar conversa)

200Conversa
json
{
  "id": "02b7a358-6061-4d51-84c0-8044dbb6db6e",
  "subject": "Dúvida sobre produto",
  "status": "A",
  "object_type": "order",
  "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "object_name": "Pedido PEDIDO-20261011-0002",
  "customer_user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Loja Seller Teste",
  "customer_name": "Maria Souza",
  "last_message_preview": "Olá! Seu pedido já saiu para entrega.",
  "last_message_at": "2026-10-11T19:25:56.593566Z",
  "unread_count": 1,
  "created_at": "2026-10-11T18:11:59.835461Z",
  "updated_at": "2026-10-11T19:25:56.593566Z",
  "messages": [
    {
      "id": "ddfeb0e4-5c98-4bc3-ab4f-fad15ca6b364",
      "thread_id": "02b7a358-6061-4d51-84c0-8044dbb6db6e",
      "sender_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
      "sender_type": "admin",
      "body": "Olá! Seu pedido já saiu para entrega.",
      "attachments": [],
      "is_read": false,
      "created_at": "2026-10-11T19:25:56.593566Z"
    }
  ]
}

Campos da resposta

iduuid
Identificador da conversa.
subjectstring
Assunto.
statusstring
Letra do estado: A aberta, R resolvida, C arquivada. Conversas antigas podem ter outras letras (por exemplo D).
object_typestring
Tipo do registro ligado à conversa (order, product, vendor, user). Ausente se não há.
object_idstring
Id do registro ligado. Ausente se não há.
object_namestring
Nome do registro ligado, para exibir.
customer_user_iduuid
Cliente da conversa.
vendor_iduuid
Seller da conversa. Ausente numa conversa direta com a loja.
vendor_namestring
Nome do seller.
customer_namestring
Nome do cliente.
last_message_previewstring
Prévia da última mensagem.
last_message_atstring
Hora da última mensagem, RFC 3339.
messagesarray

Mensagens (só ao consultar uma conversa).

iduuid
Identificador da mensagem.
thread_iduuid
Conversa.
sender_iduuid
Usuário que enviou.
sender_typestring
customervendoradmin
Quem enviou.
bodystring
Texto, sem HTML.
attachmentsarray
Anexos. Cada um tem url, filename, content_type e size (bytes).
is_readboolean
true quando o outro lado leu.
delivered_atstring
Quando chegou ao outro lado, RFC 3339. Ausente se ainda não.
read_atstring
Quando foi lida, RFC 3339. Ausente se ainda não.
created_atstring
Envio, RFC 3339.
unread_countinteger
Mensagens ainda não lidas pelo administrador.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Consultar conversa)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio manage_settings.{"error":"insufficient privileges","required":"manage_settings"}
400O id não é um UUID válido.{"error":"invalid id","detail":"id must be a valid UUID"}
404Não existe conversa com esse id.{"error":"thread not found"}

Achar ou abrir a conversa de um cliente

Usada pelo botão "Contatar cliente" do painel. Procura a conversa direta (sem seller) do cliente com a loja. Se ela não existe, cria uma conversa vazia e a devolve, para o administrador já poder escrever.

GET/api/v1/admin/messages/threads/find-for-customerAdmin

Devolve a conversa direta de um cliente, criando se não existir

Exige o privilégio manage_settings. O administrador enxerga e responde qualquer conversa da loja.

Parâmetros de consulta

user_iduuidobrigatório
Cliente.
subjectstring
Assunto, usado só quando uma conversa nova precisa ser criada.

Exemplo de requisição (Conversa do cliente)

bash
curl "$BASE_URL/api/v1/admin/messages/threads/find-for-customer?user_id=3093f506-d6af-4c27-9ef6-c245e8e602f9&subject=Sobre o seu pedido" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Conversa do cliente)

200Conversa
json
{
  "id": "02b7a358-6061-4d51-84c0-8044dbb6db6e",
  "subject": "Dúvida sobre produto",
  "status": "A",
  "object_type": null,
  "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "object_name": "Pedido PEDIDO-20261011-0002",
  "customer_user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Loja Seller Teste",
  "customer_name": "Maria Souza",
  "last_message_preview": "Olá! Seu pedido já saiu para entrega.",
  "last_message_at": "2026-10-11T19:25:56.593566Z",
  "unread_count": 1,
  "created_at": "2026-10-11T18:11:59.835461Z",
  "updated_at": "2026-10-11T19:25:56.593566Z"
}

Campos da resposta

iduuid
Identificador da conversa.
subjectstring
Assunto.
statusstring
Letra do estado: A aberta, R resolvida, C arquivada. Conversas antigas podem ter outras letras (por exemplo D).
object_typestring
Tipo do registro ligado à conversa (order, product, vendor, user). Ausente se não há.
object_idstring
Id do registro ligado. Ausente se não há.
object_namestring
Nome do registro ligado, para exibir.
customer_user_iduuid
Cliente da conversa.
vendor_iduuid
Seller da conversa. Ausente numa conversa direta com a loja.
vendor_namestring
Nome do seller.
customer_namestring
Nome do cliente.
last_message_previewstring
Prévia da última mensagem.
last_message_atstring
Hora da última mensagem, RFC 3339.
unread_countinteger
Mensagens ainda não lidas pelo administrador.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Conversa do cliente)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio manage_settings.{"error":"insufficient privileges","required":"manage_settings"}
400Falta user_id.{"error":"user_id is required"}
500user_id que não é UUID, cliente inexistente, ou falha de banco.{"error":"failed to find or create thread","detail":"..."}
Um GET que escreve

Chamar esta rota para um cliente sem conversa cria uma conversa no banco. Não a use só para "verificar se existe".

Contar mensagens não lidas

Conta as mensagens, em todas as conversas, que não foram enviadas por administradores e ainda estão não lidas. Alimenta o número do sino do painel.

GET/api/v1/admin/messages/unread-countAdmin

Devolve o total de mensagens que o administrador ainda não leu

Exige o privilégio manage_settings. O administrador enxerga e responde qualquer conversa da loja.

Exemplo de requisição (Não lidas)

bash
curl "$BASE_URL/api/v1/admin/messages/unread-count" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Não lidas)

200Contagem
json
{
  "count": 6
}

Campos da resposta

countinteger
Mensagens não lidas.

Erros (Não lidas)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio manage_settings.{"error":"insufficient privileges","required":"manage_settings"}
500Falha de banco.{"error":"failed to get unread count","detail":"..."}

Veja também

  • Responder
  • Estado e leitura
Anterior
Mensagens
Próxima
Responder uma conversa
Nesta página
  • Listar conversas
  • Exemplo de requisição (Listar conversas)
  • Resposta (Listar conversas)
  • Erros (Listar conversas)
  • Consultar conversa
  • Exemplo de requisição (Consultar conversa)
  • Resposta (Consultar conversa)
  • Erros (Consultar conversa)
  • Achar ou abrir a conversa de um cliente
  • Exemplo de requisição (Conversa do cliente)
  • Resposta (Conversa do cliente)
  • Erros (Conversa do cliente)
  • Contar mensagens não lidas
  • Exemplo de requisição (Não lidas)
  • Resposta (Não lidas)
  • Erros (Não lidas)
  • Veja também