Getting started

Introduction

Golem.ai permet d'analyser vos messages, c'est-à-dire vos emails, vos fichiers, vos tickets, etc...

Cette analyse fonctionne sur des emails, incluant le texte et les pièces jointes (documents words, pdf, texte, ou images de texte...), mais aussi directement sur du texte brut (ticket) et des documents. Pour traiter ces données, l'IA de Golem.ai peut faire plusieurs choses selon vos besoins : déduire une catégorie, extraire des informations, générer un brouillon de réponse, mais aussi des intégrations fortes à vos systèmes.

Cette documentation est dédiée aux développeurs qui doivent intégrer Golem.ai dans leurs applications.

L'API fonctionne en deux étapes : vous créez une analyse, puis vous récupérez le résultat de l'analyse. Pour récupérer le résultat, vous pouvez soit utiliser les webhooks, soit faire une requête HTTP. Nous conseillons fortement l'utilisation des webhooks, qui nous permettent une meilleur résilience et d'envoyer les résultats dès que possible.

Vous retrouverez aussi sur ce site la documentation OpenAPI de l'API.

Prérequis

L'API de Golem.ai est sécurisée par un ensemble de clés API, et toutes vos requêtes API doivent être effectuées via HTTPS et authentifiées avec ces clés API.

Les clés API seront fournies par Golem.ai. Vous aurez deux valeurs : la Secret Key et l'App ID:

le App ID nous permet d'identifier facilement votre intégration et n'est pas une information sensible. Vous devez l'envoyer en tant que query parameter dans votre requête, avec le nom appId. Vos URLs se termineront donc par quelque chose comme ?appId=<YOUR_APP_ID>.
la Secret Key est le vrai token d'autorisation et constitue donc une donnée sensible. Vous devez simplement l'utiliser comme valeur de l'en-tête HTTP Authorization.

Toutes vos requêtes APIs seront effectués sur un environnement Golem.ai. Cet environnement contient la configuration réalisée par les équipes solutions de Golem.ai, et est identifié par un environment ID (également appelé envId). Vous pouvez le retrouver dans l'URL de votre environnement : https://console.golem.ai/project/<YOUR-PROJECT-ID>/environment/<YOUR-ENVIRONMENT-ID>/dashboard.

Création d'une analyse

Pour créer une analyse, vous devez utiliser l'endpoint /environment/{environmentId}/analyses. Cet endpoint supporte plusieurs formats de messages, nous avons donc fait des guides simplifiés pour les cas les plus courants.

📄️ Analyser un fichier EML

Comment analyser un fichier EML avec l'API v2 de Golem.ai

📄️ Analyser un ou plusieurs fichiers

Comment analyser un ou plusieurs fichiers avec l'API v2 de Golem.ai

📄️ Analyser du texte et/ou des pièces jointes

Comment analyser du texte et/ou des pièces jointes avec l'API v2 de Golem.ai

Ici, nous allons expliquer le fonctionnement général de la création d'une analyse.

Les entrées d'une analyse

Une analyse peut être composée d'un fichier ou d'un texte, ou de plusieurs fichiers et/ou textes.

Le cas général est d'avoir un fichier, généralement un EML. Les pièces jointes seront extraites et traitées, ainsi que le contenu du mail à l'intérieur du fichier EML. Mais vous pouvez aussi avoir plusieurs fichiers, où vous spécifiez explicitement lequel est le principal et lesquels sont les pièces jointes.

La description de ces entrées ce fait dans le tableau inputs du champ payload de la requête.

curl --request POST \
      --url https://api.console.golem.ai/environment/<YOUR-ENVIRONMENT-ID>/analyses?appId=<YOUR-APP-ID> \
      --header 'accept: application/json' \
      --header 'authorization: <YOUR-SECRET-KEY>' \
      --header 'content-type: multipart/form-data' \
      --form 'payload={"inputs": --> INSERT THE DATA DESCRIBING THE INPUTS HERE <--}'

Le format du tableau `inputs`

Le tableau inputs est un tableau d'objets, où chaque objet décrit une entrée.

Voici un exemple de tableau inputs :

[
  {
    "type": "BODY", // le type d'entrée, peut être "BODY", "ATTACHMENT", ou bien un autre type défini au préalable
    "contentType": "file", // le type de contenu de l'entrée, peut être "file" ou "text"
    "file_key": "file1" // le nom du champ dans le corps `multipart/form-data` où se trouve le fichier
    // "text": "Texte à analyser" // le texte à analyser, si le type de contenu est "text"
    // "name": "Nom de l'entrée" // le nom de l'entrée, optionnel, disponible si le type de contenu est "text"
  }
]

Ce tableau peu contenir plusieurs entrées, voici quelques règles pour bien comprendre son fonctionnement :

le type peut être BODY, ATTACHMENT, ou bien un autre type défini au préalable, par exemple SENDER dans le cas d'un ticket.
si l'entrée décrit un fichier EML (soit un email) et que le type est BODY, alors les pièces jointes seront extraites et traitées.
vous pouvez mixer des entrées de différents types dans le même tableau inputs, que ce soit sur le type ou le contentType.
si l'entrée est de contentType text, vous pouvez aussi spécifier un name pour l'entrée. Dans le cas d'un fichier, le nom du fichier sera utilisé comme nom de l'entrée.

Voici un exemple avec des entrées diverses. Ici, nous traitons un fichier EML, avec une pièce jointe supplémentaire, et un champs texte de type RECEIVER qui permet à l'IA de Golem.ai de connaître le destinataire:

[
  {
    "type": "BODY",
    "contentType": "file",
    "file_key": "file1" // le fichier EML
  },
  {
    "type": "ATTACHMENT",
    "contentType": "file",
    "file_key": "file2" // une pièce jointe
  },
  {
    "type": "RECEIVER",
    "contentType": "text",
    "text": "John Doe <[email protected]>" // le destinataire
    "name": "RECEIVER" // le nom de l'entrée, optionnel
  }
]

Le nom d'une analyse

Le nom de l'analyse est un champ important : il permet d'identifier uniquement un message dans un environment.

Il est déduit automatiquement à partir du nom du fichier principal. Par exemple, si vous envoyez un fichier message-123456.eml, le nom de l'analyse sera message-123456.eml.

Vous pouvez également spécifier un nom personnalisé, en utilisant le champ name de la requête.

attention

Si ce fichier a un nom commun (par exemple, message.eml ou ticket-body.txt), vous devez spécifier une valeur unique par API. Par exemple, dans le cas d'un fichier ticket-body.txt, vous devez spécifier un nom personnalisé pour éviter les conflits (par exemple, ticket-123456).

Évitez aussi d'utiliser des champs qui pourraient être communs à plusieurs analyses (par exemple, le sujet ou le destinataire).

Les options de la requête

Votre requête peut contenir d'autres informations pour décrire votre message, comme un nom personnalisé, ou bien des métadonnées.

Ces informations sont aussi à transmettre dans le champ payload de la requête.

curl --request POST \
      --url https://api.console.golem.ai/environment/<YOUR-ENVIRONMENT-ID>/analyses?appId=<YOUR-APP-ID> \
      --header 'accept: application/json' \
      --header 'authorization: <YOUR-SECRET-KEY>' \
      --header 'content-type: multipart/form-data' \
      --form 'payload={"inputs": [...], "metadata": {...}, "name": "custom-analysis-name"}'
      #                                 ^ metadata object  ^ custom analysis name

Les métadonnées

Les métadonnées sont des données que vous pourriez vouloir conserver sur votre analyse, par exemple pour les faire correspondre à quelque chose de votre côté lorsque vous recevez le résultat par webhook.

Elles sont définies dans l'objet metadata du champ payload :

{
  // the metadata object. Must be a flat JSON object, so no nested objects or arrays.
  "metadata": {
    "inbox": "[email protected]",
    "integration_metadata": "custom_value"
  },
  "inputs": [...]
}

Le champ `inbox` des métadonnées

Mais vous pouvez également spécifier quelque chose qui sera utile pour beaucoup de fonctionnalités dans les métadonnées, c'est le champ inbox.

En définissant le champ inbox sur l'adresse e-mail (ou autre chose, selon votre cas), vous permettez à l'application d'afficher des tableaux de bord et des statistiques basés sur la boîte de réception, et d'autres fonctionnalités.

Ceci est optionnel, mais très fortement recommandé de remplir ce champ, d'autant plus que ce n'est pas quelque chose que nous pouvons facilement déduire des champs à l'intérieur d'un email (e.g. il peut y avoir plusieurs destinataires dans un email).

Le champ `name`

Ce champ est utilisé pour remplacer le nom de l'analyse. Il est optionnel et par défaut est défini sur le nom de fichier du premier fichier BODY.

Ceci est utile si vous voulez donner un nom personnalisé à l'analyse, par exemple quand vous avez plusieurs fichiers et que vous avez un nom pour le groupe d'entre eux, ou quand vous avez un nom dans votre système (comme un ID de ticket) pour l'analyse.

Ce champ doit être différent pour chaque message que vous voulez analyser.

{
  "name": "custom-analysis-name",
  "inputs": [...],
  "metadata": {...}
}

Le champ `manualFinalStatusUpdate`

Ce champ est utilisé pour définir manuellement le statut final de l'analyse. Il est optionnel et par défaut est défini sur false. Si vous le définissez sur true, à la fin de l'analyse, il faudra confirmer le statut final par un appel API.

Ceci n'est pas nécessaire dans l'immense majorité des cas.

Example d'un corps de requête

Dans le cas d'une requête qui envoie un seul fichier hello.txt, le corps de la requête ressemblera à ceci :

--------------------------IFLfDuKMEhUKguSzhPO6ko
Content-Disposition: form-data; name="payload"

{"inputs":[{"contentType":"file","type":"BODY","file_key":"file1"}],"metadata":{"client_id": "1234567890"},"name": "ticket-123456"}
--------------------------IFLfDuKMEhUKguSzhPO6ko
Content-Disposition: form-data; name="file1"; filename="hello.txt"
Content-Type: text/plain

Hello, world!
--------------------------IFLfDuKMEhUKguSzhPO6ko--

On remarque que le body est composé de deux parties :

la première partie est le payload, qui contient les options de la requête (ici, inputs, metadata, et name)
la deuxième partie est le fichier hello.txt. Il est transmis dans le champs file1 (cf le name="file1"), qui a bien été défini dans la partie inputs du payload.

Récupération des résultats

Avec un webhook (recommandé)

C'est la façon préférée de récupérer le résultat : nous envoyons le résultat dès que possible, et nous savons quand nous avons livré le résultat avec certitude.

Si vous choisissez d'intégrer avec cette méthode, nous intégrerons le webhook dans notre configuration. Quand l'analyse sera terminée, Golem.ai fera une requête HTTP POST vers une URL que vous avez définie. Vous pouvez également définir une paire nom de header et valeur que nous enverrons avec la requête, pour protéger votre endpoint.

Par appel HTTP REST

En utilisant l'endpoint /analysis/{analysisId}/result, vous aurez la même sortie que vous auriez reçue par webhook. Si l'analyse n'est pas terminée, vous recevrez un statut PENDING.

Réponse de l'API

Lors de la création d'une analyse, vous recevrez une réponse avec l'ID de l'analyse :

{
  "id": "7f8e8725-221d-4128-bdb4-c655d0884ca8"
}

Cet ID vous permettra de récupérer le résultat de l'analyse plus tard.

Gestion des erreurs

En cas d'erreur, l'API retournera un code d'erreur 400 avec un message descriptif :

{
  "code": 400,
  "message": "Some input is not correct"
}

Assurez-vous de vérifier les codes de réponse et de gérer les erreurs appropriées dans votre intégration.

Introduction​

Prérequis​

Création d'une analyse​

📄️ Analyser un fichier EML

📄️ Analyser un ou plusieurs fichiers

📄️ Analyser du texte et/ou des pièces jointes

Les entrées d'une analyse​

Le format du tableau inputs​

Le nom d'une analyse​

Les options de la requête​

Les métadonnées​

Le champ inbox des métadonnées​

Le champ name​

Le champ manualFinalStatusUpdate​

Example d'un corps de requête​

Récupération des résultats​

Avec un webhook (recommandé)​

Par appel HTTP REST​

Réponse de l'API​

Gestion des erreurs​