# Conversation Metadata

> Attach custom key-value data to conversations, bridging your own systems and your AI Agent.

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](/api-reference/ai-actions/). See [AI Action Variables](/ai-agent/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**

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

**Python**

```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`

```json
{
  "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` <br/> object, required | Key-value metadata to store |

**Shell**

```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**

```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`

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

---