Abrir thread

Abre uma conversa nova com a loja ou com um seller, já com a primeira mensagem do cliente.

Use esta rota quando o cliente começa um assunto: uma dúvida sobre um produto, um problema com um pedido ou um contato geral. A thread nasce A (aberta) e a primeira mensagem, se vier, é gravada como do cliente. A resposta é a thread completa.

POST/api/v1/storefront/messages/threadsCliente

Abrir uma thread

Corpo da requisição

subjectstringobrigatório

Assunto da conversa. Vazio devolve 400.

bodystring

Texto da primeira mensagem. Opcional.

vendor_iduuid

Seller que receberá a conversa. Omita para falar com a loja.

object_typestring

Tipo do objeto ligado, por exemplo order ou product. Os tipos order, product, vendor e user têm contexto em Ler thread e contexto.

object_iduuid

Id do objeto ligado. Use junto com object_type. Precisa ser um UUID.

object_namestring

Rótulo para exibir, como o número do pedido.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/messages/threads" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Dúvida sobre o pedido",
    "body": "Quando meu pedido sai?",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "object_type": "order",
    "object_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
    "object_name": "PEDIDO-20261010-0004"
  }'

Resposta

201Thread criada

json

{
  "id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
  "subject": "Dúvida sobre o pedido",
  "status": "A",
  "object_type": "order",
  "object_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "object_name": "PEDIDO-20261010-0004",
  "customer_user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "vendor_name": "Casa do Café",
  "customer_name": "Maria Souza",
  "last_message_preview": "Quando meu pedido sai?",
  "last_message_at": "2026-10-11T17:00:00Z",
  "unread_count": 0,
  "created_at": "2026-10-11T17:00:00Z",
  "updated_at": "2026-10-11T17:00:00Z",
  "messages": [
    {
      "id": "5d0a0f4e-2c3b-4b8a-8a6d-0d9d2b1c7e10",
      "thread_id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
      "sender_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "sender_type": "customer",
      "body": "Quando meu pedido sai?",
      "attachments": [],
      "is_read": false,
      "created_at": "2026-10-11T17:00:00Z"
    }
  ]
}

A resposta tem os mesmos campos de Ler a thread. Ao criar, os participantes recebem um evento new_message pelo WebSocket.

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`subject` vazio.	`{"error":"subject is required"}`
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`
403	Token de chave de API sem o escopo `customer:write`.	`{"error":"missing_scope","required":"customer:write"}`
500	Falha ao gravar, inclusive `vendor_id` ou `object_id` mal formado.	`{"error":"failed to create thread","detail":"..."}`

Veja também