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: custom metadata appears in the Inbox’s conversation details. Internal keys are filtered, and captured contact details and Action memory have their own presentation
• 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 when permitted: model context uses a filtered subset of metadata. Storing a key does not guarantee the model will receive it or mention it

Use metadata for customer references, account context, analytics, and Action inputs. Storage, Inbox display, Action substitution, and model context are separate uses of the same data.

Metadata is validated against a JSON schema if one is configured in the Dashboard.

Model context and authorization

On visitor-controlled channels such as the website Widget and Embed, model context admits visitor contact keys (visitor_name, visitor_email, visitor_phone_number) and eligible keys referenced or captured by active Actions. Internal and reserved values are filtered; configuration and size limits also apply. Other integrations have channel-specific context rules. A custom customer_tier or customer_id key is not automatically model-visible just because you sent it.

An Action can substitute {{metadata_<key>}} when building its request without asking the AI to generate that value. This does not make ordinary metadata secret: an eligible value may separately enter model context or appear in an Action response. Do not store API keys or passwords in custom metadata.

Browser-supplied metadata is not proof of identity or permission. Your receiving service must authenticate and authorize access to private records; a customer ID or plan tier sent by a browser is not sufficient. Test both the resulting Action request and the Agent’s reply for your configuration.

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

---