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 personalizados aparecem nos detalhes da conversa na Caixa de entrada. As chaves internas são filtradas, e os dados de contato capturados e a memória das Actions têm sua própria apresentação
• 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 quando permitido: o contexto do modelo usa um subconjunto filtrado dos metadados. Armazenar uma chave não garante que o modelo a receba ou mencione

Use metadados para referências de clientes, contexto da conta, analítica e dados de entrada das Actions. O armazenamento, a exibição na Caixa de entrada, a substituição nas Actions e o contexto do modelo são usos distintos dos mesmos dados.

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

Contexto do modelo e autorização

Em canais controlados pelo visitante, como o Widget e o Embed do site, o contexto do modelo aceita as chaves de contato do visitante (visitor_name, visitor_email, visitor_phone_number) e as chaves elegíveis referenciadas ou capturadas por Actions ativas. Os valores internos e reservados são filtrados; também se aplicam limites de configuração e tamanho. Outras integrações têm regras de contexto específicas para cada canal. Uma chave personalizada como customer_tier ou customer_id não fica automaticamente visível para o modelo só porque você a enviou.

Uma Action pode substituir {{metadata_<key>}} ao montar sua requisição sem pedir à IA que gere esse valor. Isso não torna os metadados comuns secretos: um valor elegível pode entrar separadamente no contexto do modelo ou aparecer na resposta de uma Action. Não armazene chaves de API ou senhas nos metadados personalizados.

Os metadados enviados pelo navegador não comprovam identidade nem permissão. O serviço que os recebe deve autenticar e autorizar o acesso a registros privados; um ID de cliente ou nível de plano enviado pelo navegador não é suficiente. Teste tanto a requisição resultante da Action quanto a resposta do Agente na sua configuração.

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"
  }
}

---