Conversation Metadata

Conversation Metadata pozwala dołączać niestandardowe dane klucz-wartość do rozmów, tworząc potężny pomost między Twoimi systemami a Twoim AI Agentem. Metadane przepływają przez cały Twój workflow w Quickchat:

• Zasilanie przez API — Użyj tych endpointów, aby programistycznie dołączyć metadane do dowolnej rozmowy (np. z Twojego CRM, helpdesku lub backendu)
• Zasilanie przez widget/embed — Przekaż metadane jako parametry inicjalizacji podczas ładowania widgetu lub wstrzyknij je dynamicznie w trakcie aktywnej rozmowy za pomocą JavaScript SDK
• Widoczne w Dashboardzie: niestandardowe metadane pojawiają się w szczegółach rozmowy w Skrzynce odbiorczej. Klucze wewnętrzne są odfiltrowywane, a zebrane dane kontaktowe i pamięć Akcji mają osobny sposób prezentacji
• Uwzględniane w eksportach — Metadane są uwzględniane przy eksporcie rozmów z Dashboardu, dzięki czemu są dostępne do analizy offline
• Używane w AI Actions — Wartości metadanych mogą być wstrzykiwane bezpośrednio jako placeholdery {{metadata_<key>}} do AI Actions. Pełną dokumentację dostępnych placeholderów znajdziesz w AI Action Variables
• Dostępne dla AI Agenta, gdy jest to dozwolone: kontekst modelu korzysta z przefiltrowanego podzbioru metadanych. Zapisanie klucza nie gwarantuje, że model go otrzyma lub o nim wspomni

Korzystaj z metadanych do przechowywania identyfikatorów klientów, kontekstu konta, danych analitycznych i danych wejściowych dla Akcji. Przechowywanie, wyświetlanie w Skrzynce odbiorczej, podstawianie w Akcjach i kontekst modelu to odrębne zastosowania tych samych danych.

Metadane są walidowane względem schematu JSON, jeśli taki jest skonfigurowany w Dashboardzie.

Kontekst modelu i autoryzacja

Na kanałach kontrolowanych przez odwiedzającego, takich jak Widget i Embed na stronie internetowej, do kontekstu modelu dopuszczane są klucze danych kontaktowych odwiedzającego (visitor_name, visitor_email, visitor_phone_number) oraz spełniające warunki klucze, do których odwołują się aktywne Akcje lub które są przez nie zbierane. Wartości wewnętrzne i zarezerwowane są odfiltrowywane; obowiązują też ograniczenia konfiguracji i rozmiaru. Inne integracje mają zasady dotyczące kontekstu właściwe dla danego kanału. Samo przesłanie niestandardowego klucza customer_tier lub customer_id nie sprawia, że model automatycznie go widzi.

Akcja może podstawić wartość {{metadata_<key>}} podczas tworzenia żądania, nie prosząc AI o wygenerowanie tej wartości. Nie oznacza to, że zwykłe metadane są tajne: wartość spełniająca warunki może niezależnie trafić do kontekstu modelu lub pojawić się w odpowiedzi Akcji. Nie przechowuj kluczy API ani haseł w niestandardowych metadanych.

Metadane dostarczone przez przeglądarkę nie są dowodem tożsamości ani uprawnień. Usługa odbierająca żądanie musi uwierzytelnić żądanie i autoryzować dostęp do prywatnych danych; identyfikator klienta lub poziom planu przesłany przez przeglądarkę nie wystarczy. Przetestuj zarówno wynikowe żądanie Akcji, jak i odpowiedź Agenta w swojej konfiguracji.

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

Utwórz lub zaktualizuj metadane dla rozmowy.

Scope: write_all

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

Request Body

Parameter	Description
metadata object, required	Metadane klucz-wartość do zapisania

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

---