Skip to content

Tock Bot API Mode

This is the recommended way to start developing stories with Tock.

Kotlin, Javascript and Python clients are available. Any programming language can be used, leveraging the Tock Bot API.

Kotlin logo Nodejs logo Python logo API logo

Connect to the demo platform

Rather than deploying its own Tock platform, it is possible to test the WebSocket or Webhook modes directly on the Tock demo platform.

Develop with Kotlin

Kotlin logo

Enable WebSocket mode

This is the preferred mode at startup, requiring no additional tunnel / setup.

To use the WebSocket client, add the tock-bot-api-websocket dependency to your Kotlin application / project.

Using Maven :


Or Gradle :

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

Enable WebHook mode

Alternatively, you can choose to use the WebHook client. Add the tock-bot-api-webhook dependency to your Kotlin application / project.

Using Maven :


Or Gradle :

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

In this case, unlike the WebSocket mode, the bot application must be reachable by the Tock platform and so has to expose a public URL (you can use ngrok in order to provide this URL).

This URL must be specified in the webhook url field in the Configuration> Bot Configurations view of Tock Studio.

Note that the WebHook mode may require the setup of a secure tunnel to the Bot API running client. As a matter of fact, the client may not be reachable from the server. For development, tools like ngrok may help.

Set up the API key

  In Tock Studio, after configuring a bot, go to Configuration> Bot Configurations and copy the API key of the bot to which you want to connect.   You can enter / paste this key into the Kotlin code (see below).

Create Stories

  The following formats are supported:

  • Text with Buttons (Quick Replies)
  • “Card” format
  • “Carousel” format
  • Specific channel formats like Messenger format, Slack format, etc.

Here is a simple bot with a few stories:

fun main() {
            "PUT-YOUR-TOCK-APP-API-KEY-HERE", // Get your app API key from Bot Configurations in Tock Studio
             newStory("greetings") { // Intent 'greetings'
                 end("Hello!") // Raw text answer
             newStory("location") { // Intent 'location'
                    // Anwser with a card - including text, file(image, video,..) and user action suggestions
                         "Card title",
                         "Card sub title",
                         newAction("Action 1"),
                         newAction("Action 2", "http://redirection") 
             newStory("goodbye") { // Intent 'goodbye'
                 end {
                     // Answer with Messenger-specific button/quick reply
                     buttonsTemplate("Are you sure ?", nlpQuickReply("Stay here"))
             // Fallback answer when the bot does find a correct response
             unknownStory {
                 end("Sorry I don't understand :(") 

Please consult the full source code sample.

Develop with Javascript

Nodejs logo

A Nodejs client is available to program Tock stories in Javascript.
Please visit the tock-node repository and documentation.

Develop with Python

Python logo

A client is available to program Tock stories in Python.
Please visit the tock-py repository and documentation.

Develop through the API

API logo

It is possible to develop in the language of your choice by using directly the underlying REST

Install Bot API server-side

To use Tock’s Bot API mode without the demo platform, a specific module must be deployed on your own server.

Called bot-api in Docker Compose descriptors, this service:

  • Expose the Bot API to the potential customers whatever their programming language are.
  • Accept WebSocket connections and / or connections to the configured webhook.

Compared to the “demo mode”, The only required change in the code is to replace the startWithDemo method with the start one, specifying the bot-api target server address.