Vizir

# Utiliser l'API Vizir

Il faut toujours demander l'autorisation avant de se servir...

Toutes les requĂȘtes prĂ©sentĂ©es ici doivent comporter un en-tĂȘte d'autorisation :

Authorization: Bearer [your_bearer_token]

your_bearer_token peut ĂȘtre rĂ©cupĂ©rĂ© en naviguant sur le dashboard, et en observant dans les outils dĂ©veloppeurs l'onglet Network pour intercepter une requĂȘte qui comporte ce fameux token.

# Exporter/Importer un chatbot

# Export

Route : https://developers.vizir.co/chatbots/<chatbotId>/export

(☝ ça, c'est dans le cas oĂč vous voulez exporter un bot depuis la prod. Si vous voulez exporter depuis la staging, la base de l'url sera https://staging.vizir.co/...)

  • MĂ©thode Ă  utiliser : POST

  • Exemple de corps (JSON) Ă  utiliser :

{
  "bundles": ["content", "conversation"],
  "models": ["Workflow"],
  "excludedModels": ["Message"],
  "dryRun": true
}
  • Description des paramĂštres
    • bundles: les bundles permettent d'exporter un ensemble de modĂšles liĂ©s Ă  un domaine : "content" (CompĂ©tences, Resources, ...), "conversation" (RĂ©pondants, Messages, ...), "automation" (Workflows, Actions, ...), "nlu" (EntitĂ©s, Intentions, ...), "test" et "misc" (Applicationmodification et Applicationurl)
    • models: liste de modĂšles spĂ©cifiques Ă  importer (peut ĂȘtre utilisĂ© en combinaison avec le champ bundles)
    • excludedModels: liste des modĂšles Ă  exclure de l'export
    • dryRun : permet de "tester" un export, c'est-Ă -dire d'extraire les modĂšles et gĂ©nĂ©rer l'archive mais sans uploader cette derniĂšre vers l'espace de stockage en ligne

⚠ Au moins un des champs bundles et models doit ĂȘtre dĂ©fini.

  • Valeur de retour :
{
  "summary": {},
  "exportId": "abcde123/chatbots/xyz.tgz"
}

summary présente un compte rendu de l'export, en donnant, par modÚle, le nombre de documents exportés et la taille du/des fichiers correspondants.

exportId est la valeur qui devra ĂȘtre utilisĂ©e au moment d'importer les donnĂ©es.

⚠ les modĂšles Workflowhistory et Actionhistory sont exclus par dĂ©faut de leur bundle correspondant "automation", donc si vous souhaitez les exporter, il faut les inclure dans models

â„č les modĂšles Chatbot, Application et Environnement sont exportĂ©s par dĂ©faut.

â„č les donnĂ©es Elastic Search sont exportĂ©s automatiquement si les modĂšles Features et Resources font partie de l'export.

# Import

Route : https://staging.vizir.co/chatbots/import

(☝ en supposant que vous voulez importer sur la staging, sinon il faudra modifier la base de l'url selon vos besoins)

  • MĂ©thode Ă  utiliser : POST

  • Exemple de corps (JSON) Ă  utiliser :

{
  "exportId": "abcde123/chatbots/xyz.tgz",
  "dryRun": true
}
  • Description des paramĂštres
    • exportId: Identifiant de l'archive de l'export Ă  importer, obtenu lors de l'appel Ă  /export (cf. plus haut)
    • isUpdate: "true" ou "false". Si "true", ignore les erreurs en provenance de la BDD lors de la tentative d'insertion de documents dĂ©jĂ  prĂ©sents. Utile pour enrichir l'import d'un bot dĂ©jĂ  effectuĂ© partiellement plus tĂŽt.

A chaque serrure sa clé

Le Bearer token sera diffĂ©rent pour l'import et l'export (puisque ce n'est pas le mĂȘme serveur et donc pas la mĂȘme base de donnĂ©es qui est concernĂ© pour ces deux Ă©tapes).

# Extraire des répondants avec leurs attributs

Pour extraire la liste des répondants et leurs attributs sur une plage de dates et un environnement donnés.

# RequĂȘte

URL : https://developers.vizir.co/chatbots/<chatbotID>/environments/<environmentID>/respondents/with-attrs/? attributes=<attribut_1>,attribut_2>,...&start=<date_début>&end=<date_fin>

# Autenthification

Afin d'accĂ©der Ă  cette route API, vous devez disposer d'un "Bearer token" ayant les droits en lecture sur ce bot et l'affecter Ă  l'en-tĂȘte Authorization. Ex: Authorization: Bearer 1234abcd

# ParamĂštres d'URL

  • chatbotID : l'ID du chatbot concernĂ©
  • environmentID : l'ID de l'environnement des rĂ©pondants Ă  rĂ©cupĂ©rer
  • attributes : liste des attributs des rĂ©pondants Ă  rĂ©cupĂ©rer, sĂ©parĂ©s par des virgules. Par ex: email,device_type,current_year
  • start et end : dĂ©finisse la pĂ©riode sur laquelle extraire les donnĂ©es, c'est-Ă -dire que ne seront extraits que les nouveaux rĂ©pondants sur la pĂ©riode donnĂ©e. La chaĂźne de caractĂšres utilisĂ©e doit ĂȘtre au format ISO 8601 (et attention, Ă  moins que vous ne spĂ©cifiez le dĂ©calage correspondant Ă  votre fuseau horaire, la date et l'heure sont ceux de l'UTC) Remarque : "start" est obligatoire, mais "end" est facultatif. Si vous omettez ce dernier, alors la date de fin sera le moment oĂč vous effectuez la requĂȘte.

Exemple de requĂȘte : https://developers.vizir.co/chatbots/60940f730910aa0011a0e824/environments/60940f730910aa0011a0e834/respondents/with-attrs/?attributes=email,device_type&start=2021-01-01T00:00:00&end=2022-01-25T23:59:59

# RĂ©ponse

La rĂ©ponse renvoyĂ©e est au format CSV ayant pour colonne : respondentID, environmentID, createdAt (date de crĂ©ation du rĂ©pondant) et tous les attributs spĂ©cifiĂ©s en paramĂštres. (Cette rĂ©ponse peut ĂȘtre enregistrĂ©e dans un fichier ".csv")

Exemple de réponse :

respondentID,realEnvID,createdAt,source,current_month,device_type
Dandelionrobin Storm,602e3f7abe4c0c6a5b50a8c3,2022-01-25T09:24:34.314Z,web,janvier,desktop
Platinumelf Rider,602e3f7abe4c0c6a5b50a8c3,2022-01-19T09:59:42.055Z,web,janvier,desktop
Malachitehugger Bat,602e3f7abe4c0c6a5b50a8c3,2022-01-19T09:56:38.849Z,web,janvier,desktop
Keenmare Glazer,602e3f7abe4c0c6a5b50a8c3,2022-01-10T10:25:15.453Z,web,janvier,desktop

← Monitoring →