API atual/Referência completa/Lives de vendas

Chat da live

Lê o histórico de mensagens de uma live e envia uma nova mensagem, como visitante ou como cliente logado.

O chat é uma sala única por live. Quem entra depois que a transmissão começou carrega o histórico com GET e, daí em diante, recebe as novas mensagens por polling ou pelo evento live.chat.message do WebSocket (veja a home da seção). Para falar, qualquer pessoa pode enviar uma mensagem; o cliente logado aparece com o nome da conta.

GET/api/v1/storefront/live-sessions/{id}/messagesPública

Ler o histórico do chat

Parâmetros de caminho

iduuidobrigatório

Id da live.

Parâmetros de consulta

limitintegerpadrão: 100

Quantas mensagens recentes devolver, de 1 a 500. Fora da faixa ou não numérico, vale 100.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/live-sessions/$SESSION_ID/messages?limit=50"

Resposta

200Mensagens

json

{
  "messages": [
    {
      "id": "b3d1c1a2-5d3e-4c1b-9b7a-1b0f6b8c2a10",
      "session_id": "7c1e5c52-0d63-4a6a-9a52-6f3a52a0f111",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "guest_name": "",
      "body": "Qual é o prazo de entrega para Curitiba?",
      "created_at": "2026-10-11T19:10:03Z",
      "author_name": "Maria S."
    }
  ],
  "total": 1
}

Campos da resposta

messagesarray

Mensagens em ordem cronológica. [] quando não há nenhuma.

messages[].iduuid

Id da mensagem.

messages[].session_iduuid

Live à qual pertence.

messages[].user_iduuid

Id do cliente, quando a mensagem veio de uma conta logada. Ausente para visitante.

messages[].guest_namestring

Nome informado pelo visitante. Vazio para cliente logado.

messages[].bodystring

Texto da mensagem.

messages[].created_atstring

Quando foi enviada (RFC 3339, UTC).

messages[].author_namestring

Nome para exibir. Para cliente logado é o nome público da conta; sem nome, usa a parte do e-mail antes do @; para visitante, o guest_name.

totalinteger

Quantidade de mensagens nesta resposta (não é o total da live).

Erros

Status	Quando	Corpo
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
404	O id não é um UUID. Uma live inexistente com UUID válido devolve `200` com lista vazia.	`{"error":"LIVE_SESSION_NOT_FOUND"}`
500	Falha ao ler o chat.	`{"error":"LIVE_CHAT_LIST_FAILED","detail":"..."}`

POST/api/v1/storefront/live-sessions/{id}/messagesPública

Enviar uma mensagem ao chat

O token do cliente é opcional. Com Authorization: Bearer, a mensagem fica ligada à conta e o author_name sai do cadastro. Sem token, a mensagem é de visitante e mostra o guest_name.

Parâmetros de caminho

iduuidobrigatório

Id da live.

Cabeçalhos

Authorizationstring

Bearer <access_token> do cliente. Opcional. Um token inválido ou expirado não gera erro: ele é ignorado e a mensagem sai como de visitante.

Corpo da requisição

bodystringobrigatório

Texto da mensagem. Não pode ser vazio nem só espaços. Máximo de 1000 caracteres; o excedente é cortado.

guest_namestring

Nome exibido quando não há login. Para cliente logado o nome exibido vem da conta (o valor enviado fica gravado, mas não é usado na exibição). Sem login e sem nome, a mensagem sai com author_name vazio.

bash

curl -X POST "$BASE_URL/api/v1/storefront/live-sessions/$SESSION_ID/messages" \
  -H "Content-Type: application/json" \
  -d '{"guest_name":"Ana","body":"Boa noite, pessoal!"}'

201Mensagem criada

json

{
  "id": "0c9a1c58-7a0b-4a58-8f6e-7a1e8a2d9f55",
  "session_id": "7c1e5c52-0d63-4a6a-9a52-6f3a52a0f111",
  "guest_name": "Ana",
  "body": "Boa noite, pessoal!",
  "created_at": "0001-01-01T00:00:00Z",
  "author_name": "Ana"
}

A resposta tem os mesmos campos de uma mensagem do histórico. Ao salvar, a plataforma também publica a mensagem aos espectadores conectados pelo WebSocket. O campo created_at da resposta de criação vem sempre zerado (0001-01-01T00:00:00Z); use o created_at do histórico se precisar do horário real.

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"INVALID_BODY","detail":"..."}`
400	`body` vazio.	`{"error":"LIVE_CHAT_POST_FAILED","detail":"body is required"}`
400	A live está `ended` ou `cancelled`.	`{"error":"LIVE_CHAT_POST_FAILED","detail":"chat is closed for this session"}`
400	A live não existe.	`{"error":"LIVE_CHAT_POST_FAILED","detail":"live session <id> not found"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`

Veja também

Chat da live

Lê o histórico de mensagens de uma live e envia uma nova mensagem, como visitante ou como cliente logado.

GET/api/v1/storefront/live-sessions/{id}/messagesPública

Ler o histórico do chat

Parâmetros de caminho

iduuidobrigatório

Id da live.

Parâmetros de consulta

limitintegerpadrão: 100

Quantas mensagens recentes devolver, de 1 a 500. Fora da faixa ou não numérico, vale 100.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/live-sessions/$SESSION_ID/messages?limit=50"

Resposta

200Mensagens

json

{
  "messages": [
    {
      "id": "b3d1c1a2-5d3e-4c1b-9b7a-1b0f6b8c2a10",
      "session_id": "7c1e5c52-0d63-4a6a-9a52-6f3a52a0f111",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "guest_name": "",
      "body": "Qual é o prazo de entrega para Curitiba?",
      "created_at": "2026-10-11T19:10:03Z",
      "author_name": "Maria S."
    }
  ],
  "total": 1
}

Campos da resposta

messagesarray

Mensagens em ordem cronológica. [] quando não há nenhuma.

messages[].iduuid

Id da mensagem.

messages[].session_iduuid

Live à qual pertence.

messages[].user_iduuid

Id do cliente, quando a mensagem veio de uma conta logada. Ausente para visitante.

messages[].guest_namestring

Nome informado pelo visitante. Vazio para cliente logado.

messages[].bodystring

Texto da mensagem.

messages[].created_atstring

Quando foi enviada (RFC 3339, UTC).

messages[].author_namestring

Nome para exibir. Para cliente logado é o nome público da conta; sem nome, usa a parte do e-mail antes do @; para visitante, o guest_name.

totalinteger

Quantidade de mensagens nesta resposta (não é o total da live).

Erros

Status	Quando	Corpo
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`
404	O id não é um UUID. Uma live inexistente com UUID válido devolve `200` com lista vazia.	`{"error":"LIVE_SESSION_NOT_FOUND"}`
500	Falha ao ler o chat.	`{"error":"LIVE_CHAT_LIST_FAILED","detail":"..."}`

POST/api/v1/storefront/live-sessions/{id}/messagesPública

Enviar uma mensagem ao chat

O token do cliente é opcional. Com Authorization: Bearer, a mensagem fica ligada à conta e o author_name sai do cadastro. Sem token, a mensagem é de visitante e mostra o guest_name.

Parâmetros de caminho

iduuidobrigatório

Id da live.

Cabeçalhos

Authorizationstring

Bearer <access_token> do cliente. Opcional. Um token inválido ou expirado não gera erro: ele é ignorado e a mensagem sai como de visitante.

Corpo da requisição

bodystringobrigatório

Texto da mensagem. Não pode ser vazio nem só espaços. Máximo de 1000 caracteres; o excedente é cortado.

guest_namestring

bash

curl -X POST "$BASE_URL/api/v1/storefront/live-sessions/$SESSION_ID/messages" \
  -H "Content-Type: application/json" \
  -d '{"guest_name":"Ana","body":"Boa noite, pessoal!"}'

201Mensagem criada

json

{
  "id": "0c9a1c58-7a0b-4a58-8f6e-7a1e8a2d9f55",
  "session_id": "7c1e5c52-0d63-4a6a-9a52-6f3a52a0f111",
  "guest_name": "Ana",
  "body": "Boa noite, pessoal!",
  "created_at": "0001-01-01T00:00:00Z",
  "author_name": "Ana"
}

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"INVALID_BODY","detail":"..."}`
400	`body` vazio.	`{"error":"LIVE_CHAT_POST_FAILED","detail":"body is required"}`
400	A live está `ended` ou `cancelled`.	`{"error":"LIVE_CHAT_POST_FAILED","detail":"chat is closed for this session"}`
400	A live não existe.	`{"error":"LIVE_CHAT_POST_FAILED","detail":"live session <id> not found"}`
403	Módulo `live-commerce` desligado.	`{"error":"module_disabled","module":"live-commerce"}`