Conversation Metadata

Conversation Metadata lets you attach custom key-value data to conversations, creating a powerful bridge between your systems and your AI Agent. Metadata flows through your entire Quickchat workflow:

• Feed via API — Use these endpoints to programmatically attach metadata to any conversation (e.g., from your CRM, helpdesk, or backend)
• Feed via widget/embed — Pass metadata as initialization parameters when loading the widget, or inject it dynamically during an active conversation using the JavaScript SDK
• Visible in the Dashboard — Metadata appears in the conversation detail view in the Inbox, so your team always has context
• Included in exports — Metadata is included when you export conversations from the Dashboard, making it available for offline analysis
• Used in AI Actions — Metadata values can be injected directly as {{metadata_<key>}} placeholders into AI Actions. See AI Action Variables for the full reference of available placeholders
• Available to the AI Agent — Your AI Agent is aware of metadata values and can reference them during conversations. For example, pass a customer’s name or plan tier, and the AI will personalize its responses accordingly

Metadata is the way to dynamically steer and personalize each conversation. Pass customer IDs, account tiers, referral sources, A/B test variants, or any context your AI Agent needs. This capability will be significantly expanded in future releases.

Metadata is validated against a JSON schema if one is configured in the 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

Create or update metadata for a conversation.

Scope: write_all

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

Request Body

Parameter	Description
metadata object, required	Key-value metadata to store

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

---