Référence API

Cette page couvre l’API REST côté serveur utilisée pour uploader votre catalogue et votre contenu, et pour récupérer les résumés de conversation. Pour l’intégration frontend, voir la Référence SDK et les docs composants React / Vue.

L’endpoint de recherche storefront (POST /public/search/lexical, appelé avec la clé publique) ne fait pas partie de cette API : voir Installer Search sur une storefront headless.

Authentification

Ajoutez votre clé API privée Dialog dans le header Authorization sur chaque requête.

Authorization: MY_PRIVATE_KEY

Votre clé privée est visible dans le dashboard Dialog après création d’une organisation API Integration. Gardez-la côté serveur : elle ne doit pas être shippée dans le navigateur.

Résumés de conversation

Cette API est désactivée par défaut. Contactez Dialog pour activer les demandes de résumé depuis votre intégration widget. Une fois la génération demandée, votre serveur peut récupérer le résumé par sessionId avec la clé API privée de la même organisation Dialog.

GET https://api.askdialog.ai/integrations/conversation-summaries/{sessionId}
Authorization: MY_PRIVATE_KEY

La réponse dépend de l’avancement :

HTTP/1.1 202 Accepted
Cache-Control: no-store

{"status":"pending"}

HTTP/1.1 200 OK
Cache-Control: no-store

{"status":"ready","summary":"Résumé de 4 000 caractères maximum."}

Interrogez à nouveau l’endpoint tant que le statut est pending. Aucun intervalle de réessai n’est imposé. Une session inconnue renvoie 404 ; un échec de génération renvoie 409. La session doit appartenir à l’organisation identifiée par votre clé privée.

Upload URLs

Dialog utilise des URLs S3 pré-signées pour les uploads catalogue et contenu.

Récupérer les upload URLs

POST https://rtbzcxkmwj.execute-api.eu-west-1.amazonaws.com/organization/catalog-upload-url

Réponse :

{
  "catalogUploadUrl": {
    "url": "your-upload-url",
    "fields": {
      "bucket": "dialog-bucket-name",
      "X-Amz-Algorithm": "",
      "key": "fileKey",
      "Policy": "",
      "X-Amz-Credential": "",
      "X-Amz-Date": "",
      "X-Amz-Signature": "",
      "X-Amz-Security-Token": ""
    }
  },
  "pageUploadUrl": { /* même format */ },
  "blogPostUploadUrl": { /* même format */ }
}

Pour chaque fichier, utilisez l’URL et les fields pour uploader vers le bucket S3 de Dialog. Voir AWS S3 pre-signed URL docs pour le flow complet.

Uploads

Upload catalogue

Uploadez un fichier JSON qui respecte le schéma catalogue. Voir Schéma du catalogue pour le JSON Schema complet.

Upload blog

Si votre site a un blog, uploadez un array de { title, content } :

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "content": { "type": "string" }
    },
    "required": ["title", "content"]
  }
}

Upload pages

Pour les FAQ, infos livraison et autres pages statiques, uploadez un array de { title, content } (même schéma que le blog).

Troubleshooting

Status	Cause probable	Solution
401	Header d’auth manquant	Ajouter `Authorization: YOUR_KEY`
403	Clé invalide ou expirée	Régénérer la clé dans le dashboard
400	Payload non conforme	Valider contre le schéma
500	Erreur serveur	Écrire au support avec l’ID de requête

Suite

Schéma du catalogue : format JSON exact de l’upload catalogue.
Référence SDK : intégration frontend.