Référence de l’API du widget externe

URL de base

L’API du widget est servie par votre site Salesforce sous le chemin /services/apexrest/redaai/chat/v1/ :

https://<your-org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1/

L’hôte exact dépend du domaine de votre site. Retrouvez-le dans Configuration › Sites. Le chargeur intégré à votre site web utilise cette adresse dans l’attribut data-endpoint.

Authentification

Chaque requête nécessite une clé API. Transmettez-la dans un en-tête HTTP ou dans le corps de la requête ; l’API accepte ces deux emplacements :

Le passage de la clé dans le corps offre une solution de remplacement lorsque les en-têtes personnalisés ne parviennent pas au service à travers l’infrastructure du site ou un proxy. Utilisez le format prévu par le chargeur fourni ou par votre client.

Après /init, chaque requête nécessite également le jeton de session renvoyé par /init :

Consultez Gestion des clés API pour créer, remplacer et révoquer les clés.

CORS

L’API ajoute l’en-tête Access-Control-Allow-Origin à ses réponses aux clients web. Le champ Origines autorisées de l’agent contient une liste d’origines séparées par des virgules. Vide, il ne restreint pas les origines ; renseigné, il entraîne le rejet d’une initialisation provenant d’une origine absente de la liste avec ORIGIN_NOT_ALLOWED.

Changement dans la version 1.13. L’origine provient de l’en-tête Origin de la requête, et non du corps. Une requête sans en-tête Origin est rejetée si Origines autorisées est renseigné. Ce contrôle vise les appels des navigateurs ; il ne constitue pas une authentification d’un serveur. Consultez POST /chat/v1/init.

Points de terminaison

Cinq points de terminaison, tous en POST. Pour un client interorigine personnalisé, vérifiez aussi le traitement des requêtes préalables OPTIONS par votre configuration Salesforce Sites et votre infrastructure.

POST /chat/v1/init

Valide la clé API, vérifie l’origine et crée une session. Renvoie le jeton et les informations de l’agent nécessaires à l’écran d’accueil du widget.

Corps de la requête

{
  "clientKey": "<your api key>"
}

Changement dans la version 1.13. Le service lit désormais l’en-tête Origin défini par le navigateur, qu’un script de page ne peut pas remplacer. Un champ origin dans le corps reste accepté pour compatibilité mais est ignoré. Un ancien widget qui le transmet peut continuer à fonctionner. Un client serveur peut construire ses propres en-têtes : ce contrôle ne remplace donc pas une authentification serveur.

Une requête serveur qui n’envoie pas d’en-tête Origin est rejetée avec ORIGIN_NOT_ALLOWED si la liste des origines autorisées est renseignée. Pour une intégration depuis votre serveur, examinez les contrôles d’accès adaptés ; laisser cette liste vide supprime la restriction d’origine. Consultez Configurer les origines autorisées.

Réponse (200 OK)

{
  "sessionToken":     "<opaque session token>",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "https://…/mascot.png",
  "maxMessageLength": 2000
}

• sessionToken : à transmettre dans toutes les requêtes suivantes.
• agentName : identifiant de l’agent, utile pour vos analyses côté client.
• displayName : nom lisible à afficher dans l’en-tête et l’accueil du widget.
• welcomeMessage : message de bienvenue externe configuré sur l’agent ; chaîne vide s’il n’est pas renseigné.
• mascotImage : URL de la mascotte si elle est configurée ; chaîne vide sinon.
• maxMessageLength : nombre maximal de caractères d’un message utilisateur.

POST /chat/v1/message

Transmet un message à l’agent et renvoie sa réponse à la fin du traitement de ce tour.

Corps de la requête

{
  "clientKey":    "<your api key>",
  "sessionToken": "<from /init>",
  "message":      "What's open on the Acme account?"
}

Un message dépassant maxMessageLength, renvoyé par /init, est rejeté avec INVALID_INPUT.

Réponse (200 OK)

{
  "response":            "<agent reply text>",
  "creditsUsed":         1.42,
  "conversationId":      "a0Q…",
  "pendingActions":      [],
  "continuationPending": true,
  "continuationDepth":   0
}

• response : réponse de l’agent, y compris les éventuels marqueurs SUGGESTIONS ou ACTION interprétés par le widget.
• creditsUsed : crédits consommés pour ce tour.
• conversationId : identifiant Salesforce de la conversation, permettant de retrouver sa transcription dans Salesforce.
• pendingActions : champ de résultat lié aux actions en attente de confirmation. Le widget externe n’utilise pas les cartes de confirmation internes ; traitez un résultat vide ou nul sans afficher de carte. Consultez Référence de l’API du widget externe ci-dessous.
• continuationPending vaut true lorsque des actions ont été exécutées et que l’agent doit encore en décrire le résultat. Appelez /chat/v1/continue pour obtenir ce compte rendu.
• continuationDepth : nombre de tours de continuation déjà effectués. Renvoyez cette valeur dans le prochain appel /continue.

POST /chat/v1/action

Exécute un outil d’action demandé par le client. Le service vérifie l’existence de l’outil actif et son admissibilité au canal du widget externe ; votre intégration doit respecter la configuration des outils de l’agent.

Corps de la requête

{
  "clientKey":    "<your api key>",
  "sessionToken": "<from /init>",
  "actionTool":   "create_record",
  "params": {
    "object_name":  "Case",
    "field_values": { "Subject": "Issue with login", "…": "…" }
  }
}

Réponse (200 OK)

{
  "success": true,
  "result":  "<tool execution result, JSON-serialised>"
}

La structure de result dépend de l’outil. Les outils d’action intégrés peuvent renvoyer un résultat structuré comportant success, message et, lorsque cela s’applique, recordId.

POST /chat/v1/continue

Demande à l’agent de décrire le résultat des actions exécutées lors du tour /message précédent, sans nouveau message utilisateur. Appelez ce point de terminaison si la réponse indique continuationPending: true.

Corps de la requête

{
  "clientKey":         "<your api key>",
  "sessionToken":      "<from /init>",
  "continuationDepth": 0
}

Réponse (200 OK)

{
  "response":            "<agent narration of what happened>",
  "creditsUsed":         0.68,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   1
}

Le champ continuationPending reste à true si l’agent a enchaîné une nouvelle action. Continuez à appeler /continue en retransmettant continuationDepth jusqu’à recevoir false, en traitant aussi les erreurs. Le paramètre Profondeur max. de continuation encadre cet enchaînement ; votre client doit respecter la profondeur renvoyée.

POST /chat/v1/history

Renvoie jusqu’à 100 messages de la conversation, du plus ancien au plus récent, par exemple pour réafficher l’échange après le rechargement du widget.

Corps de la requête

{
  "clientKey":    "<your api key>",
  "sessionToken": "<from /init>"
}

Réponse (200 OK)

{
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "2026-04-25T08:55:12.000Z" },
    { "role": "assistant", "content": "…", "timestamp": "2026-04-25T08:55:14.000Z" }
  ]
}

Réponses d’erreur

Les erreurs utilisent la structure suivante :

{
  "error": "<localised user-facing message>",
  "code":  "<machine-readable code>"
}

Utilisez code pour le traitement programmatique et affichez error à l’utilisateur.

Limites de débit

Les appels concernés passent par plusieurs contrôles. Les limites de débit et de messages sont définies par agent ; le plafond quotidien de crédits concerne l’ensemble des agents externes de l’organisation. Un bot très sollicité peut donc atteindre le plafond utilisé par tous les autres. La valeur 0 désactive ce plafond : évaluez ce choix avant de l’utiliser pour un widget public. Le budget global de licence reste applicable.

Consultez la Référence des paramètres de la plateforme pour les plafonds quotidiens.

Cycle de vie d’une session

• Création : /init crée une session pour l’agent et conserve l’adresse IP et l’origine reçues. Leur conservation ne signifie pas qu’elles sont revérifiées comme facteurs d’authentification à chaque appel.
• Activité : les réponses réussies de /message actualisent la dernière activité ; la continuation le fait également. Ne comptez pas sur /action ou /history pour prolonger le délai d’inactivité.
• Expiration : une session inactive expire selon le Délai d'expiration de la session (minute, dont la valeur de secours est 30 minutes. Un jeton expiré entraîne SESSION_EXPIRED ; le widget doit rappeler /init.
• Limite de messages : lorsque Messages de session maximum est atteint, les nouveaux messages soumis à ce contrôle sont rejetés avec MAX_MESSAGES. Créez une nouvelle session pour démarrer une nouvelle conversation.

Configuration requise sur l’agent

Plusieurs champs de la définition d’agent déterminent le comportement du widget :

Modèle de sécurité

• Contexte de l’utilisateur invité. Le widget public utilise le contexte invité du site Salesforce. Les chemins standard appliquent les contrôles prévus pour ce contexte ; vérifiez les droits d’objet et de champ, le partage et la sécurité des outils personnalisés avant l’exposition publique.
• Une clé par agent. Chaque agent externe possède sa propre clé. Sa génération ou sa révocation concerne cet agent.
• Une restriction d’origine pour les navigateurs. Renseignez Origines autorisées sur les agents publics afin de limiter l’utilisation depuis d’autres sites. Ce contrôle ne remplace pas une authentification serveur et une valeur vide le désactive.
• Des erreurs génériques pour les clients. Les détails internes sont destinés au journal d’incidents et à l’examen par les administrateurs.
• Un plafond quotidien commun aux bots externes. Il permet de limiter leur consommation collective. Il ne réserve pas de crédits et s’ajoute au budget global de licence.

Bonnes pratiques

Utilisez le chargeur fourni lorsque son fonctionnement vous convient. Il prend en charge le chargement des versions, les formats d’authentification, les erreurs et les attributs décrits dans Personnaliser l’interface du widget. Un client personnalisé doit gérer explicitement ces aspects.

Basez votre traitement sur code. Le texte error est destiné aux utilisateurs, peut être traduit et évoluer selon les versions. Le champ code sert au traitement programmatique.

Recréez une session pour SESSION_EXPIRED, pas pour toute erreur. Attendez avant de réessayer après RATE_LIMITED. Une erreur CREDIT_LIMIT nécessite de vérifier le budget ou les plafonds avec un administrateur.

Configurez les origines des agents publics. Laisser la liste vide retire ce niveau de protection des appels de navigateur.

Surveillez le plafond quotidien. Ajustez-le après observation du trafic et de la consommation réels.

Changements inclus dans 1.16000

La limite horaire par agent s’applique aussi pendant la dernière heure UTC de la journée. Les API externe et Communauté utilisent un code stable de limite de crédits pour que la réponse HTTP 429 ne dépende plus du message traduit.

Liste de mise à niveau client

Questions fréquentes

Étapes suivantes

Consultez Gestion des clés API pour les clés, ou la Référence de l’API Experience Cloud pour le portail authentifié.