Talk to a bot with the API

You might want to deploy your bot on a platform we are not currently connected to, or integrate your bot in a mobile application;

in such cases you have to use our API!

In order to talk to a bot you will first need to create an interlocutor.
An interlocutor represents a person talking to a bot.
Each interlocutor gets his own state (session values and current step). This means that you have to create a different interlocutor for each of your users that needs to talk to the bot.

📘

Authentification

In order to use the API in the following examples you will need your bot access token.
Please refer to our documentation to understand how to use it.

1. Create an interlocutor

In order to create an interlocutor you just have to send a userID to the interlocutors endpoint.

This userID must have been generated by you, and will represent this interlocutor.
userID could for example be the primary key of your users database table.

Example (replace {BOT_ID} and {ACCESS_TOKEN} with your own information) :

curl -d '{"type": "interlocutor", "userID": "clustaar-597b623f47e8461e7c57bbd4"}' \
    -X POST https://api.clustaar.io/bots/{BOT_ID}/interlocutors/clustaar_web_chat \
    -H 'Authorization: Bearer {ACCESS_TOKEN}'

The response now contains your interlocutor for your user with the ID clustaar-597b623f47e8461e7c57bbd4 :

{
  "data":{
    "type":"interlocutor",
    "id":"5a82df51bf8a1100a0615f4a"
  }
}

Note that if an interlocutor already exists with the same userID, the existing interlocutor is returned.
This means that you don't have to store the Clustaar interlocutor ID on your side.

You are now good to start talking to your bot!

2. Talk to your bot

Your interlocutor is ready, you can now send a message to your bot.

For example if your user typed hello in your chat window then the corresponding request is (replace {INTERLOCUTOR_ID} and {ACCESS_TOKEN} with your own information):

curl -d '{"type": "text", "message": "hello"}' \ 
    -X POST https://api.clustaar.io/interlocutors/{INTERLOCUTOR_ID}/reply \
    -H 'Authorization: Bearer {ACCESS_TOKEN}'

The response contains more information than just the bot response.
You get :

• the bot response (fulfillment contains the list of the actions you should display to your user in your chat window)
• the session with all its values (session)
• the interlocutor object that sent the request (interlocutor)
• the input sent to the bot (input)

{
   "data":{
      "fulfillment":{
         "actions":[
            {
               "type":"send_text_action",
               "alternatives":[
                  "Hi !"
               ]
            }
         ],
         "source":{
            "type":"actions_block",
            "actions_block":{
               "type":"actions_block",
               "id":"5a82e013bf8a11000d179596",
               "name":"Hello"
            }
         }
      },
      "session":{
         "values":{

         }
      },
      "interlocutor":{
         "type":"interlocutor",
         "id":"5a82df51bf8a1100a0615f4a",
         "location": null
      },
      "input":{
         "type":"text",
         "message":"hello"
      },
      "debug":null
   }
}

See that debug field ?
If you pass debug=1 in the GET parameters of your request you will get even more information, like the requests sent to your webhook and the intent detection results.

For more details about the response you can go to our API reference.

You are now good to deploy your bot in your mobile application, shell, smart speakers, etc.