Skava Skava / Wiki

Connexion d’éléments personnalisés pour les développeurs

Cette page s’adresse aux développeurs qui connectent le backend d’une entreprise à Skava. La création et la publication d’un élément API sont décrites dans Éléments personnalisés : interfaces API ; ici, nous détaillons tout ce qui doit se passer de l’autre côté de la ligne.

L’idée en une phrase : Skava ne connaît pas votre domaine. Il ne connaît qu’un seul format, la carte. Vous décidez de son contenu, nous ne vérifions que la forme, la taille et la sécurité. Une commande de matériaux en est un exemple ; la société suivante collecte les retours des utilisateurs, celle d’après archive une photo de chantier dans ses propres dossiers.

Le processus en un coup d’œil

  1. Un administrateur d’entreprise crée un élément API dans Skava : un formulaire ainsi que l’adresse, la méthode et le jeton de votre backend.
  2. Quelqu’un dans le chat remplit le formulaire et l’envoie.
  3. Skava appelle votre backend et envoie les valeurs remplies au format JSON.
  4. Votre réponse devient la carte dans le chat.
  5. Facultativement, vous signalez de nouveaux états plus tard via le callback. Chaque signalement devient une autre carte ; la précédente reste visible.

Exigences pour votre backend

  • HTTPS. Uniquement https://, pas de http, pas d'identifiants dans l'adresse, au maximum 2000 caractères.
  • Accessible publiquement. L'hôte doit résoudre exclusivement vers des IP publiques. Localhost, réseaux privés, link-local et métadonnées cloud sont rejetés, et cela est vérifié à chaque appel.
  • Adresse fixe. Skava résout l'hôte une seule fois et fixe la connexion à cette IP. Un changement de DNS en cours d'appel n'a aucun effet.
  • Pas de redirections. Un 301 vers l'adresse « correcte » compte comme un échec. Saisissez l'adresse finale directement.
  • Temps de réponse. Le délai d'attente est configurable par élément et plafonné à 30 secondes. Si vous avez besoin de plus de temps, répondez immédiatement et signalez le résultat plus tard via le callback.
  • Taille de la réponse. Skava lit au maximum 256 Ko.
  • Content-Type. Le corps est uniquement analysé avec application/json.

La requête qui vous parvient

La méthode est GET, POST, PUT ou PATCH, selon l'élément. Avec POST, PUT et PATCH, les valeurs arrivent dans un corps JSON, avec GET en paramètres de requête.

L'authentification est un seul en-tête dont le nom et le préfixe de la valeur sont configurés dans l'élément, généralement Authorization avec le préfixe Bearer . Le jeton est stocké chiffré de notre côté. Les en-têtes host, content-length, content-type, cookie et accept-encoding ne peuvent pas être définis.

Le corps est un objet plat. Les clés sont choisies par celui qui a créé l'élément ; l'imbrication n'apparaît que là où un tableau ou un sélecteur de produit a été ajouté :

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Trois clés proviennent toujours de notre côté, ne les utilisez donc pas vous-même :

  • locale : le code de langue de l'utilisateur. Répondez dans cette langue ; nous ne traduisons pas vos textes.
  • callback_url et callback_token : le rappel pour cette interaction unique, voir ci-dessous. Ils ne sont présents que lorsque l'appel provient d'un chat.

Les champs de contexte tels que le nom, l'entreprise, le projet ou le sous-chat sont remplis par le serveur lui-même, dérivés du canal dans lequel l'élément a été exécuté. Un client modifié ne peut pas y revendiquer un autre nom de projet.

La réponse : le format carte

Répondez avec 2xx et un objet card. C'est exactement ce qui devient la carte dans le chat :

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

  • v (obligatoire) : l'entier 1. En texte ("1"), il est rejeté. Sans cela, la réponse ne compte pas comme une carte et la correspondance de réponse configurée dans l'élément s'applique.
  • title : le titre de la carte.
  • state : uniquement la couleur et le ton de l'icône, l'une des valeurs ok, pending, warn, error. Une valeur inconnue revient à ok et vous recevez un indice.
  • status_text : texte libre que nous n'interprétons pas. Il s'affiche en haut de la carte et apparaît également dans la liste des discussions et dans une notification push.
  • fields : une liste de label et value. Au maximum 20 entrées, label 80 caractères, value 200, title et status_text 120 chacun. Les valeurs trop longues sont abrégées, non rejetées : une commande ne doit pas échouer à cause d'un détail.
  • icon : voir ci-dessous.

Ce que Skava fait à vos textes avant qu'ils n'atteignent la discussion : les sauts de ligne et les caractères de contrôle sont supprimés (un caractère de droite à gauche pourrait sinon inverser l'affichage d'un montant), les backticks sont remplacés, et tout ce qui commence par [SKAVA: est neutralisé. La dernière règle empêche une valeur de carte d'être interprétée comme un autre élément de discussion, par exemple une demande de paiement.

Les liens dans les champs, le HTML et les images ne peuvent pas être définis. Une discussion est un environnement de confiance, et une adresse cliquable provenant d'un backend externe serait une invitation à reconstruire une page de connexion.

Les saisies de l'utilisateur appartiennent au serveur : elles figurent sur la première carte et vous ne pouvez pas les écraser. Dans le chat, elles constituent l'enregistrement de ce qui a réellement été soumis.

Icônes

Avec icon, la carte obtient son propre marque dans l'en-tête. Deux possibilités :

Un nom issu du jeu inclus : package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Ou votre propre SVG sous forme de chaîne. Skava n'en retient que la géométrie (path, circle, ellipse, rect, line, polyline, polygon avec leurs attributs numériques) pour construire sa propre image. Les scripts, styles, références externes, foreignObject et attributs d'événements sont écartés ; une déclaration de type de document ou une entité entraîne un rejet ; le fichier ne doit pas dépasser 8 Ko et contenir au plus 16 formes. La couleur, l'épaisseur du trait et la taille sont définies par Skava, si bien qu'une icône ne peut pas se faire passer pour un contrôle. Travaillez sur une grille de 24 par 24.

Sans icon, le marqueur par défaut reste.

Le rappel : signalement des états ultérieurs

L'appel contient callback_url et callback_token. Utilisez-les pour signaler de nouveaux états plus tard :

POST <callback_url> avec Authorization: Bearer <callback_token> et Content-Type: application/json, corps de 32 Ko maximum :

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

En plus de la carte, il y a trois valeurs facultatives :

  • seq : votre propre compteur. Un rapport avec une valeur inférieure ou égale est ignoré afin que deux rapports ne se dépassent pas. Sans seq, le dernier arrivé l'emporte.
  • final : clôture l'interaction. Le jeton devient invalide et aucune autre carte n'apparaît. Autorisé également dans la première réponse, pour les flux sans suite.
  • notify : définissez false pour publier la carte en silence, sans compteur de non-lus et sans notification. Pour les étapes intermédiaires qui ne doivent réveiller personne. Sans cela, la carte est un message parfaitement normal.

Chaque rapport devient sa propre carte dans le chat, la précédente reste. Cela permet de savoir quel état a été signalé. D'où une recommandation : n'envoyer que ce qui a changé. Une carte qui répète le numéro de commande, les articles et le total pour la quatrième fois n'est que du bruit pour le lecteur.

Deux limites : le même rapport deux fois ne produit pas une seconde carte, et une interaction peut publier au maximum 50 cartes. Une interaction accepte les rapports pendant 90 jours.

Réponses auxquelles vous devez réagir

  • 200 avec {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Lisez les indices : ils indiquent ce qui a été raccourci ou supprimé.
  • 401 : jeton ou identifiant d'interaction incorrect. Ne réessayez pas.
  • 410 : interaction fermée ou expirée. Ne réessayez pas.
  • 422 : carte inutilisable, avec hints comme raison. Corrigez d'abord.
  • 400 JSON invalide, 413 trop volumineux, 429 trop de requêtes (réessayer avec un délai d'attente), 500 erreur de notre côté, réessayer plus tard.

Exemple 1 : une commande avec un historique de statut

Étape 1, la requête vers votre backend :

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Étape 2, votre réponse immédiate :

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

La conversation affiche désormais une carte avec une icône de colis, le statut et les saisies de l'utilisateur.

Étape 3, plus tard lors de la sélection :

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Une seconde carte discrète sans champs : seul le statut a changé.

Étape 4, à l'expédition :

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Cette carte peut très bien réveiller quelqu'un, d'où l'absence de notify: false.

Étape 5, à la livraison :

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

Avec final, l'interaction est clôturée et le jeton ne fonctionne plus.

Exemple 2 : une action sans suites

Tous les flux n'ont pas d'historique. Un élément avec un seul champ qui transmet des données à votre système n'a besoin que d'une seule réponse :

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

final: true est important ici : sinon, l'interaction resterait ouverte pendant 90 jours avec un jeton valide, même si vous ne reportez plus rien.

Sélecteur de produits du catalogue

Une fois que l'entreprise a téléversé son catalogue d'articles, l'élément peut contenir le bloc sélecteur de produits. L'utilisateur assemble un panier à partir de celui-ci, et vous le recevez sous forme de liste, sous la clé choisie par la personne qui a créé l'élément :

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Comme la clé est libre, recherchez la première liste ayant cette structure plutôt qu'un nom fixe. Avant l'envoi, Skava vérifie que chaque référence existe bien dans le catalogue de cette entreprise, avec un maximum de 50 articles. Dans la carte, les articles s'affichent en liste avec image du produit, nom et quantité.

Tests

  • Ping dans l'éditeur d'élément envoie un HEAD brut, sans jeton ni données. Répondez avec n'importe quoi ; toute réponse HTTP compte comme accessible.
  • Requête de test déclenche un appel réel avec des valeurs d'exemple, même si l'élément est encore en brouillon, et affiche la requête, la réponse et les messages du validateur de carte.
  • Aperçu dans l'onglet adjacent : collez votre réponse JSON, vérifiez, et vous verrez la carte finale ainsi que les indices. Elle est contrôlée côté serveur avec le même code que celui utilisé en production.
  • Serveur d'exemple : un fournisseur d'exemple complet fonctionne sur api.skava.io et utilise tout ce qui est décrit ci-dessus. Son code source se trouve dans le dépôt sous example_order_server/, environ 600 lignes de bibliothèque standard pure, conçu pour être copié.

Ce qu'il faut savoir en plus

  • La carte est un message de chat parfaitement normal. Elle apparaît dans la recherche, peut être citée et reste dans l'historique.
  • Elle est envoyée par l'expéditeur système, et non par un compte de votre entreprise. Elle s'affiche toujours du côté de la personne qui a exécuté l'élément, et le titre indique quel système rédige le message.
  • L’entité définit qui peut l’exécuter : uniquement les membres de l’entreprise, ou aussi des externes qui partagent un chat avec elle. Lorsque votre entreprise quitte le chat, l’autorisation prend fin automatiquement.
  • Un élément API dont le jeton a expiré est inactif : les applications actuelles le masquent dans le menu, et tout appel envoyé quand même est rejeté côté serveur. Un administrateur peut y stocker un nouveau jeton, ce qui fonctionne également sur une interface publiée.

Lié

Création et publication : Éléments personnalisés : interfaces API. Documents remplissables au lieu d’interfaces : Éléments personnalisés : documents.