Conversation Metadata

Conversation Metadata vous permet d’attacher des données clé-valeur personnalisées aux conversations, créant un pont puissant entre vos systèmes et votre AI Agent. Les métadonnées circulent dans l’ensemble de votre workflow Quickchat :

• Alimentation via l’API — Utilisez ces endpoints pour attacher par programmation des métadonnées à n’importe quelle conversation (p. ex. depuis votre CRM, votre helpdesk ou votre backend)
• Alimentation via le widget/embed — Passez des métadonnées comme paramètres d’initialisation lors du chargement du widget, ou injectez-les dynamiquement pendant une conversation active à l’aide du SDK JavaScript
• Visibles dans le Dashboard : les métadonnées personnalisées apparaissent dans les détails de la conversation dans la Boîte de réception. Les clés internes sont filtrées, et les coordonnées collectées ainsi que la mémoire des Actions ont leur propre présentation
• Incluses dans les exports — Les métadonnées sont incluses lorsque vous exportez des conversations depuis le Dashboard, ce qui les rend disponibles pour une analyse hors ligne
• Utilisées dans les AI Actions — Les valeurs de métadonnées peuvent être injectées directement comme marqueurs {{metadata_<key>}} dans les AI Actions. Consultez AI Action Variables pour la référence complète des marqueurs disponibles
• Disponibles pour l’AI Agent lorsque cela est autorisé : le contexte du modèle utilise un sous-ensemble filtré des métadonnées. Le stockage d’une clé ne garantit pas que le modèle la recevra ou la mentionnera

Utilisez les métadonnées pour les références client, le contexte du compte, l’analyse et les données d’entrée des Actions. Le stockage, l’affichage dans la Boîte de réception, la substitution dans les Actions et le contexte du modèle sont des utilisations distinctes des mêmes données.

Les métadonnées sont validées par rapport à un JSON schema si l’un est configuré dans le Dashboard.

Contexte du modèle et autorisation

Sur les canaux contrôlés par le visiteur, tels que le Widget et l’Embed du site web, le contexte du modèle accepte les clés de contact du visiteur (visitor_name, visitor_email, visitor_phone_number) et les clés admissibles référencées ou collectées par les Actions actives. Les valeurs internes et réservées sont filtrées ; des restrictions de configuration et de taille s’appliquent également. Les autres intégrations suivent des règles de contexte propres à chaque canal. Une clé personnalisée customer_tier ou customer_id n’est pas automatiquement visible pour le modèle du seul fait que vous l’avez envoyée.

Une Action peut remplacer {{metadata_<key>}} par sa valeur lors de la construction de sa requête sans demander à l’IA de générer cette valeur. Cela ne rend pas les métadonnées ordinaires secrètes : une valeur admissible peut, séparément, entrer dans le contexte du modèle ou apparaître dans la réponse d’une Action. Ne stockez pas de clés API ni de mots de passe dans les métadonnées personnalisées.

Les métadonnées fournies par le navigateur ne constituent pas une preuve d’identité ou d’autorisation. Votre service destinataire doit authentifier et autoriser l’accès aux données privées ; un identifiant client ou un niveau d’abonnement envoyé par un navigateur ne suffit pas. Testez à la fois la requête produite par l’Action et la réponse de l’Agent pour votre configuration.

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

Créez ou mettez à jour les métadonnées d’une conversation.

Scope: write_all

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

Request Body

Parameter	Description
metadata object, required	Métadonnées clé-valeur à stocker

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

---