API¶

Une automatisation sans connexion à votre Système d'Informations, des API, des bases de données... présentera certainement peu d'intérêt. Les ressources API vous permettent d'intégrer un chatbot avec vos propres API externes.

Ces APIs peuvent ensuite retourner des données brutes à traiter plus tard ou des workflows Prisme.ai directement exécutables.

La configuration de la ressource est pensée de sorte à permettre d'appeler le plus large panel possible d'APIs. Si jamais il vous manque une option particulière pour formatter correctement votre requête, merci de nous contacter ou passer par la ressource fonction afin d'écrire l'appel HTTP en Javascript brut.

L'appel de l'API décrite par votre ressource se fera ensuite par une action au sein de votre workflow.

Exemple d'utilisation :

Vous créez un Webhook "Météo" qui pour une ville vous donne la température, le vent et l'humidité.
Ensuite dès que vous avez besoin de la météo dans votre workflow, vous ajoutez une étape "Appeler un Webhook" et vous sélectionnez "Météo".

1. Création¶

A la création de votre API, seule son URL est demandée. Plus de paramètres apparaissent sur l'écran suivant :

Paramètres à injecter dans l'URL et dans le corps de la requête (sauf si un corps de requête est personnalisé)
Méthode HTTP GET, POST, PUT, ou DELETE. POST par défaut
Corps de la requête : corps de la requête personnalisé
En-têtes HTTP
Authentification basique: pour sécuriser votre appel avec un identifiant et un mot de passe
Filtre JSON : chemin JSON à extraire de la réponse

Les mêmes options seront disponibles lors de l'appel de l'API (détails plus bas).
C'est particulièrement utile pour certains champs qui nécessitent d'être écrits avec une valeur issue d'un dialogue d'usager

2. Contenu de la requête par défaut¶

Si vous ne personnalisez pas le corps de votre requête et que celle-ci n'est pas du GET, votre API recevra par défaut l'objet suivant :

interface request {
  timestamp: string; // DateTime de l'appel
  sessionId: string; // Identifiant de la session
  bot: {
    id: string; // Identifiant de l'assistant
  };
  user: { // Utilisateur courant
    id: string; // Identifiant de l'utilisateur
    location: string; // Localisation de l'utilisateur s'il l'a autorisé
    platform: string; // Plateforme de l'agent utilisateur
    conversationSize: number; // Nombre de messages de la conversation
    conversationId: string; // Identifiant de la conversation
  };
  userMessage: { // Message de l'utilisateur
    event: string; // Si le message de l'utilisateur est un évènement, son nom
    text: string; // Si c'est du texte, son contenu
    payload: {}; // Si le message contient un objet arbitraire, celui-ci
  }
  originalRequest: {}; // Objet de paramètres arbitraires passés au script d'injection
  lang: string; // Langue du navigateur de l'utilisateur
  query: string; // Requête envoyée par l'utilisateur
  event: string; // Évènement envoyé par l'utilisateur
  fulfillment: { // Réponses générée par le workflow avant d'arriver à la fonction
    stream: {
      type: string;
      resourceId: string;
    }[];
  intent: { // Intention correspondante à la requête de l'utilisateur
    name: string;
    confidence: number; // Indice de correspondance
    inputs: {}; // Valeur des paramètres de l'intention
  };
  contexts: { // Contextes
    lifespan: string; // Durée de vie
    required: boolean; // S'il est requis
    name: string; // Nom
    parameters: {}; // Paramètres associés
    scope: string; // Périmètre
  }[];
  endConversation: boolean; // Si la convesation est terminée
}

Exemple :

body: { "id": "",
   "timestamp": "2018-09-21T12:02:39+00:00",
   "sessionId": "BxopMtpjDl5Pfrc4",
   "user": { "platform": "web", "conversationSize": 1 },
   "lang": "fr",
   "query": "Je souhaite réserver trois chambres pour 4 personnes avec petit déjeuner",
   "endConversation": false,
    ...
   "status": { "code": 200, "errorType": "success" }
  }

3. Réponse¶

L'API peut retourner des données brutes ou un workflow Prisme.ai directement exécutable :

// Renvoit un bloc de données brutes
return [{"title": "Hello World"}];

// Renvoit un workflow à exécuter
return [
  {
    type: "text",
    text: "Hello World",
  },
  {
    type: "button",
    text: "Cliquez moi",
  },
];

Plus d'information sur la structure des workflows ici.