Référence de l’API Experience Cloud

Différences avec l’API du widget externe

L’API Experience Cloud et l’API du widget externe répondent à des usages et à des modèles de sécurité différents :

Utilisez cette API pour un chatbot accessible après connexion à un portail Salesforce Experience Cloud. Pour un site web public, utilisez l’API du widget externe.

URL de base

L’API est servie par votre site Experience Cloud sous le chemin /services/apexrest/redaai/chat/community/v1/ :

https://<your-community>.my.site.com/<site-path>/services/apexrest/redaai/chat/community/v1/

L’hôte exact dépend de votre configuration Experience Cloud. Les appels du composant fourni utilisent le contexte de l’utilisateur connecté au portail.

Authentification

Aucune clé API de widget n’est nécessaire. Le service vérifie l’identité Salesforce de l’appelant, déterminée par son contexte d’authentification. Deux conséquences :

• Un appel exécuté comme utilisateur invité non authentifié est rejeté avec AUTH_REQUIRED.
• Un client doit disposer d’un contexte Salesforce authentifié approprié ; la seule connaissance de l’adresse du portail ne donne aucun accès.

Pour une intégration personnalisée, utilisez un mécanisme d’authentification Salesforce pris en charge. Ne supposez pas qu’un cookie de session sera transmis ou accepté dans n’importe quel contexte interorigine.

Points de terminaison

Six points de terminaison, tous en POST :

POST /chat/community/v1/init

Recherche l’agent et reprend la conversation la plus récente de cet utilisateur avec lui, si elle se trouve dans la fenêtre de reprise configurée. Sinon, crée une conversation.

Corps de la requête

{
  "agentName": "support-assistant"
}

Réponse (200 OK)

{
  "conversationId":   "a0Q…",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "https://…/mascot.png",
  "maxMessageLength": 2000,
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "…" },
    { "role": "assistant", "content": "…", "timestamp": "…" }
  ]
}

Si le tableau messages n’est pas vide, la conversation a été reprise. Affichez les échanges renvoyés pour assurer la continuité. L’historique est limité aux 100 premiers messages dans l’ordre de séquence ; une conversation plus longue n’est donc pas renvoyée intégralement. Un tableau vide indique qu’aucun historique n’est renvoyé.

Fenêtre de reprise

La reprise utilise le délai d’expiration configuré sur la définition d’agent : Session_Timeout_Minutes__c, en minutes, avec une valeur de secours de 30. La plateforme recherche la dernière conversation de l’utilisateur avec cet agent et vérifie si sa dernière activité se situe dans cette fenêtre.

POST /chat/community/v1/new

Crée une conversation même si une conversation récente existe. Ce point de terminaison convient à un bouton « Recommencer ».

Corps de la requête

{
  "agentName": "support-assistant"
}

Réponse (200 OK)

{
  "conversationId":   "a0Q…",
  "agentName":        "support-assistant",
  "displayName":      "Support Assistant",
  "welcomeMessage":   "Hi! How can I help today?",
  "mascotImage":      "…",
  "maxMessageLength": 2000,
  "messages": []
}

Le tableau messages est vide : la nouvelle conversation ne possède pas encore d’historique.

POST /chat/community/v1/message

Transmet un message utilisateur à l’agent et renvoie sa réponse.

Corps de la requête

{
  "conversationId": "<from /init or /new>",
  "message":        "What's open on my case 00012345?"
}

La plateforme vérifie que la conversation appartient à l’utilisateur appelant. L’accès à la conversation d’un autre utilisateur est rejeté.

Réponse (200 OK)

{
  "response":            "<agent reply text>",
  "creditsUsed":         1.42,
  "conversationId":      "a0Q…",
  "continuationPending": false,
  "continuationDepth":   0
}

Votre client doit traiter le champ continuationPending. Lorsque l’agent a exécuté des actions dont il doit encore décrire le résultat, ce champ vaut true. Appelez /continue pour obtenir cette explication. Ignorer ce champ peut laisser l’utilisateur sans compte rendu de l’action effectuée.

POST /chat/community/v1/action

Exécute une action confirmée. Le service vérifie l’outil demandé et son admissibilité au canal Communauté ; votre intégration doit également respecter la configuration des outils de l’agent.

Corps de la requête

{
  "conversationId": "<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>"
}

POST /chat/community/v1/continue

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

Corps de la requête

{
  "conversationId":    "a0Q…",
  "continuationDepth": 0
}

Renvoyez la valeur continuationDepth reçue dans la réponse précédente. Si elle est omise, le service utilise 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 pendant son compte rendu. Continuez à appeler /continue en retransmettant la valeur continuationDepth jusqu’à recevoir false, en traitant aussi les erreurs. Le paramètre Profondeur max. de continuation limite l’enchaînement. Votre client doit respecter la profondeur renvoyée.

POST /chat/community/v1/history

Renvoie jusqu’à 100 messages de la conversation appartenant à l’utilisateur actif du portail, dans l’ordre de séquence croissant, par exemple pour réafficher l’échange après le rechargement de la page. Si la conversation est plus longue, cet appel ne fournit pas un historique complet.

Corps de la requête

{
  "conversationId": "a0Q…"
}

Réponse (200 OK)

{
  "messages": [
    { "role": "user",      "content": "…", "timestamp": "…" },
    { "role": "assistant", "content": "…", "timestamp": "…" }
  ]
}

Réponses d’erreur

Même structure que pour l’API du widget externe :

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

Limites de débit

Les contrôles sont similaires à ceux du widget externe, avec deux différences :

• Le contrôle de débit du portail est appelé avec l’identifiant de l’utilisateur, au lieu du jeton de session opaque du widget.
• Le plafond quotidien utilise le paramètre Bot communautaire - Plafond de crédits quotidien, distinct du plafond du widget externe.

Pour supprimer ce plafond quotidien, laissez Bot communautaire - Plafond de crédits quotidien vide ou réglez-le sur 0. Les plafonds du portail et du widget externe sont distincts, mais leur consommation utilise le même budget de licence.

Propriété des conversations

La conversation appartient à l’utilisateur qui l’a créée. Le service vérifie cette propriété lors des appels /message, /action et /history. Une valeur conversationId appartenant à un autre utilisateur est rejetée avec INVALID_INPUT. Le même contrôle s’applique à la continuation.

Ce contrôle s’ajoute aux autorisations Salesforce. L’absence de clé API de widget ne signifie donc pas que les conversations sont publiques.

Le contact de l’utilisateur du portail fournit le contexte initial. Les utilisateurs Experience Cloud peuvent être liés à un contact via User.ContactId. Lors de /init ou /new, REDA AI recherche ce contact et l’associe à la conversation comme enregistrement de contexte. Les champs de contexte configurés et accessibles peuvent alors aider l’agent à comprendre la demande, sans que le client transmette lui-même l’identité du contact.

Si l’utilisateur ne possède pas de contact associé, la conversation peut être créée sans cet enregistrement de contexte.

Configuration requise sur l’agent

Modèle de sécurité

• L’authentification repose sur Salesforce. Aucune clé API de widget n’est à créer ou à renouveler. L’appel utilise le contexte de l’utilisateur connecté.
• Les autorisations de l’utilisateur s’appliquent aux chemins standard du package. Le profil, les ensembles d’autorisations et les règles de partage déterminent les droits sur les objets, champs et enregistrements. Examinez séparément les contrôles appliqués par vos outils personnalisés.
• La propriété de la conversation est vérifiée. Connaître l’identifiant d’une conversation ne suffit pas pour accéder à celle d’un autre utilisateur.
• Les restrictions de canal des outils s’appliquent. Seuls les outils d’action admissibles au canal Communauté peuvent être utilisés ici.
• Le plafond quotidien limite la consommation du portail. Configurez-le en tenant compte du budget global de licence ; il ne réserve pas de crédits exclusivement aux utilisateurs du portail.
• Les erreurs exposées restent génériques. Les détails internes sont destinés au journal d’incidents pour l’examen par un administrateur.

Bonnes pratiques

Utilisez le composant de portail fourni. Le composant Lightning pour Experience Cloud gère les appels, la reprise des conversations et l’affichage. Un client personnalisé nécessite de prendre en charge explicitement l’authentification et le cycle de conversation.

Reprenez les conversations plutôt que de les recréer. Appelez /init à l’ouverture pour reprendre une conversation récente lorsque cela est possible. Réservez /new à une action explicite de l’utilisateur, comme « Recommencer ».

Choisissez un délai d’expiration adapté. Un délai trop court empêche la reprise entre les pages ; un délai trop long peut reprendre un échange devenu obsolète. Trente minutes constituent la valeur de secours documentée.

Surveillez le plafond quotidien du portail. Il est indépendant du plafond du widget externe et peut être adapté à votre volume d’utilisateurs authentifiés, dans la limite du budget global de licence.

Vérifiez les canaux des outils. Un outil d’action limité à Interne ne peut pas être utilisé depuis le portail simplement parce qu’il est associé à l’agent.

Revoir la continuité des conversations

Fenêtre de conversation (heures) vide utilise désormais le réglage de l’organisation, initialement 30 minutes. Une valeur positive fixe la fenêtre de l’agent ; 0 désactive la reprise automatique. La correspondance dépend du canal : API utilise agent et enregistrement ; Interne/MCP authentifié utilise agent, utilisateur et contexte d’enregistrement pertinent. Communauté utilise le réglage partagé plutôt que le délai de session externe. Le chat des pages d’accueil, d’application et de la barre d’utilitaires peut reprendre une conversation éligible. Les identifiants explicites restent soumis aux contrôles de leur route. Utilisez 0 si vous comptiez sur une valeur vide pour démarrer une nouvelle conversation. Les autorisations empaquetées corrigent aussi l’accès Interne et Communauté.

Questions fréquentes

Étapes suivantes

Consultez Configurer un agent pour un portail Experience Cloud pour le déploiement, ou la Référence de l’API du widget externe pour le canal public.