Conversation Metadata

O Conversation Metadata permite anexar dados chave-valor personalizados às conversas, criando uma ponte poderosa entre seus sistemas e seu Agente de IA. Os metadados fluem por todo o seu workflow do Quickchat:

• Alimentar via API — Use estes endpoints para anexar metadados de forma programática a qualquer conversa (ex.: a partir do seu CRM, helpdesk ou backend)
• Alimentar via widget/embed — Passe metadados como parâmetros de inicialização ao carregar o widget, ou injete-os dinamicamente durante uma conversa ativa usando o SDK JavaScript
• Visível no Dashboard — Os metadados aparecem na visualização de detalhes da conversa na Inbox, então sua equipe sempre tem contexto
• Incluídos nas exportações — Os metadados são incluídos quando você exporta conversas a partir do Dashboard, tornando-os disponíveis para análise offline
• Usados em AI Actions — Os valores de metadados podem ser injetados diretamente como placeholders {{metadata_<key>}} nas AI Actions. Veja Variáveis de AI Actions para a referência completa dos placeholders disponíveis
• Disponíveis para o Agente de IA — Seu Agente de IA conhece os valores de metadados e pode referenciá-los durante as conversas. Por exemplo, passe o nome de um cliente ou o nível do plano, e a IA personalizará suas respostas de acordo

Os metadados são a forma de direcionar e personalizar dinamicamente cada conversa. Passe IDs de clientes, níveis de conta, fontes de indicação, variantes de testes A/B ou qualquer contexto que seu Agente de IA precise. Essa capacidade será significativamente expandida em versões futuras.

Os metadados são validados contra um JSON schema, se houver um configurado no Dashboard.

Get Metadata

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

Set Metadata

Cria ou atualiza os metadados de uma conversa.

Scope: write_all

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Request Body

Parameter	Description
metadata object, required	Metadados chave-valor a armazenar

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "metadata": {"ticket_id": "T-1234", "priority": "high"}
    },
)
data = response.json()

Response 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---