API atual/Referência completa/Mensagens e notificações

Leitura e presença

Marca mensagens como lidas ou entregues, avisa que o seller está digitando e mostra quem está online na conversa.

Estas quatro rotas existem para o app de atendimento ficar fiel ao que acontece do outro lado: os dois "vistos" de uma mensagem, o aviso "digitando..." e a bolinha verde de online. Em todas, a conversa precisa pertencer ao seller; caso contrário a resposta é 403.

Marcar como lida

PATCH/api/v1/vendor/messages/threads/{id}/readSeller

Marca como lidas as mensagens recebidas

Marca como lidas todas as mensagens da conversa que não foram enviadas pelo usuário que chama e ainda estavam não lidas. É idempotente: chamar de novo devolve count 0. O remetente recebe o aviso message.read.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/vendor/messages/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/read" \
  -H "Authorization: Bearer $TOKEN"

200Mensagens marcadas

json

{
  "message": "marked as read",
  "count": 3
}

Campos da resposta

messagestring

Texto fixo em inglês, marked as read.

countinteger

Quantas mensagens mudaram de não lida para lida agora.

Marcar como entregue

PATCH/api/v1/vendor/messages/threads/{id}/deliveredSeller

Marca como entregues as mensagens recebidas

Chame quando o app carregar a conversa na tela, antes de o atendente abri-la de fato. Grava delivered_at nas mensagens recebidas que ainda não tinham e avisa o remetente (message.delivered).

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/vendor/messages/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/delivered" \
  -H "Authorization: Bearer $TOKEN"

200Mensagens marcadas

json

{
  "message": "marked as delivered",
  "count": 3
}

Campos da resposta

messagestring

Texto fixo em inglês, marked as delivered.

countinteger

Quantas mensagens ganharam delivered_at agora.

Avisar que está digitando

POST/api/v1/vendor/messages/threads/{id}/typingSeller

Avisa o cliente que o seller está digitando

Nada é gravado: a plataforma só repassa o aviso thread.typing aos outros participantes. Envie a cada poucos segundos enquanto a pessoa digita e mande is_typing: false ao parar.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Corpo da requisição

is_typingbooleanpadrão: true

true ao começar ou continuar a digitar, false ao parar. Um corpo ausente ou inválido conta como true.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/messages/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/typing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "is_typing": true
}'

204Sem conteúdo

json

(empty body)

Ver presença

GET/api/v1/vendor/messages/threads/{id}/presenceSeller

Quem está online na conversa

Lista os outros participantes (o próprio usuário fica de fora) e se cada um tem uma conexão em tempo real aberta neste instante. Use na abertura da conversa; depois acompanhe pelo canal em tempo real.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/messages/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/presence" \
  -H "Authorization: Bearer $TOKEN"

200Presença

json

{
  "participants": [
    {
      "user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
      "online": false
    }
  ]
}

Campos da resposta

participantsarray

Outros participantes da conversa.

user_iduuid

Id do usuário.

onlineboolean

true se há conexão em tempo real aberta agora.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
400	O `{id}` do caminho não é um UUID.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
403	A conversa não existe ou não pertence ao seller. A API não distingue os dois casos.	`{"error":"you are not a participant of this thread"}`
500	Falha ao gravar a marcação.	`{"error":"failed to mark read","detail":"..."}`

Veja também

API atual/Referência completa/Mensagens e notificações

Leitura e presença

Marca mensagens como lidas ou entregues, avisa que o seller está digitando e mostra quem está online na conversa.

Marcar como lida

PATCH/api/v1/vendor/messages/threads/{id}/readSeller

Marca como lidas as mensagens recebidas

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/vendor/messages/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/read" \
  -H "Authorization: Bearer $TOKEN"

200Mensagens marcadas

json

{
  "message": "marked as read",
  "count": 3
}

Campos da resposta

messagestring

Texto fixo em inglês, marked as read.

countinteger

Quantas mensagens mudaram de não lida para lida agora.

Marcar como entregue

PATCH/api/v1/vendor/messages/threads/{id}/deliveredSeller

Marca como entregues as mensagens recebidas

Chame quando o app carregar a conversa na tela, antes de o atendente abri-la de fato. Grava delivered_at nas mensagens recebidas que ainda não tinham e avisa o remetente (message.delivered).

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/vendor/messages/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/delivered" \
  -H "Authorization: Bearer $TOKEN"

200Mensagens marcadas

json

{
  "message": "marked as delivered",
  "count": 3
}

Campos da resposta

messagestring

Texto fixo em inglês, marked as delivered.

countinteger

Quantas mensagens ganharam delivered_at agora.

Avisar que está digitando

POST/api/v1/vendor/messages/threads/{id}/typingSeller

Avisa o cliente que o seller está digitando

Nada é gravado: a plataforma só repassa o aviso thread.typing aos outros participantes. Envie a cada poucos segundos enquanto a pessoa digita e mande is_typing: false ao parar.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Corpo da requisição

is_typingbooleanpadrão: true

true ao começar ou continuar a digitar, false ao parar. Um corpo ausente ou inválido conta como true.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/messages/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/typing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "is_typing": true
}'

204Sem conteúdo

json

(empty body)

Ver presença

GET/api/v1/vendor/messages/threads/{id}/presenceSeller

Quem está online na conversa

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/messages/threads/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/presence" \
  -H "Authorization: Bearer $TOKEN"

200Presença

json

{
  "participants": [
    {
      "user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
      "online": false
    }
  ]
}

Campos da resposta

participantsarray

Outros participantes da conversa.

user_iduuid

Id do usuário.

onlineboolean

true se há conexão em tempo real aberta agora.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
400	O `{id}` do caminho não é um UUID.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
403	A conversa não existe ou não pertence ao seller. A API não distingue os dois casos.	`{"error":"you are not a participant of this thread"}`
500	Falha ao gravar a marcação.	`{"error":"failed to mark read","detail":"..."}`