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 sur la page Éléments personnalisés : interfaces API ; ici, nous couvrons tout ce qui doit se passer à l'autre bout 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 vérifions uniquement la forme, la taille et la sécurité. Une commande de matériaux est un exemple ; la société suivante recueille les retours des utilisateurs, celle d'après archive une photo de chantier dans ses propres registres.

Le flux 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. Une personne 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. Optionnellement, vous signalez de nouveaux états plus tard via le callback. Chaque signalement devient une autre carte ; la précédente reste affichée.

Exigences pour votre backend

• HTTPS. Uniquement https://, pas de http, pas d'identifiants dans l'adresse, au maximum 2000 caractères.
• Accessibles publiquement. L'hôte doit résoudre exclusivement vers des IP publiques. Les adresses localhost, les réseaux privés, les adresses link-local et les métadonnées cloud sont rejetées, et cette vérification est effectuée à chaque appel.
• Adresse fixe. Skava résout l'hôte une seule fois et verrouille la connexion sur cette IP. Un changement DNS en cours d'appel n'a aucun effet.
• Aucune redirection. Une redirection 301 vers l'adresse « correcte » est comptée comme une erreur. Entrez l'adresse finale immédiatement.
• Délai 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 rappel.
• 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, tandis qu'avec GET, elles sont transmises sous forme de paramètres de requête.

L'authentification est un seul en-tête dont le nom et le préfixe de valeur sont configurés dans l'élément, généralement Authorization avec le préfixe Bearer . Le jeton est stocké de manière chiffrée 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 construit l'élément ; l'imbrication n'apparaît que là où ils ont ajouté un tableau ou un sélecteur de produit :

{"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 nous proviennent toujours, 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 name, company, project ou subchat sont remplis par le serveur lui-même, dérivés du canal dans lequel l'élément a été exécuté. Un client falsifié ne peut pas revendiquer un nom de projet différent.

La réponse : le format de la carte

Répondez par 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. Sous forme de texte ("1"), il est rejeté. Sans lui, la réponse ne compte pas comme une carte et la mappage de réponse configuré dans l'élément s'applique.
• title : le titre de la carte.
• state : couleur et ton de l'icône uniquement, l'un des ok, pending, warn, error. Une valeur inconnue revient à ok et vous recevez un avertissement.
• status_text : texte libre que nous n'interprétons pas. Il se situe en haut de la carte et c'est aussi ce qui s'affiche dans la liste des chats 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 tronquées, pas 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 le chat : les sauts de ligne et les caractères de contrôle sont supprimés (un caractère de droite à gauche pourrait autrement inverser l'affichage d'un montant), les accents graves sont remplacés, et tout ce qui commence par [SKAVA: est désactivé. Le dernier point empêche qu'une valeur de carte soit interprétée comme un autre élément de chat, par exemple une demande de paiement.

Les liens dans les champs, le HTML et les images ne peuvent pas être définis. Un chat est un environnement de confiance, et une adresse cliquable provenant d'un backend tiers serait une invitation à recréer une page de connexion.

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

Icônes

Avec icon, la carte obtient sa propre marque dans l'en-tête. Deux méthodes :

Un nom du jeu intégré : 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 en extrait uniquement la géométrie (path, circle, ellipse, rect, line, polyline, polygon avec leurs attributs numériques) et construit sa propre image. Les scripts, les styles, les références externes, foreignObject et les attributs d'événement sont ignorés ; une déclaration de type de document ou une entité entraîne un rejet ; le fichier ne peut dépasser 8 Ko et contenir au maximum 16 formes. La couleur, l'épaisseur du trait et la taille sont définies par Skava, donc une icône ne peut pas se faire passer pour un contrôle. Travaillez sur une grille de 24 par 24.

Sans icon, la marque par défaut reste.

Le rappel : signalement d'états ultérieurs

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

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

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

Outre la carte, il existe trois valeurs facultatives :

• seq : votre propre compteur. Un signalement avec une valeur inférieure ou égale est rejeté afin qu'aucun signalement ne puisse en dépasser un autre. Sans seq, le dernier arrivé l'emporte.
• final : met fin à 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 suivi.
• notify : défini sur 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, le précédent reste. Ainsi, on sait quel état a été signalé. Cela implique 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 envoyé 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-la d'abord.
• 400 JSON invalide, 413 trop volumineux, 429 trop de requêtes (réessayez avec un délai progressif), 500 notre erreur, réessayez plus tard.

Exemple 1 : une commande avec un historique des statuts

É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"}]}}

Le chat affiche maintenant une carte avec une icône de colis, le statut et les saisies de l'utilisateur.

Étape 3, plus tard lors de la préparation :

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 deuxième carte silencieuse sans champ : seul l'état a changé.

Étape 4, lors de 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 réveiller quelqu'un, donc pas de notify: false.

Étape 5, lors de 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 fermée et le jeton ne fonctionne plus.

Exemple 2 : une action sans suivi

Tous les flux n'ont pas d'historique. Un élément avec un seul champ qui transmet quelque chose à 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 rapporterez plus rien.

Sélecteur de produits du catalogue

Une fois que l'entreprise a téléchargé son catalogue d'articles, l'élément peut contenir le bloc sélecteur de produits. L'utilisateur compose un panier à partir de celui-ci, et vous le recevez sous forme de liste avec la clé choisie par celui 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 forme plutôt qu'un nom fixe. Avant l'envoi, Skava vérifie que chaque numéro existe bien dans le catalogue de cette entreprise, jusqu'à 50 articles maximum. Dans la carte, les articles apparaissent sous forme de liste avec l'image du produit, le nom et la quantité.

Tests

• Ping dans l'éditeur d'éléments envoie un HEAD brut sans jeton ni données. Répondez par n'importe quoi ; toute réponse HTTP compte comme accessible.
• Test de requête déclenche un appel réel avec des valeurs d'exemple, même si l'élément est encore un 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 terminée ainsi que les indices. Elle est vérifiée sur le serveur avec le même code qu'en production.
• Exemple de serveur : un fournisseur d'exemples 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, destinées à être copiées.

Ce qu'il faut savoir en plus

• La carte est un message de chat parfaitement normal. Elle s'affiche dans les résultats de recherche, peut être citée et reste dans l'historique.
• Elle est envoyée par l'expéditeur du système, et non par un compte de votre entreprise. Elle apparaît néanmoins du côté de la personne qui a exécuté l'élément, et le système qui l'a écrite est indiqué dans le titre.
• Qui peut l'exécuter est défini sur l'élément : uniquement les membres de l'entreprise, ou également des personnes extérieures partageant 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 et n'apparaît même pas dans le menu tant qu'un administrateur n'en a pas enregistré un nouveau.

Liés

Création et publication : Éléments personnalisés : interfaces API. Documents remplissables plutôt qu'interfaces : Éléments personnalisés : documents.