Ligar à conversa

Liga a conversa a um pedido, produto, seller ou usuário, lê o resumo do registro e liga o assistente.

Ligar a conversa a um registro

Define o registro a que a conversa se refere, depois de criada. Assim o painel mostra o resumo do registro ao lado do chat (rota de contexto). Substitui a ligação anterior, se houver.

PATCH/api/v1/admin/messages/threads/{id}/linkAdmin

Associa a conversa a um pedido, produto, seller ou usuário

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

Parâmetros de caminho

iduuidobrigatório

Identificador da conversa.

Corpo da requisição

object_typestringobrigatório

Tipo do registro. A rota não valida: qualquer texto é gravado. A rota de contexto só resolve order, product, vendor e user.

object_idstringobrigatório

Id do registro.

object_namestring

Nome para exibir (por exemplo o número do pedido).

Exemplo de requisição (Ligar)

bash

curl -X PATCH "$BASE_URL/api/v1/admin/messages/threads/02b7a358-6061-4d51-84c0-8044dbb6db6e/link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "object_type": "order",
  "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "object_name": "Pedido PEDIDO-20261011-0002"
}'

Resposta (Ligar)

200Conversa ligada

json

{
  "id": "02b7a358-6061-4d51-84c0-8044dbb6db6e",
  "object_type": "order",
  "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "object_name": "Pedido PEDIDO-20261011-0002"
}

Erros (Ligar)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
400	Faltam `object_type` ou `object_id`.	`{"error":"object_type and object_id are required"}`
404	Conversa inexistente.	`{"error":"thread not found"}`

Desligar a conversa do registro

Limpa object_type, object_id e object_name da conversa. Não precisa de corpo.

PATCH/api/v1/admin/messages/threads/{id}/unlinkAdmin

Remove a ligação da conversa com o registro

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

Parâmetros de caminho

iduuidobrigatório

Identificador da conversa.

Exemplo de requisição (Desligar)

bash

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

Resposta (Desligar)

200Conversa desligada

json

{
  "id": "02b7a358-6061-4d51-84c0-8044dbb6db6e",
  "message": "thread unlinked"
}

Erros (Desligar)

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

Ver o registro ligado à conversa

Quando a conversa está ligada a um registro (veja Ligar à conversa), devolve um resumo dele para o painel mostrar ao lado do chat. Sem ligação, devolve {"context": null}.

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

Devolve dados resumidos do pedido, produto, seller ou usuário ligado

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

Parâmetros de caminho

iduuidobrigatório

Identificador da conversa.

Exemplo de requisição (Contexto)

bash

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

Resposta (Contexto)

200Contexto de pedido

json

{
  "object_type": "order",
  "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "data": {
    "order_number": "PEDIDO-20261011-0002",
    "status": "O",
    "total": 24000,
    "customer_name": "Maria Souza"
  }
}

200Sem ligação

json

{
  "context": null
}

Campos da resposta

object_typestring

order, product, vendor ou user.

object_idstring

Id do registro.

dataobject

Resumo, que depende do tipo. order: order_number, status, total (centavos), customer_name. product: name, sku, price (centavos), image_url. vendor: company_name, status, email. user: name, email, role.

Erros (Contexto)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`

Ligar ou desligar o assistente da conversa

Quando a loja usa o assistente automático de atendimento (SAC), esta rota diz se ele responde nesta conversa. É o botão "Assumir" do painel: ao assumir, o atendente humano silencia o assistente.

PUT/api/v1/admin/messages/threads/{id}/agentAdmin

Define se o assistente automático de atendimento responde nesta conversa

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

Parâmetros de caminho

iduuidobrigatório

Identificador da conversa.

Corpo da requisição

agent_statusstringobrigatório

activehandoffoff

active o assistente responde; handoff um humano assumiu e o assistente se cala; off o assistente fica desligado nesta conversa.

Exemplo de requisição (Assistente)

bash

curl -X PUT "$BASE_URL/api/v1/admin/messages/threads/02b7a358-6061-4d51-84c0-8044dbb6db6e/agent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_status": "handoff"
}'

Resposta (Assistente)

200Estado definido

json

{
  "ok": true,
  "agent_status": "handoff"
}

Campos da resposta

okboolean

Sempre true em caso de sucesso.

agent_statusstring

Valor gravado.

Erros (Assistente)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
400	`agent_status` fora da lista, ou corpo inválido.	`{"error":"invalid agent_status"}`
500	`id` que não é UUID, ou falha de banco (esta rota não valida o `id`).	`{"error":"..."}`

Veja também

API atual/Referência completa/Mensagens

Ligar à conversa

Liga a conversa a um pedido, produto, seller ou usuário, lê o resumo do registro e liga o assistente.

Ligar a conversa a um registro

Define o registro a que a conversa se refere, depois de criada. Assim o painel mostra o resumo do registro ao lado do chat (rota de contexto). Substitui a ligação anterior, se houver.

PATCH/api/v1/admin/messages/threads/{id}/linkAdmin

Associa a conversa a um pedido, produto, seller ou usuário

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

Parâmetros de caminho

iduuidobrigatório

Identificador da conversa.

Corpo da requisição

object_typestringobrigatório

Tipo do registro. A rota não valida: qualquer texto é gravado. A rota de contexto só resolve order, product, vendor e user.

object_idstringobrigatório

Id do registro.

object_namestring

Nome para exibir (por exemplo o número do pedido).

Exemplo de requisição (Ligar)

bash

curl -X PATCH "$BASE_URL/api/v1/admin/messages/threads/02b7a358-6061-4d51-84c0-8044dbb6db6e/link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "object_type": "order",
  "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "object_name": "Pedido PEDIDO-20261011-0002"
}'

Resposta (Ligar)

200Conversa ligada

json

{
  "id": "02b7a358-6061-4d51-84c0-8044dbb6db6e",
  "object_type": "order",
  "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "object_name": "Pedido PEDIDO-20261011-0002"
}

Erros (Ligar)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
400	Faltam `object_type` ou `object_id`.	`{"error":"object_type and object_id are required"}`
404	Conversa inexistente.	`{"error":"thread not found"}`

Desligar a conversa do registro

Limpa object_type, object_id e object_name da conversa. Não precisa de corpo.

PATCH/api/v1/admin/messages/threads/{id}/unlinkAdmin

Remove a ligação da conversa com o registro

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

Parâmetros de caminho

iduuidobrigatório

Identificador da conversa.

Exemplo de requisição (Desligar)

bash

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

Resposta (Desligar)

200Conversa desligada

json

{
  "id": "02b7a358-6061-4d51-84c0-8044dbb6db6e",
  "message": "thread unlinked"
}

Erros (Desligar)

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

Ver o registro ligado à conversa

Quando a conversa está ligada a um registro (veja Ligar à conversa), devolve um resumo dele para o painel mostrar ao lado do chat. Sem ligação, devolve {"context": null}.

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

Devolve dados resumidos do pedido, produto, seller ou usuário ligado

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

Parâmetros de caminho

iduuidobrigatório

Identificador da conversa.

Exemplo de requisição (Contexto)

bash

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

Resposta (Contexto)

200Contexto de pedido

json

{
  "object_type": "order",
  "object_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "data": {
    "order_number": "PEDIDO-20261011-0002",
    "status": "O",
    "total": 24000,
    "customer_name": "Maria Souza"
  }
}

200Sem ligação

json

{
  "context": null
}

Campos da resposta

object_typestring

order, product, vendor ou user.

object_idstring

Id do registro.

dataobject

Erros (Contexto)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`

Ligar ou desligar o assistente da conversa

Quando a loja usa o assistente automático de atendimento (SAC), esta rota diz se ele responde nesta conversa. É o botão "Assumir" do painel: ao assumir, o atendente humano silencia o assistente.

PUT/api/v1/admin/messages/threads/{id}/agentAdmin

Define se o assistente automático de atendimento responde nesta conversa

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

Parâmetros de caminho

iduuidobrigatório

Identificador da conversa.

Corpo da requisição

agent_statusstringobrigatório

activehandoffoff

active o assistente responde; handoff um humano assumiu e o assistente se cala; off o assistente fica desligado nesta conversa.

Exemplo de requisição (Assistente)

bash

curl -X PUT "$BASE_URL/api/v1/admin/messages/threads/02b7a358-6061-4d51-84c0-8044dbb6db6e/agent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_status": "handoff"
}'

Resposta (Assistente)

200Estado definido

json

{
  "ok": true,
  "agent_status": "handoff"
}

Campos da resposta

okboolean

Sempre true em caso de sucesso.

agent_statusstring

Valor gravado.

Erros (Assistente)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
400	`agent_status` fora da lista, ou corpo inválido.	`{"error":"invalid agent_status"}`
500	`id` que não é UUID, ou falha de banco (esta rota não valida o `id`).	`{"error":"..."}`