Documentation d'intégration

Insertion d'accessoire

Intégrez le widget de service client à votre site Web avec un seul morceau de code.

Obtenir le code d'intégration

Connectez-vous au back-office → Paramètres de canal → Code d'intégration, copiez le code d'intégration dédié :

<script>
  window.$aicrs = window.$aicrs || { q: [] };
</script>
<script async src="https://votre-domaine-support.com/widget/loader.js" data-wk="VOTRE_WIDGET_KEY"></script>

Collez ce code avant la balise </body> de chaque page de votre site Web. Le widget s'affichera sous forme d'une bulle de chat dans le coin inférieur droit de la page, les visiteurs peuvent cliquer pour commencer à consulter.

Liste blanche des domaines

Pour empêcher le vol du widget, celui-ci n'est actif que sur les domaines que vous avez enregistrés. Ajoutez le domaine de votre site Web (plusieurs sont pris en charge) dans le back-office → Paramètres de canal → Liste blanche des domaines. Les domaines non enregistrés ne chargeront pas le widget, sans affecter votre page.

Réinitialisation du widget_key

En cas de doute sur la fuite du key, vous pouvez le réinitialiser dans les paramètres de canal. Une fois réinitialisé, l'ancien key devient immédiatement invalide, et vous devrez mettre à jour en conséquence le code d'intégration sur votre site Web.

Questions fréquemment posées

• Le widget ne s'affiche pas ? Vérifiez si le domaine actuel est dans la liste blanche, si le widget_key correspond à celui du back-office, et si le compte est dans la période de service.
• Est-ce que cela affecte la vitesse de votre site Web ? Le chargeur est inférieur à 1KO et est chargé de manière asynchrone, sans bloquer le rendu de votre page.

identifier l'adhésion au membre

Une fois que les visiteurs se connectent à votre site Web, appelez la méthode identify avec les informations du membre. Le système de service client attribuera la session de ce navigateur à ce membre. L'agent pourra ainsi voir directement l'identité du membre, et les accès depuis plusieurs appareils seront fusionnés en un même visiteur.

Méthode d'appel

Appelez la méthode après avoir déterminé que l'utilisateur est connecté sur votre page :

$aicrs.identify({
  externalId: 'U10086',      // Obligatoire, identifiant unique de l'utilisateur dans votre système
  name: 'Madame Li',             // Facultatif, nom affiché
  phone: '138****0000',      // Facultatif
  email: 'user@example.com', // Facultatif
  hash: 'Signature HMAC calculée côté serveur',  // Obligatoire, anti-usurpation
  custom: { vip: 'gold' }     // Facultatif, champs supplémentaires visibles côté agent
})

Algorithme de signature

La hash doit être calculée côté serveur de votre système (le widget_secret ne doit pas apparaître dans le code côté client) :

hash = hexadécimale minuscule de HMAC-SHA256(widget_secret, externalId)

Le widget_secret se trouve dans le tableau de bord marchand → Paramètres du canal → Code d'intégration, et est réinitialisé en même temps que le widget_key.

Exemple en Node.js :

const crypto = require('crypto')
const hash = crypto.createHmac('sha256', WIDGET_SECRET).update(externalId).digest('hex')

Résultat de la vérification

Les visiteurs dont la signature est vérifiée afficheront un marqueur "Vérifié" côté agent ; si la vérification échoue, l'appel à identify est ignoré et l'identité reste anonyme, sans erreur ni interruption de votre page.

Push d'événements Webhook

Lorsqu’un événement clé de l’activité se produit, le système envoie un message au format JSON vers l’URL de rappel (callback) configuré, ce qui vous permet de synchroniser facilement les données de service client dans votre propre système.

Configuration

Paramètres de l’entreprise → Webhook : renseignez l’URL de rappel (doit être HTTPS) et la clé de signature secret, sélectionnez les types d’événements à souscrire. Après enregistrement, vous pouvez cliquer sur "Envoyer un événement de test" pour effectuer un test immédiat.

Format de la requête

Chaque notification est envoyée sous la forme d’une requête POST :

POST votre URL de rappel
Content-Type: application/json
X-AICRS-Event: type d’événement
X-AICRS-Signature: HMAC-SHA256(secret, corps de la requête) en minuscules hexadécimales

Structure du corps de la requête :

{
  "event": "message.created",
  "tenant_id": 129,
  "timestamp": 1784500000,
  "data": { "objet snapshot": "..." }
}

Types d’événements

Vérification de signature et réessais

Lors de la réception d’une notification, calculez HMAC-SHA256 à l’aide de la clé secret sur le corps de la requête originale, et comparez-le avec X-AICRS-Signature. Si les deux ne correspondent pas, le message doit être ignoré.

Une réponse de votre interface avec un code 2xx est considérée comme une réussite ; en cas d’échec, la requête sera réessayée avec un délai de 1 minute / 5 minutes / 15 minutes, pour un maximum de 3 tentatives. Si l’échec persiste, l’état sera marqué comme échoué. Vous pourrez consulter la raison de l’échec dans l'historique des notifications du tableau de bord et effectuer un dépannage manuel.

API ouverte

API ouvert permettant de lire les données de service client depuis votre système, de créer des tickets et de les isoler selon le commerçant.

Authentification

Compte commerçant → Données et système pour générer une clé API (commençant par ak_, le texte clair n'est affiché qu'une seule fois au moment de la génération, veuillez le conserver soigneusement ; une fois réinitialisée, l'ancienne clé devient immédiatement invalide).

Toutes les requêtes doivent inclure l'en-tête de requête suivant :

Authorization: Bearer ak_YourKey

Limitation de débit

Chaque clé peut effectuer un maximum de 120 requêtes par 60 secondes, au-delà, la réponse est 429.

Liste des interfaces

Exemple :

curl -H "Authorization: Bearer ak_xxx" \
  "https://votre-domaine-service-client/api/open/v1/conversations?page=1"

Remarques

• Toutes les réponses sont au format JSON, les interfaces de liste prennent en charge le paramètre de pagination page.
• La version actuelle ne permet pas d'envoyer des messages aux visiteurs via l'API.
• L'API est suspendue en même temps que l'arrêt du compte ou l'expiration du service.

Correspondance des codes d'erreur

Toutes les réponses d'erreur d'interface sont unifiées en structure JSON :

{ "code": "code d'erreur", "message": "message en chinois" }

Correspondance entre le code d'état HTTP et le code :

Recommandations :

• 401/403 : Vérifiez si la clé est valide et l'état du service du compte.
• 429 : Réessayez plus tard conformément à Retry-After ou à la stratégie d'évitement.
• 5xx : Pour les interfaces idempotentes, le réessai est sécurisé ; pour les opérations non idempotentes, veuillez vérifier d'abord avant de réessayer.

CRM Interface Ouverte

Les opérations de lecture et d'écriture des données clients et opportunités se font via l'API ouverte (/api/open/v1, Bearer ak_ clé, générée dans le tableau de bord du commerçant "Données et système → API").

Clients

Les règles de déduplication sont identiques à celles du tableau de bord : external_id > numéro de téléphone > email, si une correspondance est trouvée, le client est rattaché à l'enregistrement existant au lieu d'en créer un nouveau.

Limitation de fréquence : 120 appels par clé toutes les 60 secondes, au-delà, une réponse 429 est retournée.

Push d'événements client

Les événements du cycle de vie client passent par le canal Webhook existant (abonnement dans le tableau de bord du commerçant "Données et système → Webhook"), avec la signature et le mécanisme de reprise identiques à ceux des événements de message (X-AICRS-Signature HMAC-SHA256, reprise avec retrait exponentiel).

Format de la charge utile : {"event":"customer.created","data":{...objet client...},"ts":1690000000}. Une réponse 2xx confirme la réception ; toute réponse non 2xx ou un dépassement de temps entraînera une reprise selon la stratégie de retrait.