Facebook Native Integration

Using Facebook native integration, you can see your chatbot’s interactions on Facebook just as your users see them. The integration is very simple, and basically requires you to copy Bonobo on the JSON you send and receive from Facebook.

REST API

All parameters must be passed as strings

Parameter NameDescriptionRequired
platformwill be always "facebook" in this caseYes
tokencan be generated at app.bonobo.ai, in "settings"Yes
full_jsonfull facebook JSON – the one you send to facebookYes
date_time"2016-8-3 00:00:00". Timestamps are also supported
intents_listlist of intents or events detected in the message that you would like to track (e.g “payment request”, “payment failure” etc.)

Examples

Incoming message (user):

           {
            "platform": "facebook",
            "token": "ASJDLJK987987JASKJ",
            "full_json":{
            "object": "page",
            "entry": [
                 {
                  "id": "324987234987",
                  "time": 1458692752478,
                  "messaging": [
                          {
                          "sender": {
                            "id": "74626837627"
                           },
                          "recipient": {
                            "id": "324987234987"
                          },
                          "timestamp": "1458692752478",
                          "message": {
                                   "mid": "mid.1457764197618:41d102a3e1ae206a38",
                                   "seq": 707,
                          "text": "hello from the user!"
                          }
                 }
                 ]
               }
            ]
}
Outgoing message (bot):

            {
             "platform": "facebook",
             "token": "ASJDLJK987987JASKJ",
             "full_json":{
                         "qs": {
                             "access_token": ""
                         },
                             "uri": "https://graph.facebook.com/v2.6/me/messages",
                         "json": {
                         "message": {
                             "text": "Hello from the bot!"
                             },
                             "recipient": {
                                "id": "74626837627"
                             }
                         },
                         "method": "POST",
                         "responseBody": {
                             "recipient_id": "74626837627",
                             "message_id": " mid.1457764197618:41d102a3e1ae206a38"
                         }
               }
}

Python SDK

  • Install Bonobo API package:
    
                            pip install bonoboapi
  • Import from bonobo the Facebook API:
    
                           from bonoboapi.facebookApiModule import FacebookAPI
  • Define a new Facebook Object:
    
                           bonobo = FacebookAPI(ACCESS_TOKEN_BONOBO)
  • Send user messages and bot messages to bonobo by calling sendDataToBonobo with the Json object you receive\send to facebook:
    
                           bonobo.sendDataToBonobo(jsonData, timeDate – as time stamp/ date time(optional),
                           intentsList(optional));
    

Node.js SDK

  • Install Bonobo API package:
    
                            npm install --save bonoboapi
  • Define a new Facebook-Bonobo object variable:
    
                           var bonobo = require('bonoboapi')( <"Bonobo Token"> ,
                           <"Facebook Token">(optional)).facebook;
                        
  • Send Facebook messages and bot messages to bonobo by calling sendDataToBonobo with the Json object you receive\send to facebook:
    
                           bonobo.sendDataToBonobo(jsonData, timeDate – as time stamp/
                           date time(optional), intentsList – as array(optional));
    
  • If you wish to send only intents/events array without timestamp use as follows:
    
                           bonobo.sendBotToBonobo(jsonData, undefined, intentsList);
    

Botkit

  • Install Bonobo API package:
    
                            npm install --save bonoboapi
  • Define a new Facebook-Bonobo object variable:
    
                           var bonobo = require('bonoboapi')( <"Bonobo Token"> ,
                           <"Facebook Token">(optional)).facebook;
                        
  • Create your Botkit bot:
    
                           const controller = Botkit.facebookbot({…});
  • Define the middleware functions of Bonobo that Botkit will call each time it receives a message(receaive.use) and sends a message(send.use):
    
                           controller.middleware.receive.use(bonobo.receive);
    controller.middleware.send.use(bonobo.send);

Codeless

  • Go to https://developers.facebook.com/apps/ and click on "Add a New App".

    - For category choose "Apps For Messenger".
  • In Token Generation select the page that your bot is associated with:
  • Copy and paste your facebook access token into bonobo's account page:
  • In Webhooks select "Setup Webhooks":
  • Enter your callback URL:

    https://api.bonobo.ai/apiv1/addmessage/?platform=facebook&token=YOUR_BONOBO_TOKEN

    - For Verify Token type "bonobo".

    - Choose all boxes.

  • Click on “Select a Page” and select the page associated with your bot, then click on "Subscribe":

Slack Native Integration

Using Slack native integration, you can see your chatbot’s interactions on Slack just as your users see them. The integration is very simple, and basically requires you to copy Bonobo on the JSON you send and receive from Slack:

REST API

All parameters must be passed as strings

Parameter NameDescriptionRequired
platformwill be always "slack"Yes
tokencan be generated at app.bonobo.ai, in "settings"Yes
full_jsonfull slack JSON – the one you send to SlackYes
date_time"2016-8-3 00:00:00". Timestamps are also supported
intents_listlist of intents or events detected in the message that you would like to track (e.g “payment request”, “payment failure” etc.)

Examples

Incoming message (user):

            {
                "platform": "slack",
                "token": "ASJDLJK987987JASKJ",
                "full_json": {
                    "token": "x0-....",
                    "team": {
                        "id": "T0MHH8VCH",
                        "name": "MYTEST"
                    },
                    "bot": {
                        "id": "B0MHKCPHD"
                    },
                      "message": {
                                  "text": "hello",
                                  "ts": "1477431815.000021",
                                  "user": "U0MHCB80D",
                                  "team": "T0MJH9VCF",
                                  "type": "message",
                                  "channel": "G0MG3SD4U"
                      },
                    }
}
Outgoing message (bot):

            {
                "platform": "slack",
                "token": "ASJDLJK987987JASKJ",
                "full_json": {
                    "token": "x0-....",
                    "team": {
                        "id": "T0MHH8VCH",
                        "name": "MYTEST"
                    },
                    "bot": {
                        "id": "B0MHKCPHD"
                    },
                      "message": {
                              "type": "message",
                              "channel": "G0MG3SD4U",
                              "text": "I am a test message http://slack.com",
                              "attachments": [
                                   {
                                        "text": "And here's an attachment!"
                                   }
                              ]
                      },
                    }
}

Python SDK

  • Install Bonobo API package:
    
                            pip install bonoboapi
  • Import from bonobo the Slack API:
    
                           from bonoboapi.slackApiModule import SlackAPI
    
  • Define a new Slack Object:
    
                           bonobo = SlackAPI(ACCESS_TOKEN_BONOBO)
  • Send user messages and Bot messages to Bonobo by calling the following functions with the Json object you receive\send to Slack:
    For sending User messages:
    
                           bonobo.sendUserToBonobo(jsonData, timeDate – as time stamp/ date time(optional),
                           intentsList – (optional))
    
    
    
    For sending Bot messages:
    
                           bonobo.sendBotToBonobo(jsonData, timeDate – as time stamp/ date time(optional),
                           intentsList – (optional))
    
    
    If you wish to send only intents list without timestamp use as follows:
    
                           bonobo.sendBotToBonobo(jsonData, None, intentsList)
    
    
    

Node.js SDK

  • Install Bonobo API package:
    
                            npm install --save bonoboapi
  • Define a new Slack-Bonobo object variable:
    
                           var bonobo = require('bonoboapi')( <"Bonobo Token"> , <"Slack Token">(optional)).slack;
    
                        
  • Send User messages and Bot messages to Bonobo by calling the following functions with the Json object you receive\send to Slack:
    
                           bonobo.sendBotToBonobo(jsonData, timeDate – as time stamp/ date time(optional),
                           intentsList – as array(optional));
    
    
  • If you wish to send only intents/events array without timestamp use as follows:
    For sending Bot messages:
    
                           bonobo.sendBotToBonobo(jsonData, timeDate – as time stamp/ date time(optional),
                           intentsList – as array(optional));
    
    
    
    If you wish to send only intents list without timestamp use as follows:
    
                           bonobo.sendBotToBonobo(jsonData, undefined, intentsList);
    
    
    

Botkit

  • Install Bonobo API package:
    
                            npm install --save bonoboapi
  • Define a new Facebook-Bonobo object variable:
    
                           var bonobo = require('bonoboapi')( < Bonobo Token> ,
                           < Slack Token>(optional)). slack;
    
                        
  • Create your Botkit bot:
    
                           const controller = Botkit.slackbot({…});
  • Define the middleware functions of Bonobo that Botkit wil call each time it receives a message (receive.use) and sends a message (send.use):
    
                           controller.middleware.receive.use(bonobo.receive);
    controller.middleware.send.use(bonobo.send);

Viber Native Integration

Using Viber native integration, you can see your chatbot’s interactions on Viber just as your users see them. The integration is very simple, and basically requires you to copy Bonobo on the JSON you send and receive from Viber:

REST API

All parameters must be passed as strings

Parameter NameDescriptionRequired
platformwill be always "viber"Yes
tokencan be generated at app.bonobo.ai, in "settings"Yes
full_jsonfull Viber JSON – the one you send to ViberYes
auth_tokenOptional in “incoming message” (User)
date_time"2016-8-3 00:00:00". Timestamps are also supported
intents_listlist of intents or events detected in the message that you would like to track (e.g “payment request”, “payment failure” etc.)

Examples

Incoming message (user):

            {
                "platform": "viber",
                "token": "",
                "full_json": {
                              "auth_token": "",
                              "timestamp": "1478694591484L",
                              "message_token": "4977115541722554762L",
                              "message": {
                                "text": "Hi",
                                "type": "text"
                              },
                              "event": "message",
                              "sender": {
                                "id": ,
                                "avatar": "URL",
                                "name":
                              }
                }
}
Outgoing message (bot):

            {
                "platform": "viber",
                "token": "",
                "full_json": {
                              "auth_token": "",
                              "receiver": "",
                              "type": "text",
                              "text": "Hey!",
                }
}

Python SDK

  • Install Bonobo API package:
    
                            pip install bonoboapi
  • Import from bonobo the Viber API:
    
                           from bonoboapi.viberApiModule import ViberAPI
    
  • Define a new Viber Object:
    
                           bonobo = SlackAPI(ACCESS_TOKEN_BONOBO)
  • Send user messages and Bot messages to Bonobo by calling the following functions with the Json object you receive\send to Viber:
    For sending Bot messages:
    
                           bonobo.sendDataToBonobo(jsonData, timeDate – as time stamp/ date time(optional),
                           intentsList – (optional));
    
    
    
                        

Node.js SDK

  • Install Bonobo API package:
    
                            npm install --save bonoboapi
  • Define a new Viber-Bonobo object variable:
    
                           var bonobo = require('bonoboapi')( <"Bonobo Token"> , <"Viber Token">
                           (optional)).viber;
    
    
                        
  • Send User messages and Bot messages to Bonobo by calling the following functions with the Json object you receive\send to Viber:
    For sending Bot messages:
    
                           bonobo.sendBotToBonobo(jsonData, timeDate – as time stamp/ date time(optional),
                           intentsList – as array(optional));
    
    
    
    
    If you wish to send only intents list without timestamp use as follows:
    
                           bonobo.sendBotToBonobo(jsonData, undefined, intentsList);
    
    
    

Bonobo Live Intervention

Bonobo Live enables you to intervene with conversations in two different ways:
1. Send messages to your users without pausing your bot
2. Take over your bot – which means you pause and play it at will

Sending messages without pausing your bot

Supported in Facebook, Slack and Viber

No integration needed. When you play live conversations, you can just insert sentences and click “send”. Your users will receive them immediately.

In order to pause and play your bot, please follow these steps:

Supported in Facebook, Slack and Viber
  • Create a Webhook that will receive paused user sessions. Add your Webhook URL to the "facebook Pause URL"/"slack Pause URL"/ “Viber Pause URL” field in app.bonobo.ai under "Account". This is how it works:
    When pressing "pause" we will send a POST request to your Webhook url with this data:
    
                                                    {
                        "is_paused": "true",
                        "conversation_id": "SOME_ID"
    }
    When pressing "play" we will send a POST request to your Webhook url with this data:
    
                    {
                        "is_paused": "false",
                        "conversation_id": "SOME_ID"
    }
  • Each time that you receive a new message, quickly check if this session is paused and if so - stop the bot from responding. you can simply manage a list of all the paused sessions and check the session status before responding.

Generic API

Chatbots built on all platforms can integrate with Bonobo’s generic API. However, if your bot was built on Facebook, Slack or Viber, we strongly recommend using the respective native integrations.

REST API

All parameters must be passed as strings

Parameter NameDescriptionRequired
tokencan be generated under "settings" in app.bonobo.aiYes
textthe message itself (UTF-8 encoding is optimal)Yes
channel_idunique conversation id. This parameter is optional if user_id is provided.Yes
platformwill be always "viber"Yes
user_idunique user_id. This parameter is optional if channel_id is providedYes
platformtype of messaging platform used (e.g kik, LINE, WeChat)Yes
who_speaks"bot"/"user"Yes
date_time"2016-8-3 00:00:00". Timestamps are also supported
intents_listlist of intents or events detected in the message that you would like to track (e.g “payment request”, “payment failure” etc.)

Example

Outgoing message (bot):

{
"id_channel": "KSJDUA9",
"date_time": "2016-8-3 00:01:01",
"text": "hey!",
"platform": "slack",
"token": "525fc441c49Pf2b4bacf0e6b75935ab5",
"who_speaks": "bot",
}

Python SDK

  • Install Bonobo API package:
    
                            pip install bonoboapi
  • Import from bonobo the Generic API:
    
                           from bonoboapi.genericApiModule import GenericAPI
    
  • Define a new Generic Object:
    
                           bonobo = GenericAPI(ACCESS_TOKEN_BONOBO)
  • Send user messages and Bot messages to Bonobo by calling the following functions with the Json object you receive\send:
    Parameter NameDescriptionRequired
    textthe message itself (UTF-8 encoding is optimal)Yes
    channel_idunique conversation id. This parameter is optional if user_id is provided.Yes
    user_idunique user_id. This parameter is optional if channel_id is providedYes
    platformwill be always "viber"Yes
    who_speaks"bot"/"user"Yes
    date_time"2016-8-3 00:00:00". Timestamps are also supported
    intents_listlist of intents or events detected in the message that you would like to track (e.g “payment request”, “payment failure” etc.)
    For sending messages:
    
                           bonobo.sendDataToBonobo(text, channel_id, user_id, platform, who_speaks, date_time
                           (optional), intents_list(optional))
                            
    If you wish to send only intents list without timestamp use as follows:
    
                           bonobo.sendDataToBonobo(text, channel_id, user_id, platform, who_speaks, None,
                           intents_list(optional))

Node.js SDK

  • Install Bonobo API package:
    
                            npm install --save bonoboapi
  • Define a new Generic-Bonobo object variable:
    
                           var bonobo = require('bonoboapi')( <"Bonobo Token">).generic;
    
  • Define a new Generic Object:
    
                           bonobo = GenericAPI(ACCESS_TOKEN_BONOBO)
  • Send user messages and bot messages to bonobo by calling sendDataToBonobo function with the Json object you receive\send:
    Parameter NameDescriptionRequired
    textthe message itself (UTF-8 encoding is optimal)Yes
    channel_idunique conversation id. This parameter is optional if user_id is provided.Yes
    user_idunique user_id. This parameter is optional if channel_id is providedYes
    platformwill be always "viber"Yes
    who_speaks"bot"/"user"Yes
    date_time"2016-8-3 00:00:00". Timestamps are also supported
    intents_listlist of intents or events detected in the message that you would like to track (e.g “payment request”, “payment failure” etc.)
    For sending messages:
    
                           sendDataToBonobo(text, channel_id, user_id, platform, who_speaks,
                           date_time(Optional), intents_list(Optional));
    
                            
    If you wish to send only intents list without timestamp use as follows:
    
                           bonobo.sendBotToBonobo(jsonData, undefined, intentsList);