Vizir

# Connecteur API / Se connecter à une API

Vous avez plusieurs solutions pour connecter votre chatbot à une API. La plus simple est d'utiliser nos template de chatbot et nos connecteurs pré construits.

Pour gérer les connecteurs API, il faut se rendre dans les paramètres du chatbot et se connecter à votre application depuis cette interface.

Raccourci pour gagner du temps

Nous avons rédigé une documentation pour les cas d'usage les plus fréquents chez nos clients avec le plus souvent des templates de compétence qui vous feront gagner un temps précieux ⏳

Ensuite, une fois connecté, vous pouvez récupérer un "AuthId" qui vous permet de connecter le chatbot à l'API de votre choix.

Copier le auth Id

Puis il faut l'ajouter dans votre workflow comme ci-dessous: Ajouter le auth Id

👇👇👇

Pour bénéficier de cette nouvelle façon de gérer les intégrations api, recherchez simplement le nom de l'outil dans la liste des actions; puis recherchez dans le "path" l'action que vous souhaitez réaliser sur cet outil!

Renseignez comme auparavant les informations pour compléter l'action !!

# Créer son connecteur API

Pour créer un connecteur API beaucoup de chose vont dépendre de la méthode d'authentification de l'api.

# Authorization OAUTH2

Exemple pour Miscorosft Azure

# grantType: authorization_code

{
  "variables": [],
  "name": "Microsoft Azure public",
  "image": "https://logo.clearbit.com/azure.com",
  "auth": {
    "authorizationURL": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "tokenURL": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "authType": "OAUTH2",
    "grantType": "authorization_code",
  },
  "request": {
    "baseURL": "https://graph.microsoft.com/v1.0/",
    "headers": {
      "Accept": "application/json",
      "Authorization": "Bearer {{accessToken}}",
      "User-Agent": "Vizir"
    }
  },
  "website": "microsoft-teams.com"
}

grantType peut prendre 3 valeurs

  • client_credentials
  • authorization_code
  • password_credentials

Vous pouvez personnaliser les tokenParams et authorizationParams en fonction de l'application à laquelle vous souhaitez vous connecter.

Par exemple si vous devez ajouter le client_id dans les paramètres pour récupérer le token.

"tokenParams": {
  "client_id": "{{client_id}}"
}

Par exemple:

Vous pouvez ajouter dans la variable httpOptions toutes les options que vous souhaitez ajouter à la requête http. Par exemple si vous souhaitez ajouter un header dans les appels API pour récupérer le token vous pouvez ajouter

"auth": {
  "httpOptions": {
    "headers": {
      "api-secret": "<ValueOfYourSecret"
    }
  }
}

👇👇👇

Pour le moment l'usage nous montre que httpOptions est utilisé pour les headers. Si vous en avez besoin pour des queryParams ou des payload, merci de contacter notre support @it@vizir.co

# grantType: client_credentials

⚠️⚠️⚠️

Le click sur Connecter simule la connexion et ne valide pas la connexion. Pour la valider vous devez essayer une appel API via l'interface de test.

Voici un exemple avancé pour un type d'authorisation client_credentials

{
  "name": "Demo",
  "website": "demo.io",
  "auth": {
    "tokenURL": "https://api.demo.io/api/oauth/token",
    "grantType": "client_credentials",
    "tokenParams": { "user_id": "{{user_id}}" },
    "httpOptions": {
      "headers": {
        "x-ps-application": "bearer {{application_secret}}"
      }
    },
    "authType": "OAUTH2"
  },
  "request": {
    "baseURL": "https://api.demo.io/api",
    "headers": {
      "Accept": "application/json",
      "Authorization": "Bearer {{accessToken}}",
      "User-Agent": "Vizir",
      "x-ps-application": "bearer {{application_secret}}"
    }
  },
  "variables": [
    {
      "name": "application_secret",
      "type": "string",
      "description": "application_secret",
      "default_value": "",
      "required": true,
      "hidden": true
    },
    {
      "name": "user_id",
      "type": "string",
      "description": "user_id",
      "default_value": "",
      "required": true,
      "hidden": true
    }
  ],
  "image": "https://www.vizir.co/wp-content/uploads/2020/11/logo.svg"
}

Nous avons ajouté des paramètres en plus qui peuvent être demandés par certaines API (x-ps-application, user_id).

Dans notre exemple, x-ps-application est demandé dans la récupérer du token ET dans toutes les requêtes API au contraire de user_id qui n'est demandé que dans la récupération du token.

Pour simplifier la vie des utilisateurs, les définir en variables va permettre d'ouvrir une fenêtre pour que l'utilisateur les renseigne au click sur connecter

# grantType: password_credentials

👇👇👇

Nous n'avons pas encore implémenté le grantType: password_credentials.

si vous en avez besoin n'hésitez pas à en parlé avec votre chef de projet ou contacter directement notre support @it@vizir.co

# Options

options additional options to setup how the module perform requests

  • scopeSeparator Scope separator character. Some providers may require a different separator. Defaults to empty space
  • credentialsEncodingMode Setup how credentials are encoded when options.authorizationMode is header. Use loose if your provider doesn't conform the OAuth2 specification. Defaults to strict
  • bodyFormat - Request's body data format. Valid options are form or json. Defaults to form
  • authorizationMethod - Method used to send the client.id/client.secret authorization params at the token request. Valid options are header or body. If set to body, the bodyFormat option will be used to format the credentials. Defaults to header

# Authorization: OAUTH 1

Exemple pour Trello

{
  "variables": [],
  "name": "Trello",
  "website": "trello.com",
  "auth": {
    "requestTokenURL": "https://trello.com/1/OAuthGetRequestToken",
    "accessTokenURL": "https://trello.com/1/OAuthGetAccessToken",
    "userAuthorizationURL": "https://trello.com/1/OAuthAuthorizeToken",
    "authType": "OAUTH1",
    "signatureMethod": "HMAC-SHA1",
    "authorizationParams": { "expiration": "never" }
  },
  "request": {
    "baseURL": "https://api.trello.com/1/",
    "headers": {
      "Accept": "application/json",
      "User-Agent": "Vizir"
    },
    "queryParams": {
      "key": "{{consumerKey}}",
      "token": "{{accessToken}}"
    }
  },
  "image": "https://logo.clearbit.com/trello.com",
}

# Authorization: BASIC

Exemple pour Atlassian

{
  "variables": [
    {
      "name": "atlassian-domain",
      "type": "string",
      "required": true
    }
  ],
  "name": "atlassian",
  "website": "atlassian.com",
  "image": "https://seeklogo.com/images/A/atlassian-logo-DF2FCF6E4D-seeklogo.com.png",
  "auth": {
    "authType": "BASIC"
  },
  "request": {
    "baseURL": "https://{{atlassian-domain}}.atlassian.net/",
    "headers": {
      "Accept": "application/json",
      "Authorization": "Basic {{accessToken}}",
      "User-Agent": "Vizir"
    }
  }
}

# Authorization: CUSTOM

Exemple pour JSON placeholder api de test publique et gratuite

{
  "variables": [],
  "name": "JSONplaceholder",
  "website": "https://jsonplaceholder.typicode.com/",
  "auth": { "authType": "CUSTOM" },
  "request": {
    "baseURL": "https://jsonplaceholder.typicode.com/",
    "headers": { "User-Agent": "Vizir" }
  },
  "image": "https://thumbs.dreamstime.com/b/ligne-noire-ic%C3%B4ne-pour-la-d%C3%A9mo-d%C3%A9monstration-et-l-exposition-divers-logo-139882881.jpg"
}

Voici les principaux champs à renseigner:

  • name, website, image
  • request: informations de base pour les requêtes à l'api
  • auth: informations de base pour l'authentification de l'api pour Oauth1 et Oauth2
  • variables: informations qui seront demandées avant la connexion de l'utilisateur (si elles ne sont pas déjà définies dans les variables du chatbot)

# Créer la configuration qui est propre à votre compte

# Créer une configuration OAUTH2

  • Créez votre application sur l'outil de votre choix, récupérez le client_id et le client_secret.
  • Indiquez la redirect_uri ci dessous lorsqu'elle vous sera demandée.
    • redirect_uri: https://dashboard.vizir.co/authcallback
  • Ajoutez une nouvelle config dans l'interface (paramètres du chatbot) de vizir Voici un exemple de config

    TIP

    ⚠️ Renseignez le client_id, le client_secret et les scopes.

{
    "name": "Vizir - Staging",
    "authType": "OAUTH2",
    "scope": [],
    "client_id": "",
    "client_secret"
}

Pour aller plus loin et simplifier la vie des utilisateurs vous pouvez voir en fin de page le BONUS TEMPLATE

🔐

Les informations confidentielles seront stockées de manière sécurisées et chiffrées. Nous les chiffrons les clés avec un algorithme aes-256-gcm.

Les données sont stockées en France sur nos serveurs hébergés par OVH.

# Créer une configuration OAUTH 1

  • Créez votre application sur l'outil de votre choix, récupérez le consumerKey et le consumerSecret.
  • Indiquez la redirect_uri ci dessous si elle vous est demandée.
    • redirect_uri: https://dashboard.vizir.co/authcallback
    • Orgigines autorisées: https://dashboard.vizir.co
  • Ajoutez une nouvelle config dans l'interface (paramètres du chatbot) de vizir Voici un exemple de config

    TIP

    ⚠️ Renseignez le consumerSecret, le consumerKey.

{
    "name": "Vizir - Staging",
    "authType": "OAUTH1",
    "scope": [],
    "consumerSecret": "",
    "consumerKey"
}

# Créer une configuration BASIC

Dans le cas d'une authentification Basic, il nous sera nécessaire d'avoir le username et le password.

Il est possible comme dans l'exemple ci-dessous de gérer ce username et password ddans les variables de votre chatbot. Cela vous permettra de partager la configuration avec d'autres équipes sans divulger votre mot de passe.

{
    "name" : "Jira - Basic Auth",
    "authType" : "BASIC",
    "headers" : {
        "Authorization" : "Basic {{accessToken}}"
    },
    "password" : "{{jira-user-token}}",
    "username" : "{{jira-user-email}}",
    "authId" : {
        "defaultAuthIdVariable" : "atlassion-authId",
        "saveDefault" : false
    },
    "variables": [
        {
            "name": "jira-user-email",
            "type": "string",
            "required": true
        },
        {
            "name": "jira-api-token",
            "type": "string",
            "required": true,
            "hidden": true
        }
    ]
}

# CUSTOM

Voici un objet qui correspond à une configuration CUSTOM.

Le seul champ obligatoire est le authType: CUSTOM

{
    "name": "User Token Auth GLPI",
    "authType": "CUSTOM",
    "headers" : {
        "Authorization" : "user_token {{glpi-user-token}}",
        "App-Token" : "{{glpi-app-token}}"
    }
}

Vous pouvez ainsi définir les paramètres qui seront nécessaire à l'authentification:

  • headers(JSON)
  • queryParams (à renseigner sous forme de JSON, les paramètres seront passer en paramètre d'URL
  • payload (à renseigner sous forme de JSON également, ces infromations seront passées dans le body de la requête)

# Rendre des variables obligatoires

Lorsque l'utilisateur va cliquer sur connecter, une nouvelle fenêtre va s'ouvrir.

Dans cette fenêtre, vous pouvez afficher les variables que l'utilisateur n'a pas encore défini pour simplifier son expérience. Afficher les variables La définition des variables peut se faire au niveau de l'intégration OU au niveau de la configuration.

Pour le faire, il faut mettre à jour l'intégration API en rajoutant un champ variables

"variables": [
    {
      "name": "glpi_url",
      "type": "string",
      "description": "Url de votre instance GLPI",
      "default_value": "",
      "required": true
    },
    {
      "name": "glpi-app-token",
      "type": "string",
      "description": "app token",
      "default_value": "",
      "required": true,
      "hidden": true
    },
    {
      "name": "glpi-user-token",
      "type": "string",
      "description": "user token",
      "default_value": "",
      "required": true
    }
  ]

Nous obtenons ainsi une intégration comme ci-dessous (exemple donné pour GLPI):

{
  "variables": [
    {
      "name": "glpi_url",
      "type": "string",
      "description": "Url de votre instance GLPI",
      "default_value": "",
      "required": true
    },
    {
      "name": "glpi-app-token",
      "type": "string",
      "description": "app token",
      "default_value": "",
      "required": true,
      "hidden": true
    },
    {
      "name": "glpi-user-token",
      "type": "string",
      "description": "user token",
      "default_value": "",
      "required": true
    }
  ],
  "image": "https://glpi-project.org/wp-content/uploads/2017/03/logo-glpi-bleu-1.png",
  "name": "glpi",
  "auth": {
    "authorizationURL": "https://{{glpi_url}}/apirest.php/initSession",
    "authType": "BASIC"
  },
  "request": {
    "baseURL": "https://{{glpi_url}}/apirest.php",
    "headers": {
      "Accept": "application/json",
      "App-Token": "{{glpi-app-token}}",
      "User-Agent": "Vizir"
    },
    "queryParams": {
      "user_token": "{{glpi-user-token}}"
    }
  },
  "website": "https://glpi-project.org"
}

⚠️

Nous ne faisons aucune vérification après le login sur les outils qui n'utilise pas soit OAUTH1 ou OAUTH2. Il est donc possible que vous ayez un message de succès alors que l'une de vos variables est fausse. C'est pourquoi, nous vous conseillons de tester directement via l'interface de test le nouvel AuthId que vous avez une fois connecté.

# BONUS TEMPLATE

TIP

Vous souhaitez simplifier la vie de vos utilisateurs et créer un template ?

Il est possible dans la configuration de rajouter des paramètres pour que le authId se sauvegarde directement dans les variables du chatbot.

Ca permettra aux utilisateurs de ne jamais passer par l'onglet variables pour paramétrer leur chatbot.

Pour cela dans la configuration de votre application vous pouvez ajouter un champs comme ci-dessous:

"authId": {
    "saveDefault": true,
    "defaultAuthIdVariable": "github-authId"
}

Quand l'utilisateur va cliquer sur Se connecter, son id d'authentification sera automatiquement stocké dans la variable github-authId.

Donc voici à quoi pourrait ressemble une intégration avec github:

{
  "authId": {
    "saveDefault": true,
    "defaultAuthIdVariable": "github-authId"
  },
  "scope": [ "repo", "admin:org" ],
  "name": "Vizir - Staging",
  "authType": "OAUTH2",
  "__v": 1,
  "client_id": "2b08d9d27359xxxxxxxx"
}

TIP

Le authId est indispensable seulement dans les cas ou nous devons effectuer des manipulations pour récupérer un token à jours (OAUTH1 et OAUTH2).

Vous pouvez l'utilisez pour les authentifications BASIC et CUSTOM si vous souhitez vous connectez à différents comptes mais cela n'est pas nécessaire

# Exécuter du code javascript après un appel API

# Modifier les données de retour d'api avant de les intégrer dans le chatbot

A la création de votre action, vous pouvez activer l'option fonction javascript. Cette option vous permetttra de modifier les données récupérées de l'api pour les utiliser dans votre chatbot.

Prenons un exemple: Nous souhaitons récupérer les informations d'un fichier Excel.

L'api de google Sheet renvoie un objet JSON pas simple à utiliser sous forme de tableau.

Pour simplifier l'utilisation de cette intégration, nous avons créé une nouvelle action Google Sheet vLookUp. Cette action permet de trouver chercher dans une excel la ligne de notre choix et de renvoyer les données sous forme de json plus facilement utilisable dans le chatbot.

Pour cela dans un premier temps on utilise l'action pour récupérer des valeur de google.

Dans le cas d'un Excel comme ci-dessous, nous récupérerons les données ci-dessous. Tableau Google Sheet

{
  "range": "demo!A1:D1000",
  "majorDimension": "ROWS",
  "values": [
    [
      "Email",
      "Age",
      "Date de naissance",
      "Ville"
    ],
    [
      "john@doe.fr",
      "31",
      "14/05/1990",
      "Paris"
    ],
    [
      "leonardo.dicaprio@vizir.co",
      "52",
      "14/02/1954",
      "Los Angeles"
    ]
  ]
}

Dans notre cas nous souhaitons récupérer seulement les données de leonardo.dicaprio@vizir.co sous la forme de JSON

{
  "Email": "leonardo.dicaprio@vizir.co",
  "Age": "52",
  "Date de naissance": "14/02/1954",
  "Ville": "Los Angeles"
}

Pour cela, nous allons activer l'option fonction javascript dans notre nouvelle action.


let obj = {}
let vLookupIndex = data.values[0].findIndex(col => col == "{{vLookupColumn}}")
data.values[0].forEach((col, index) => {
  let value = data.values.find(line => line[vLookupIndex] == "{{vLookupValue}}");
  if (value) {
    obj[col] = value[index]
  } else {
    obj[col] = ""
  }
})
return obj;

Jira →