Метадані розмови

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

• Передавання через API: додавайте метадані до будь-якої розмови програмно через ці ендпоїнти (наприклад, із CRM, служби підтримки чи бекенду)
• Передавання через віджет/Embed: передавайте метадані як параметри ініціалізації під час завантаження віджета або додавайте їх динамічно під час розмови через JavaScript SDK
• Відображення в панелі керування: власні метадані показуються в деталях розмови у Вхідних. Внутрішні ключі відфільтровуються, а зібрані контактні дані й пам’ять дій відображаються окремо
• Включення в експорт: метадані входять до експорту розмов із панелі керування, тож їх можна аналізувати офлайн
• Використання в діях AI: значення метаданих можна підставляти як {{metadata_<key>}} у дії AI. Повний перелік доступних змінних наведено в розділі Змінні дій AI
• Доступність AI-агенту за наявності дозволу: контекст моделі використовує відфільтровану частину метаданих. Збереження ключа не гарантує, що модель отримає чи згадає його

Використовуйте метадані для ідентифікаторів клієнтів, контексту облікового запису, аналітики й вхідних даних дій. Зберігання, відображення у Вхідних, підстановка в діях і контекст моделі є окремими способами використання тих самих даних.

Якщо в панелі керування налаштовано JSON-схему, метадані перевіряються за нею.

Необов’язкові перевірки прикладів

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

• Перевірка умов запуску дії. Оцініть умови за наданими тестовими метаданими без виконання дії.

У сумісному браузері ці перевірки також доступні як інструменти сайту. Посилання відкривають звичайні форми.

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

У каналах, якими керує відвідувач, як-от віджет сайту й Embed, до контексту моделі допускаються контактні ключі відвідувача (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 object, обов’язковий	Метадані у форматі ключ-значення для збереження

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

---