Gespreksmetadata

Met gespreksmetadata koppel je aangepaste sleutel-waardegegevens aan gesprekken en maak je een krachtige verbinding tussen je systemen en je AI-agent. Metadata loopt door je volledige Quickchat-workflow:

• Aanleveren via API: gebruik deze endpoints om programmatisch metadata aan elk gesprek toe te voegen (bijvoorbeeld vanuit je CRM, helpdesk of backend)
• Aanleveren via widget of ingesloten chat: geef metadata mee als initialisatieparameters wanneer je de widget laadt, of voeg deze dynamisch toe tijdens een actief gesprek met de JavaScript SDK
• Zichtbaar in het dashboard: aangepaste metadata verschijnt bij de gespreksdetails in de Inbox. Interne sleutels worden gefilterd en verzamelde contactgegevens en actiegeheugen hebben een eigen weergave
• Opgenomen in exports: metadata wordt meegenomen wanneer je gesprekken uit het dashboard exporteert en is zo beschikbaar voor offline analyse
• Gebruikt in AI-acties: metadatawaarden kunnen rechtstreeks als tijdelijke aanduidingen {{metadata_<key>}} in AI-acties worden ingevoegd. Zie Variabelen voor AI-acties voor het volledige overzicht
• Beschikbaar voor de AI-agent wanneer toegestaan: de modelcontext gebruikt een gefilterde subset van metadata. Het opslaan van een sleutel garandeert niet dat het model deze ontvangt of noemt

Gebruik metadata voor klantreferenties, accountcontext, analyses en actie-inputs. Opslag, weergave in de Inbox, vervanging in acties en modelcontext zijn afzonderlijke toepassingen van dezelfde gegevens.

Metadata wordt gevalideerd tegen een JSON-schema als dat in het dashboard is ingesteld.

Optionele voorbeeldcontroles

• Bekijk een voorbeeld van metadatasleutels. Controleer hoe opgegeven veldnamen variabelesleutels worden, inclusief dubbele namen en fouten door gereserveerde sleutels. Dit controleert geen waarden of accountspecifieke rechten.

• Controleer uitvoeringsvoorwaarden voor acties. Beoordeel voorwaarden met opgegeven voorbeeldmetadata zonder een actie uit te voeren.

In een geschikte browser zijn deze controles ook beschikbaar als sitetools. De links openen de standaardformulieren.

Modelcontext en autorisatie

Op kanalen die bezoekers kunnen beïnvloeden, zoals de websitewidget en ingesloten chat, laat de modelcontext contactgegevens van bezoekers toe (visitor_name, visitor_email, visitor_phone_number) en geschikte sleutels waarnaar actieve acties verwijzen of die ze verzamelen. Interne en gereserveerde waarden worden gefilterd; ook configuratie- en groottelimieten gelden. Andere integraties hebben kanaalspecifieke contextregels. Een aangepaste sleutel customer_tier of customer_id is niet automatisch zichtbaar voor het model omdat je die hebt verstuurd.

Een actie kan {{metadata_<key>}} vervangen bij het opbouwen van de aanvraag zonder de AI te vragen die waarde te genereren. Dit maakt gewone metadata niet geheim: een geschikte waarde kan apart in de modelcontext terechtkomen of in een actierespons verschijnen. Sla geen API-sleutels of wachtwoorden op in aangepaste metadata.

Metadata uit de browser bewijst geen identiteit of toestemming. Je ontvangende service moet toegang tot privégegevens authenticeren en autoriseren; een klant-ID of abonnementsniveau uit een browser is niet voldoende. Test zowel de resulterende actieaanvraag als het antwoord van de agent voor jouw configuratie.

Metadata ophalen

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

Antwoord 200 OK

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

Metadata instellen

Maak metadata voor een gesprek aan of werk deze bij.

Bereik: write_all

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

Requestbody

Parameter	Beschrijving
metadata object, verplicht	Sleutel-waardemetadata om op te slaan

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

Antwoord 200 OK

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

---