Skip to content

Développer en mode Tock Bot API

Le mode Bot API de Tock permet de développer des bots en se connectant à une plateforme Tock Studio en utilisant l’API REST conversationnelle de Tock.

C’est donc le mode de développement Tock recommandé pour démarrer, ainsi que dans des scenarios ou l’accès partagé à la base de données serait un problème.

Seul le mode Bot API est disponible sur la plateforme de démonstration publique Tock.

Cette page présente le développement de bots Tock en mode Bot API en Kotlin. Des clients sont aussi disponibles pour Javascript/Node et Python. Il est possible de développer des parcours Tock dans n’importe quel langage via la Bot API.

Logo Kotlin Logo Nodejs Logo Python API

Une autre section présente le mode Bot Framework disponible pour Kotlin uniquement, plus intégré mais aussi plus couplé à la plateforme Tock.

Se connecter sur la plateforme de démonstration

Plutôt que déployer se propre plateforme Tock, il est possible de tester les modes WebSocket ou Webhook directement sur la plateforme de démonstration Tock.

Développer en Kotlin

Logo Kotlin

Activer le mode WebSocket

C’est le mode à privilégier au démarrage car le plus simple à mettre en oeuvre.

Pour utiliser le client websocket, il faut ajouter la dépendance tock-bot-api-websocket à votre application/projet Kotlin.

Par exemple dans un projet Maven :

        <dependency>
            <groupId>ai.tock</groupId>
            <artifactId>tock-bot-api-websocket</artifactId>
            <version>23.9.2</version>
        </dependency>

Ou dans un projet Gradle :

      compile 'ai.tock:tock-bot-api-websocket:23.9.2'

Activer le mode WebHook

De manière alternative, vous pouvez choisir d’utiliser le client WebHook, il faut ajouter la dépendance tock-bot-api-webhook à votre application/projet Kotlin.

Par exemple dans un projet Maven :

        <dependency>
            <groupId>ai.tock</groupId>
            <artifactId>tock-bot-api-webhook</artifactId>
            <version>23.9.2</version>
        </dependency>

Ou dans un projet Gradle :

      compile 'ai.tock:tock-bot-api-webhook:23.9.2'

Dans ce cas, contrairement au mode WebSocket, il faut que l’application/bot démarrée soit joignable par la plateforme Tock via une URL publique (vous pouvez utilisez par exemple ngrok).

Cette URL doit être indiquée dans le champ webhook url dans la vue Configuration > Bot Configurations de l’interface Tock Studio.

Paramétrer la clé d’API

Dans Tock Studio, après avoir configuré un bot, allez dans Configuration > Bot Configurations et copiez la clé d’API du bot auquel vous souhaitez vous connecter.

Vous pourrez saisir/coller cette clef dans le code Kotlin (voir ci-dessous).

Créer des parcours en Kotlin

Pour le moment, les composants suivants sont supportés pour les réponses :

  • Texte avec Boutons (Quick Reply)
  • Format “carte”
  • Format “carousel”
  • Formats spécifiques aux différents canaux intégrés

Voici un exemple de bot simple avec quelques parcours déclarés :

fun main() {
    startWithDemo(
        newBot(
            "PUT-YOUR-TOCK-APP-API-KEY-HERE", // Récupérer la clé d'API à partir de l'onglet "Bot Configurations" dans Tock Studio
             newStory("greetings") { // Intention 'greetings'
                 end("Bonjour!") // Réponse texte simple
             },
             newStory("location") { // Intention 'location'
                 end(
                     // Réponse avec une carte - pouvant inclure du texte, un fichier (par exemple une image) et des suggestions d'action utilisateur
                     newCard(
                         "Le titre de la carte",
                         "Un sous-titre",
                         newAttachment("https://url-image.png"),
                         newAction("Action 1"),
                         newAction("Action 2", "http://redirection") 
                     )
                 )
             },
             newStory("goodbye") { // Intention 'goodbye'
                 end {
                     // Réponse spécifique au format Messenger 
                     buttonsTemplate("Etes-vous sûr(e) de vouloir partir ?", nlpQuickReply("Je reste"))
                 } 
             },
             // Réponse fournie pas le bot en cas d'incompréhension
             unknownStory {
                 end("Je n'ai pas compris. Mais j'apprends tous les jours :)")
             }
        )
    )
}

Le code source complet de l’exemple est disponible.

Développer en Javascript

Logo Nodejs

Un client est fourni pour développer des parcours en Javascript avec Nodejs.
Pour en savoir plus, voir la documentation sur le dépôt tock-node.

Développer en Python

Logo Python

Un client est fourni pour développer des parcours en Python.
Pour en savoir plus, voir la documentation sur le dépôt tock-py.

Développer via l’API

Logo API

Il est possible de développer des parcours Tock dans n’importe quel langage, en s’interfaçant directement avec l’API.

Installer Bot API côté serveur

Pour utiliser le mode Bot API de Tock, un module spécifique doit être déployé avec la plateforme. Généralement appelé bot-api dans les descripteurs Docker Compose par exemple, ce service a pour rôle :

  • D’exposer la Bot API aux clients potentiels quelque soit leur langage de programmation
  • D’accepter des connexions en WebSocket et/ou de se connecter au webhook configuré

Le guide Déployer Tock avec Docker ou encore le chapitre Installation montrent comment déployer ce module si nécessaire.

La seule modification nécessaire par rapport au code d’exemple pour la platforme de démonstration est de remplacer la méthode startWithDemo par start en précisant si besoin l’adresse de du serveur bot-api.