Метаданные разговора

Метаданные разговора позволяют прикреплять пользовательские пары ключ-значение к разговорам, связывая ваши системы с AI-агентом. Метаданные проходят через весь рабочий процесс Quickchat:

• Передача через API: используйте эти endpoints для программного добавления метаданных в любой разговор (например, из CRM, службы поддержки или backend)
• Передача через виджет или встраивание: передавайте метаданные как параметры инициализации при загрузке виджета или добавляйте их динамически в активный разговор через JavaScript SDK
• Отображение в панели управления: пользовательские метаданные видны в деталях разговора во Входящих. Внутренние ключи фильтруются, а собранные контактные данные и память действий имеют отдельное представление
• Включение в экспорт: метаданные входят в экспорт разговоров из панели управления и доступны для анализа вне системы
• Использование в AI-действиях: значения можно подставлять прямо в AI-действия через {{metadata_<key>}}. Полный перечень доступных подстановок см. в Переменных AI-действий
• Доступность AI-агенту при разрешении: в контекст модели попадает отфильтрованное подмножество метаданных. Сохранение ключа не гарантирует, что модель получит или упомянет его

Используйте метаданные для ссылок на клиентов, контекста аккаунта, аналитики и входных данных действий. Хранение, отображение во Входящих, подстановка в действия и контекст модели являются отдельными способами использования одних данных.

Если в панели управления настроена JSON-схема, метаданные проверяются по ней.

Необязательные проверки примеров

• Предпросмотр ключей метаданных. Проверьте, как заданные имена полей преобразуются в ключи переменных, включая дубликаты и ошибки зарезервированных ключей. Проверка не изучает значения или разрешения конкретного аккаунта.

• Проверка условий запуска действий. Оцените условия на заданных примерах метаданных без запуска действия.

В совместимом браузере эти проверки также доступны как инструменты сайта. Ссылки открывают обычные формы.

Контекст модели и авторизация

На каналах, контролируемых посетителем, например Виджете сайта и Встраивании, контекст модели допускает контактные ключи посетителя (visitor_name, visitor_email, visitor_phone_number) и разрешённые ключи, на которые ссылаются активные действия или которые они сохраняют. Внутренние и зарезервированные значения фильтруются; также действуют настройки и ограничения размера. У других интеграций есть собственные правила контекста. Пользовательский ключ customer_tier или customer_id не становится видимым модели автоматически только потому, что вы его отправили.

Действие может подставить {{metadata_<key>}} при формировании запроса, не прося AI сгенерировать значение. Это не делает обычные метаданные секретными: допустимое значение может отдельно попасть в контекст модели или появиться в ответе действия. Не храните API-ключи и пароли в пользовательских метаданных.

Метаданные из браузера не доказывают личность или права доступа. Получающий сервис должен аутентифицировать и авторизовать доступ к закрытым записям. Переданного браузером ID клиента или тарифа недостаточно. Проверяйте и сформированный запрос действия, и ответ агента для вашей конфигурации.

Получение метаданных

Права: 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()

Ответ 200 OK

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

Запись метаданных

Создайте или обновите метаданные разговора.

Права: write_all

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

Тело запроса

Параметр	Описание
metadata объект, обязательный	Метаданные для сохранения в виде пар ключ-значение

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()

Ответ 200 OK

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

---