INTRODUCTION / INTRODUCTION

Introduction

The Botanalytics API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API token in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. Be sure to subscribe to Botanalytics's API announce mailing list to receive information on new additions and changes to Botanalytics's API and language libraries.

Authentication

Authenticate your account by including your token in API requests. You can manage your API tokens in the Botlist. Your API token carry many privileges, so be sure to keep them secure! Do not share your API token in publicly accessible areas such GitHub, client-side code, and so forth. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Botanalytics uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Botanalytics's servers.


200, 201 OK Everything worked as expected (some API calls may return 201 instead).

400 Bad Request The request was unacceptable, often due to missing a required parameter.

401 Unauthorized You forgot to include your API token or it is wrong.

404 Not Found The requested resource doesn't exist.

500, 502, 503, 504 Server Errors Something went wrong on Botanalytics's end. Try again later. (These are rare.)

API libraries

Official libraries for the Botanalytics API are available in several languages such as Node.js, Python, Java and Ruby.

API Endpoint

https://api.botanalytics.co/v1/

Live Person Takeover - Hybrid Mode

On Hybrid mode, human representative can join the conversation with pausing the bot. To improve the engagement of conversations, you can pause the bot and join the conversation. You can send messages as If they are coming from your bot. After you talk with your user, you can enable bot again before leaving the conversation.

User Profile

This endpoint is built for all platforms, any combination is acceptable as long as unique id is provided.

If you're using this endpoint, just make sure you include "id" since it's the only required part. Then, you can customize the rest according to your preferences. It's possible to choose from the options provided like last_name, email, gender and etc.

TIP #1: You can also create custom objects for the user. Please see below the details to learn more about how creating new objects and defining custom fields work.

TIP #2: Fields like email, language, and phone might have multiple entries. For example, one user might have more than one email address. Since we're capable of keeping these entries separately, you can send us different calls for additional email, language and phone field entries.

COPY
cURL
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"id\": \"..\",
  • \"full_name\": \"..\",
  • \"username\": \"..\",
  • \"first_name\": \"..\",
  • \"last_name\": \"..\",
  • \"email\": \"..\",
  • \"phone\": \"..\",
  • \"gender\": \"..\",
  • \"locale\": \"..\",
  • \"country\": \"..\",
  • \"city\": \"..\",
  • \"profile_pic\": \"..\",
  • \"timezone\": \"..\",
  • \"language\": \"..\",
  • \"custom\": ..
  • }" \
  • 'https://api.botanalytics.co/v1/platform/users/'
  • user_id

    required

    string

    Platform related unique ID of the user

  • full_name

    optional

    string

    Full Name of the user

  • first_name

    optional

    string

    First Name of the user

  • last_name

    optional

    string

    Last Name of the user

  • email

    optional

    string

    Email of the user

  • phone

    optional

    string

    Phone number of the user, with country code

  • gender

    optional

    string

    Gender of the user, "male"|"female"|"unknown"

  • locale

    optional

    string

    Locale of the user etc; en_US, ca_ES

  • country

    optional

    string

    Country parth of ISO_CODE format etc "US"

  • city

    optional

    string

    City of the user

  • profile_pic

    optional

    string

    Profile picture url of the user

  • timezone

    optional

    string

    Timezone is ± difference from utc (etc "+3") for the user

  • language

    optional

    object

    Language parth of ISO_CODE format etc "en"

  • custom

    optional

    Array of Json Object

    Custom property fields for the user, etc. [ {"birth_date": "09/01/1990" }, {"coffee_time": ""}]

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/platform/users/

Natural Language Understanding

This section enables features via "nlu_payload" parameter to any platform. NLU payload enables you to send us your messages with additional information about natural language properties. Thus, we understand intent structure of your message types and automatically track and tag them according to NLU structures.

Currently supported NLU platforms include;

Microsoft LUIS

Rasa

Watson Assistant

TIP 1: Having NLU based bots & projects will improve the overall quality of your analytics data since it you'll be able to use our intent tracking, intent path tracking and conversation paths features.

TIP 2: Please add type (can be either "luis", "rasa" or "watson_assistant") parameter inside the json object before send us the "nlu_payload" you receive from one of the supported NLU platforms. See below the nlu_payload parameter content examples

LUIS
Rasa
Watson Assistant
  • {
  • "type": "luis",
  • "query": "I am looking for Mexican food",
  • "topScoringIntent":{
  • "intent": "...",
  • "score": "..."
  • },
  • "intents":[
  • ...
  • ],
  • "entities":[
  • ...
  • ]
  • }

Natural Language Understanding Example

Generic Platform Example

TIP : Below you can see how nlu_payload is being sent to our end via generic platform, please be aware nlu_payload parameter is available for all platforms.

COPY
LUIS
Rasa
Watson Assistant
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"is_sender_bot\": ,
  • \"user\":{
  • \"id\": \"...\"
  • },
  • \"message\":{
  • \"timestamp\": ,
  • \"text\": \"...\"
  • },
  • "nlu_payload": {
  • "type": "luis",
  • "query": "I am looking for Mexican food",
  • "topScoringIntent":{
  • "intent": "...",
  • "score": "..."
  • },
  • "intents":[
  • ...
  • ],
  • "entities":[
  • ...
  • ]
  • }
  • }" \
  • 'https://api.botanalytics.co/v1/messages/generic/'
  • is_sender_bot

    required

    boolean

    true If sms is sent by Bot, false otherwise

  • user

    required

    object

  • message

    required

    object

  • nlu_payload

    optional

    object

    NLU payload content as mentioned at the section above

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/generic/

Facebook Messenger



Messages

COPY
Node.js
Python
Ruby
cURL
  • const Botanalytics = require('botanalytics').
  • FacebookMessenger(process.env.BOTANALYTICS_TOKEN);

  • app.post('/webhook/', function (req, res) {
  • ...
  • var data = req.body;
  • Botanalytics.logIncomingMessage(req.body);
  • ...
  • ...
  • Botanalytics.logOutgoingMessage(
  • messageData,
  • sender,
  • process.env.FACEBOOK_PAGE_TOKEN);
  • ...
  • })
  • recipient

    required

    string

    Always null for incoming messages

  • timestamp

    required

    number

    Timestamp of the message in milliseconds

  • message

    required

    object

    Facebook's message object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/facebook-messenger/

Node.js code example

Facebook Messenger Livechat Settings

Livechat settings can be either set via botlist page or you can make a REST call.

COPY
cURL
  • curl --include \
  • --request PATCH \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"platform_token\": \"..\",
  • \"webhook_url\": \"..\",
  • }" \
  • 'https://api.botanalytics.co/v1/bots/me'
  • platform_token

    required

    string

    Facebook Messenger bot's auth token

  • webhook_url

    required

    string

    Pause webhook url,

    https://yourbotswebhookurl/pause

Header Authorization:Token BOTANALYTICS_TOKEN

Patchhttps://api.botanalytics.co/api/v1/bots/me/

Facebook Messenger Pause Webhook

Your webhook will recieve two fields in the body:

userId Facebook user ID of the session to pause

paused Whether to pause the bot or not

While the details of the implementation may vary, at a high level, your webhook should keep track of which user sessions are paused. Whenever a new message is received, check if the session is paused for that user, and if so, stop the bot responding.

Facebook Webhook Example:

COPY
Node.js
  • var pausedUsers = {}
  • app.post('/pause', jsonParser, function (req, res) {
  • const userId = req.body.userId
  • const paused = req.body.paused
  • pausedUsers[userId] = paused
  • res.send("ok")
  • });

And then, check the status after receiving a message:

COPY
Node.js
  • app.post('/webhook/', jsonParser, function (req, res) {
  • ...
  • if(req.body.entry){
  • req.body.entry.forEach(function(entry){
  • if(entry.messaging){
  • entry.messaging.forEach(function(event){
  • var recipientId = event.sender.id;
  • if(!pausedUsers[recipientId]){
  • //handle message if session is not paused for this userId
  • [...]
  • }
  • }
  • }
  • }
  • }
  • ...
  • }

Facebook User Profile

COPY
Node.js
Python
Ruby
cURL
  • const Botanalytics = require('botanalytics').
  • FacebookMessenger(process.env.BOTANALYTICS_TOKEN);

  • var profileData = {
  • "first_name": "..."
  • "last_name": "..."
  • "profile_pic": "..."
  • "locale": "..."
  • "timezone": "..."
  • "gender": "..."
  • "user_id": "..."
  • };
  • Botanalytics.logUserProfile(profileData);
  • user_id

    required

    string

    Facebook Page-scoped ID of the user

  • first_name

    optional

    string

    Facebook's user profile 'first_name'

  • last_name

    optional

    string

    Facebook's user profile 'last_name'

  • profile_pic

    optional

    string

    Facebook's user profile 'profile_pic'

  • locale

    optional

    string

    Facebook's user profile 'locale'

  • timezone

    optional

    number

    Facebook's user profile 'timezone'

  • gender

    optional

    object

    Facebook's user profile gender

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/facebook-messenger/users/

Google Rbm

Incoming Messages



COPY
Java
  • import co.botanalytics.sdk.rbm.BotanalyticsRBMClient;
  • BotanalyticsRBMClient botanalyticsClient = new
  • BotanalyticsRBMClient(process.env.BOTANALYTICS_TOKEN);

  • ...
  • @Override
  • public void doPost(HttpServletRequest request, HttpServletResponse
  • response) throws IOException {
  • ...
  • botanalyticsClient.logMessage(request);
  • ...
  • }
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/rbm/

Google Rbm

Outgoing Messages



COPY
Java
  • import co.botanalytics.sdk.rbm.BotanalyticsRBMClient;
  • BotanalyticsRBMClient botanalyticsClient = new
  • BotanalyticsRBMClient(process.env.BOTANALYTICS_TOKEN);

  • ...
  • RCSBusinessMessaging.Phones.AgentMessages.Create message =
  • builder.build().phones().agentMessages().create(convertToApiFormat(msisdn), agentMessage);

  • AgentMessage agentMessage = message.execute();
  • // for text messages
  • botanalyticsClient.logMessage(agentMessage);
  • // for media messages we have four different method
  • String fileUrl = uploadFile("...");
  • botanalyticsClient.logImageMessage(agentMessage, fileUrl);

  • botanalyticsClient.logVideoMessage(agentMessage, fileUrl);

  • botanalyticsClient.logAudioMessage(agentMessage, fileUrl);

  • botanalyticsClient.logFileMessage(agentMessage, fileUrl);

  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/rbm/

Google Assistant



Actions SDK

COPY
Node.js/Actions SDK
cURL
  • const { actionssdk } = require ( 'actions-on-google' );
  • const Botanalytics = require ( 'botanalytics' ).
  • GoogleAssistant ( process.env.BOTANALYTICS_TOKEN );
  • const app = actionssdk();
  • Botanalytics. attach ( app );

  • exports.sillyNameMaker = ( req, res ) => {
  • ...
  • Handle your app
  • ...
  • };

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/google-assistant/

Node.js/Actions Sdk code example

DialogFlow with NPM

COPY
Node.js/Dialogflow
  • const { dialogflow } = require ( 'actions-on-google' );
  • const Botanalytics = require ( 'botanalytics' ).
  • GoogleAssistant ( process.env.BOTANALYTICS_TOKEN );
  • const app = dialogflow();
  • Botanalytics. attach ( app );

  • exports.sillyNameMaker = ( req, res ) => {
  • ...
  • Handle your app
  • ...
  • };

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/google-assistant/

Node.js/Dialogflow code example

Dialogflow with Firebase

COPY
Node.js/Dialogflow with Firebase
  • const Botanalytics = require('botanalytics').
  • GoogleAssistant(process.env.BOTANALYTICS_TOKEN);

  • const { dialogflow } = require ( 'actions-on-google' );
  • const Botanalytics = require ( 'botanalytics' ).
  • GoogleAssistant ( process.env.BOTANALYTICS_TOKEN );
  • const app = dialogflow();
  • ...
  • Handle your app
  • ...
  • Botanalytics. attach ( app );

    • exports.dialogflowFirebaseFulfillment = functions.https. onRequest ( app );

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/google-assistant/

Python SDK

COPY
Python SDK
  • from botanalytics.google import GoogleAssistant

  • botanalytics = GoogleAssistant(debug=True,
  • token=os.environ['BOTANALYTICS_API_TOKEN'],
  • callback=err_callback,
  • async=True)

  • ...
  • botanalytics.log(request_payload, response_payload)
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/google-assistant/

Python SDK with Google Cloud Functions

COPY
Python SDK with Google Cloud Functions
  • from botanalytics.google import GoogleAssistantCloudFunctions

  • botanalytics = GoogleAssistantCloudFunctions(debug=True,
  • token=os.environ['BOTANALYTICS_API_TOKEN'],
  • async=True)

  • ...
  • botanalytics.log(request_payload, response_payload)
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/google-assistant/

Ruby SDK

COPY
Ruby SDK
  • require 'botanalytics'
  • botanalytics = Botanalytics::GoogleAssistant.new(
  • :debug => true,
  • :async => true,
  • :token => ENV['BOTANALYTICS_API_TOKEN'],
  • :callback => :error_callback)
  • ...
  • botanalytics.log(request_payload, response_payload)
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/google-assistant/

Amazon Alexa



Lambda with Skills Kit V2

COPY
Node.js/Lambda with Skills Kit V2
cUrl
  • const Botanalytics = require('botanalytics').
  • AmazonAlexa(process.env.BOTANALYTICS_TOKEN);

  • const skill = Alexa. SkillBuilders . custom ()
  • . withSkillId ( "Your alexa skill id" )
  • . addRequestHandlers ( Handler1,Handler2,... )
  • . addErrorHandlers ( ErrorHandler1,... )
  • . create ();
  • exports.handler = Botanalytics.handler(event, context) {
  • ...
  • return skill . invoke ( event, context );
  • ...
  • }

  • -----OR-----
  • const lambda = Alexa. SkillBuilders . custom ()
  • . withSkillId ( "Your alexa skill id" )
  • . addRequestHandlers ( Handler1,Handler2,... )
  • . addErrorHandlers ( ErrorHandler1,... )
  • . lambda ();
  • exports.handler = Botanalytics .handler ( lambda );

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/amazon-alexa/

Node.js code example

Node.js Webhook

COPY
Node.js Webhook
  • const Botanalytics = require('botanalytics').
  • AmazonAlexa(process.env.BOTANALYTICS_TOKEN);

  • app.post('/alexa', (req, res) => {
  • ...
  • const responseBody = {
  • "version": "1.0",
  • "response": {
  • "outputSpeech": {
  • "type": "SSML",
  • "ssml": "Botanalytics Rocks"
  • },
  • "directives": [
  • {
  • "type": "AudioPlayer.Play",
  • "playBehavior": "ENQUEUE",
  • "audioItem": {
  • "stream": {
  • "expectedPreviousToken": "...",
  • "token": "...",
  • "url": "https://botanalytics.co/",
  • "offsetInMilliseconds": 0
  • }
  • }
  • }
  • ],
  • }
  • Botanalytics.log(req.body, responseBody);
  • ...
  • res.send(responseBody);
  • };

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/amazon-alexa/

Python SDK with Lambda

COPY
Python SDK with Lambda
  • from botanalytics.amazon import AmazonAlexaLambda

  • botanalytics = AmazonAlexaLambda(debug=True,
  • token=os.environ['BOTANALYTICS_API_TOKEN'],
  • async_logging=True)

  • ...
  • botanalytics.log(request_payload, response_payload)
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/amazon-alexa/

Python SDK

COPY
Python SDK
  • from botanalytics.amazon import AmazonAlexa

  • botanalytics = AmazonAlexa(debug=True,
  • token=os.environ['BOTANALYTICS_API_TOKEN'],
  • callback=err_callback)

  • ...
  • botanalytics.log(request_payload, response_payload)
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/amazon-alexa/

Ruby SDK

COPY
Ruby SDK
  • require 'botanalytics'
  • botanalytics = Botanalytics::AmazonAlexa.new(
  • :debug => true,
  • :async => true,
  • :token => ENV['BOTANALYTICS_API_TOKEN'],
  • :callback => :error_callback)
  • ...
  • botanalytics.log(request_payload, response_payload)
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/amazon-alexa/

Microsoft Bot Framework V4



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • MicrosoftBotFramework(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const adapter = new BotFrameworkAdapter({
  • appId: process.env.MicrosoftAppId,
  • appPassword: process.env.MicrosoftAppPassword
  • });

  • // Use the middleware
  • adapter.use(Botanalytics.middleware);
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/microsoft-bot-framework/messages/

Language Understanding (LUIS)



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • MicrosoftBotFramework(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const luisApplication = {
  • applicationId: luisConfig.appId,
  • endpointKey: luisConfig.authoringKey,
  • endpoint: luisConfig.getEndpoint()
  • };

  • const adapter = new BotFrameworkAdapter({
  • appId: process.env.MicrosoftAppId,
  • appPassword: process.env.MicrosoftAppPassword
  • });

  • adapter.use(Botanalytics.middleware);
  • ...
  • let luisRecognizer = new LuisRecognizer(luisApplication,
  • luisPredictionOptions, true);
  • Botanalytics.useLuisRecognizer(luisRecognizer);
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/microsoft-bot-framework/messages/

Watson Assistant



We're accepting both IBM Watson Assistant V1 and V2 message payloads directly

Timestamp (in milliseconds) parameter can be inserted into IBM Watson Assistant message payloads to increase message time accuracies.

COPY
cUrl
  • curl --include \
  • --request PATCH \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"intents\": [..],
  • \"entities\":[..],
  • \"input\":[..],
  • \"output\":[..],
  • \"context\":[..],
  • \"user_id\": \"..\",
  • \"timestamp\":,
  • }" \
  • 'https://api.botanalytics.co/v1/watson-assistant/messages/'

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/watson-assistant/messages/

Twitter



Botanalytics provides one click integration for Twitter bots.

Slack



Slack Initialize

When you first connect slack via rtm.start, please initialize using this endpoint. Please keep in mind If you are using one of our official libraries this is done in the background.

COPY
cUrl
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"self\": {},
  • \"team\": {},
  • \"users\": [],
  • \"channels\": [],
  • \"groups\": [],
  • \"mpims\": [],
  • \"ims\": [],
  • \"bots\": []
  • }" \
  • 'https://api.botanalytics.co/v1/bots/slack/initialize/'
  • self

    required

    object

    Slack's rtm.start self

  • team

    required

    object

    Slack's rtm.start team

  • users

    required

    object

    Slack's rtm.start users

  • channels

    required

    object

    Slack's rtm.start channels

  • groups

    required

    object

    Slack's rtm.start groups

  • mpims

    required

    object

    Slack's rtm.start mpims

  • ims

    required

    object

    Slack's rtm.start ims

  • bots

    required

    object

    Slack's rtm.start bots

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/bots/slack/initialize/

Slack Rtm Api

COPY
Node.js
Python
Ruby
cUrl
  • const rtm = new RtmClient(CONFIG.slack.eventapi,{
  • dataStore: false,
  • useRtmConnect: true
  • });
  • const Botanalytics = require('botanalytics').
  • SlackRTMApi(process.env.BOTANALYTICS_TOKEN);

  • ...
  • Botanalytics.attach(rtm, console.error);
  • ...
  • object

    Slack's RTM Message object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/slack/

Slack Events Api

COPY
Node.js
Python
Ruby
cUrl
  • const Botanalytics = require('botanalytics').
  • SlackEventApi(process.env.BOTANALYTICS_TOKEN,
  • process.env.SLACK_BOT_TOKEN);

  • const slackEventHandler = function(request, h) {
  • ...
  • Botanalytics.log(request.payload);
  • ...
  • }
  • object

    Slack's Events API Message object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/slack/event/

Slack Events Api Button Click

COPY
Node.js
Python
Ruby
cUrl
  • const Botanalytics = require('botanalytics').
  • SlackEventApi(process.env.BOTANALYTICS_TOKEN,
  • process.env.SLACK_BOT_TOKEN);

  • const slackEventHandler = function(request, h) {
  • ...
  • Botanalytics.log(request.payload);
  • ...
  • }
  • const runServer = async () => {
  • server.route({
  • method: 'POST',
  • path : '/slack/interactive',
  • handler : function (request, h) {
  • ...
  • Botanalytics.log(JSON.parse(request.payload.payload));
  • return null;
  • }
  • });
  • ...
  • }
  • string

    Slack's Events API Button Click object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/slack/interactive/

Kik



Messages

COPY
Node.js
cURL
  • const Botanalytics = require('botanalytics').
  • Kik(process.env.BOTANALYTICS_TOKEN);

  • ...
  • let bot = new Bot({
  • username: process.env.KIK_USERNAME,
  • apiKey: process.env.KIK_APIKEY,
  • baseUrl: process.env.KIK_BASEURL
  • });
  • bot.updateBotConfiguration();
  • Botanalytics.attach(bot);
  • ...
  • messages

    required

    array

    Array of Kik's message object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/kik/

Node.js code example

User Profile

COPY
Node.js
cURL
  • const Botanalytics = require('botanalytics').
  • Kik(process.env.BOTANALYTICS_TOKEN);

  • ...
  • let bot = new Bot({
  • username: process.env.KIK_USERNAME,
  • apiKey: process.env.KIK_APIKEY,
  • baseUrl: process.env.KIK_BASEURL
  • });
  • bot.updateBotConfiguration();
  • Botanalytics.attach(bot);
  • ...
  • username

    required

    string

    Kik's user profile 'username'

  • firstName

    optional

    string

    Kik's user profile 'firstName'

  • lastName

    optional

    string

    Kik's user profile 'lastName'

  • profilePicUrl

    optional

    string

    Kik's user profile 'profilePicUrl'

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/kik/users/

Viber



Messages

COPY
Node.js
cURL
  • const Botanalytics = require('botanalytics').
  • Viber(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const bot = new ViberBot(logger, {
  • authToken: process.env.VIBER_PUBLIC_ACCOUNT_ACCESS_TOKEN_KEY,
  • name: "Is It Up",
  • avatar: "https://raw.githubusercontent.com/devrelv/drop/master/151-icon.png"
  • });
  • Botanalytics.attach(bot, (err) => {
  • console.log('Callback error: ' + util.inspect(err));
  • });
  • ...
  • message

    required

    string

    Viber's message object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/viber/

Node.js code example

User Profile

COPY
Node.js
cURL
  • const Botanalytics = require('botanalytics').
  • Viber(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const bot = new ViberBot(logger, {
  • authToken: process.env.VIBER_PUBLIC_ACCOUNT_ACCESS_TOKEN_KEY,
  • name: "Is It Up",
  • avatar: "https://raw.githubusercontent.com/devrelv/drop/master/151-icon.png"
  • });
  • Botanalytics.attach(bot, (err) => {
  • console.log('Callback error: ' + util.inspect(err));
  • });
  • ...
  • id

    required

    string

    Viber's user detail id

  • name

    optional

    string

    Viber's user detail name

  • avatar

    optional

    string

    Viber's user detail avatar

  • country

    optional

    string

    Viber's user detail country

  • language

    optional

    string

    Viber's user detail language

  • primary_device_os

    optional

    string

    Viber's user detail primary_device_os

  • api_version

    optional

    string

    Viber's user detail api_version

  • viber_version

    optional

    string

    Viber's user detail viber_version

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/viber/users/

Line



Incoming Messages

COPY
cURL
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"events\": [],
  • }" \
  • 'https://api.botanalytics.co/v1/messages/line/'
  • events

    required

    array

    Array of Line's event payload

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/line/

Outgoing Messages

COPY
cURL
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"request\": \"..\",
  • \"response\": \"..\",
  • }" \
  • 'https://api.botanalytics.co/v1/messages/line/'
  • to

    required

    string

    ID of the target recipient

  • timestamp

    required

    int

    Timestamp of the message

  • messages

    required

    array

    Array of Line's event payload

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/line/

User Profile

COPY
cURL
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • "displayName":"LINE taro",
  • "userId":"U4af4980629...",
  • "pictureUrl":"http://obs.line-apps.com/...",
  • "statusMessage":"Hello, LINE!"
  • }" \
  • 'https://api.botanalytics.co/v1/line/users/'
  • userId

    required

    string

    Line's user profile userId

  • displayName

    required

    string

    Line's user profile displayName

  • pictureUrl

    required

    optional

    Line's user profile pictureUrl

  • statusMessage

    optional

    string

    Line's user profile statusMessage

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/line/users/

WeChat



Messages

COPY
cURL
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"is_sender_bot\": true,
  • \"message\": {
  • }
  • }" \
  • 'https://api.botanalytics.co/v1/messages/wechat/'
  • message

    required

    object

    WeChat's message object

  • is_sender_bot

    required

    boolean

    true If sms is sent by Bot, false otherwise

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/wechat/

User Profile

COPY
cURL
  • curl --include \
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"openid\": \"o6_bmjrPTlm6_2sgVt7hMZOPfL2M\",
  • \"nickname\": \"Band\",
  • \"sex\": 1,
  • \"language\": \"zh_CN\",
  • \"city\": \"Guangzhou\",
  • \"province\": \"Guangdong\",
  • \"country\": \"China\",
  • \"headimgurl\": \"...",
  • \"subscribe_time\": 1382694957
  • }" \
  • 'https://api.botanalytics.co/v1/wechat/users/'
  • openid

    required

    string

    WeChat's user profile penid

  • nickname

    optional

    string

    WeChat's user profile nickname

  • sex

    optional

    int

    WeChat's user profile sex

  • language

    optional

    string

    WeChat's user profile language

  • city

    optional

    string

    WeChat's user profile city

  • province

    optional

    string

    WeChat's user profile province

  • country

    optional

    string

    WeChat's user profile country

  • headimgurl

    optional

    string

    WeChat's user profile headimgurl

  • subscribe_time

    optional

    int

    WeChat's user profile subscribe_time

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/wechat/users/

Twilio Sms



COPY
cURL
  • curl --include \
  • --request POST \
  • --header "Authorization: Token BOTANALYTICS_TOKEN" \
  • --data-binary "{
  • \"is_sender_bot\":
  • \"message\": {
  • }
  • }" \
  • 'https://api.botanalytics.co/v1/twilio/sms/messages/'
  • is_sender_bot

    required

    boolean

    true If sms is sent by Bot, false otherwise

  • message

    required

    object

    Twilio's sms object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/twilio/sms/messages/

Skype



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • MicrosoftBotFramework(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const adapter = new BotFrameworkAdapter({
  • appId: process.env.MicrosoftAppId,
  • appPassword: process.env.MicrosoftAppPassword
  • });

  • // Use the middleware
  • adapter.use(Botanalytics.middleware);
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/microsoft-bot-framework/messages/

Microsoft Teams



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • MicrosoftBotFramework(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const adapter = new BotFrameworkAdapter({
  • appId: process.env.MicrosoftAppId,
  • appPassword: process.env.MicrosoftAppPassword
  • });

  • // Use the middleware
  • adapter.use(Botanalytics.middleware);
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/microsoft-bot-framework/messages/

Telegram



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • MicrosoftBotFramework(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const adapter = new BotFrameworkAdapter({
  • appId: process.env.MicrosoftAppId,
  • appPassword: process.env.MicrosoftAppPassword
  • });

  • // Use the middleware
  • adapter.use(Botanalytics.middleware);
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/microsoft-bot-framework/messages/

Cortana



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • MicrosoftBotFramework(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const adapter = new BotFrameworkAdapter({
  • appId: process.env.MicrosoftAppId,
  • appPassword: process.env.MicrosoftAppPassword
  • });

  • // Use the middleware
  • adapter.use(Botanalytics.middleware);
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/microsoft-bot-framework/messages/

GroupMe



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • MicrosoftBotFramework(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const adapter = new BotFrameworkAdapter({
  • appId: process.env.MicrosoftAppId,
  • appPassword: process.env.MicrosoftAppPassword
  • });

  • // Use the middleware
  • adapter.use(Botanalytics.middleware);
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/microsoft-bot-framework/messages/

Bing



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • MicrosoftBotFramework(process.env.BOTANALYTICS_TOKEN);

  • ...
  • const adapter = new BotFrameworkAdapter({
  • appId: process.env.MicrosoftAppId,
  • appPassword: process.env.MicrosoftAppPassword
  • });

  • // Use the middleware
  • adapter.use(Botanalytics.middleware);
  • ...

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/microsoft-bot-framework/messages/

Generic



COPY
Python
Ruby
cUrl
  • from botanalytics.generic import Generic


  • botanalytics = Generic(debug=True,
  • token=os.environ['BOTANALYTICS_API_TOKEN'],
  • callback=err_callback,
  • async=True)

  • ...
  • botanalytics.log(message)
  • ...
  • is_sender_bot

    required

    boolean

    true If sms is sent by Bot, false otherwise

  • user

    required

    object

  • message

    required

    object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/generic/

Web Chat



COPY
Python
Ruby
cUrl
  • from botanalytics.generic import Generic


  • botanalytics = Generic(debug=True,
  • token=os.environ['BOTANALYTICS_API_TOKEN'],
  • callback=err_callback,
  • async=True)

  • ...
  • botanalytics.log(message)
  • ...
  • is_sender_bot

    required

    boolean

    true If sms is sent by Bot, false otherwise

  • user

    required

    object

  • message

    required

    object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/generic/

Sms



COPY
Python
Ruby
cUrl
  • from botanalytics.generic import Generic


  • botanalytics = Generic(debug=True,
  • token=os.environ['BOTANALYTICS_API_TOKEN'],
  • callback=err_callback,
  • async=True)

  • ...
  • botanalytics.log(message)
  • ...
  • is_sender_bot

    required

    boolean

    true If sms is sent by Bot, false otherwise

  • user

    required

    object

  • message

    required

    object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/generic/

Email



COPY
Python
Ruby
cUrl
  • from botanalytics.generic import Generic


  • botanalytics = Generic(debug=True,
  • token=os.environ['BOTANALYTICS_API_TOKEN'],
  • callback=err_callback,
  • async=True)

  • ...
  • botanalytics.log(message)
  • ...
  • is_sender_bot

    required

    boolean

    true If sms is sent by Bot, false otherwise

  • user

    required

    object

  • message

    required

    object

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/generic/

Rasa

There are two options to integrate Rasa with Botanalytics

OPTION 1: Endpoints.yml


This integration path only works if you have no event broker set up with Rasa. If you do have an event broker, please look at integrating Rasa via an event broker.

Install Botanalytics via Pip


If you have an python environment through virtualenv or anaconda (recommended) install pip, and then use the environment’s pip to install Botanalytics:

COPY
  • pip install botanalytics

Add Botanalytics to your endpoints.yml


Add a line to your endpoints.yml so that rasa-core is configured to send events to Botanalytics:

COPY
  • event_broker:
  • type: botanalytics.rasa.Rasa
  • api_token: BOTANALYTICS_TOKEN
  • debug: true

OPTION 2: Event Broker


Install Botanalytics via Pip


If you have an python environment through virtualenv or anaconda (recommended) install pip, and then use the environment’s pip to install Botanalytics:

COPY
  • pip install botanalytics

Include Botanalytics


COPY
  • from botanalytics.rasa import Rasa

Consume events with Botanalytics


COPY
  • def _callback(ch, method, properties, body):
  • event = json.loads(body)
  • db = Rasa(token=BOTANALYTICS_TOKEN)
  • db.publish(event)

ManyChat

  • 1-Go to Botanalytics and log in via Facebook because you can only connect your ManyChat bots through Facebook. You could either sign in via Facebook at this point or connect your Facebook account after you sign in via email.

  • 2- Make sure you authorize Botanalytics on Facebook when you are asked to. After this step, you'll see a list of the pages that you have admin permission. Choose the page you'd like to continue with and it's done! If you'd like to add a new FB bot later on, follow the steps explained below;

  • 3- Click on the “Add a new bot” button and fill in the required information. Make sure to choose Facebook Messenger as the platform and connect your Facebook account if you haven't already.

  • 4- Click on “Check connection”.

  • 5- If you see the check mark turning green and the “Integration Successful” message, you will be redirected to your dashboard.

  • 6- You're all set, integration is complete.

1-Go to Botanalytics and log in via Facebook because you can only connect your ManyChat bots through Facebook. You could either sign in via Facebook at this point or connect your Facebook account after you sign in via email.

2- Make sure you authorize Botanalytics on Facebook when you are asked to. After this step, you'll see a list of the pages that you have admin permission. Choose the page you'd like to continue with and it's done! If you'd like to add a new FB bot later on, follow the steps explained below;

3- Click on the “Add a new bot” button and fill in the required information. Make sure to choose Facebook Messenger as the platform and connect your Facebook account if you haven't already.

4- Click on “Check connection”.

5- If you see the check mark turning green and the “Integration Successful” message, you will be redirected to your dashboard.

6- You're all set, integration is complete.

Drift

  • 1-Login into your Drift account and click on “settings”.

  • 2-Navigate to Apps section through App Settings

  • 3-You’ll see Botanalytics in Apps list

  • 4-Click “Connect” to proceed

  • 5-Authorize App so that we can receive data from you

  • 6-Provide your bot’s details and save

  • 7-If it says “we need to receive data from you” when you click “check connection”, that means the integration is successful and we’re excitedly waiting for your conversational data to analyse. You can click on Dashboard to see your data.

  • 8-Voila, you’re all set!

1-Login into your Drift account and click on “settings”.

2-Navigate to Apps section through App Settings

3-You’ll see Botanalytics in Apps list

4-Click “Connect” to proceed

5-Authorize App so that we can receive data from you

6-Provide your bot’s details and save

7-If it says “we need to receive data from you” when you click “check connection”, that means the integration is successful and we’re excitedly waiting for your conversational data to analyse. You can click on Dashboard to see your data.

8-Voila, you’re all set!

Chatfuel

  • 1-Go to Chatfuel and click on the ‘’Analyze’’ tab on the right menu.

  • 2-Select the bot you want to connect to Botanalytics.

  • 3-Click on the ‘’Analyze’’ tab on the left menu.

  • 4-When you scroll down, you’ll see the ‘’Third-Party Analytics’’ title, click on ‘’Show Analytics Tools’’ button, Botanalytics will appear as shown below:

  • 5-Click on ‘’Connect’’ button to integrate your bot into Botanalytics.

  • 6-You'll be redirected to Facebook login page for Botanalytics, after click on the page your bot is associated, you will have your Chatfuel bot integrated into Botanalytics.

  • 7-Good to go! You’re all set.

1-Go to Chatfuel and login.

2-Select the bot you want to connect to Botanalytics.

3-Click on the ‘’Analyze’’ tab on the left menu

4-When you scroll down, you’ll see the ‘’Third-Party Analytics’’ title, click on ‘’Show Analytics Tools’’ button, Botanalytics will appear as shown below:

5-Click on ‘’Connect’’ button to integrate your bot into Botanalytics.

6-You'll redirected to Facebook login page for Botanalytics, after click on the page your bot is associated, you will have your Chatfuel bot integrated into Botanalytics.

7-Good to go! You’re all set.

BLiP

  • 1-Go to BLiP and click on the ‘’Analyze’’ tab on the right menu.

  • 2-Select the bot you want to connect to Botanalytics or create a new one.

  • 3-Click on the ‘’Integrations’’ tab on the right menu.

  • 4-Click on ‘’Connect’’ button to integrate your bot into Botanalytics.

  • 5-You'll be redirected to Botanalytics integration, click on the configuration tab, then you will need to enter your Botanalytics bot's token and click save button.

  • 6-Click on activate toggle to make integration active

  • 7-Good to go! You’re all set.

1-Go to BLiP and login.

2-Select the bot you want to connect to Botanalytics or create a new one.

3-Click on the ‘’Integrations’’ tab on the right menu.

4-Click on ‘’Connect’’ button to integrate your bot into Botanalytics.

5-You'll be redirected to Botanalytics integration, click on the configuration tab, then you will need to enter your Botanalytics bot's token and click save button.

6-Click on ‘’Activate’’ toggle to make integration active

7-Good to go! You’re all set.

Smooch

  • 1-Login into your Smooch account. Select your application. As shown below, click the ''Connect channels'' button.

  • 2-After you click, you can select Botanalytics under the ''Build A Bot'' category from the integrations page.

  • 3-Click ''Visit to Install'' button on Botanalytics' profile page on Smooch.io as shown below:

  • 4-After it directs you to sign up for Botanalytics, fill out the signup form with your credentials.

  • 5-You can select the app you would like to integrate on the connection page.

  • 6-Allow the app connection to move forward with the integration steps. If you click ''Deny'', it will cancel the integration. You will have to start over.

  • 7-Your bot integration is set. On the page below, check your connection to have your metrics measured.

  • 8-Wait for a while to see your data on Botanalytics. When your bot processes the data on Smooch.io, Botanalytics will receive and you'll start to see your dashboard and metrics.

  • 9-You're all set.

1-Login into your Smooch account. Select your application. As shown below, click the ''Connect channels'' button.

2-After you click, you can select Botanalytics under the ''Build A Bot'' category from the integrations page.

3-Click ''Visit to Install'' button on Botanalytics' profile page on Smooch.io as shown below:

4-After it directs you to sign up for Botanalytics, fill out the signup form with your credentials.

5-You can select the app you would like to integrate on the connection page.

6-Allow the app connection to move forward with the integration steps. If you click ''Deny'', it will cancel the integration. You will have to start over.

7-Your bot integration is set. On the page below, check your connection to have your metrics measured.

8-Wait for a while to see your data on Botanalytics. When your bot processes the data on Smooch.io, Botanalytics will receive and you'll start to see your dashboard and metrics.

9-You're all set.

Smartloop

  • 1-Login into your Smartloop account.

  • 2-Select the bot you want to connect to Botanalytics or create a new one.

  • 3-Click on the ‘’CONFIGURE’’ button on the left menu.

  • 4-In the Configure page scroll down to see ‘’THIRD-PARTY ANALYTICS’’ on the right side of the screen

  • 5-Select botanalytics tab from the ‘’THIRD-PARTY ANALYTICS’’, then you will need to enter your Botanalytics bot's token and click ‘’Connect’’ button.

  • 6-You're all set.

1-Login into your Smartloop account.

2-Select the bot you want to connect to Botanalytics or create a new one..

3-Click on the ‘’CONFIGURE’’ button on the left menu.

4-In the Configure page scroll down to see ‘’THIRD-PARTY ANALYTICS’’ on the right side of the screen

5-Select botanalytics tab from the ‘’THIRD-PARTY ANALYTICS’’, then you will need to enter your Botanalytics bot's token and click ‘’Connect’’ button.

6-You're all set.

Amio

  • 1-Login into your Amio account. Select an existing channel or create new one.

  • 2-In Integrations tab click on Connect Integration.

  • 3-Select Botanalytics from the integration list

  • 4-Fill required fields: Name, Token and Channel, and click Connect. You can see the details here

  • 5-Wait for a while to see your data on Botanalytics. When your bot processes the data on Amio.io, Botanalytics will receive and you'll start to see your dashboard and metrics.

  • 6-You're all set.

1-Login into your Amio account. Select an existing channel or create new one.

2-In Integrations tab click on Connect Integration.

3-Select Botanalytics from the integration list

4-Fill required fields: Name, Token and Channel, and click Connect. You can see the details here

5-Wait for a while to see your data on Botanalytics. When your bot processes the data on Amio.io, Botanalytics will receive and you'll start to see your dashboard and metrics.

6-You're all set.

Amazon Lex



COPY
Node.js
  • const Botanalytics = require('botanalytics').
  • AmazonLex(process.env.BOTANALYTICS_TOKEN);

  • exports.handler = (event, context, callback) => {
  • ...
  • dispatch(event, (response) => {
  • Botanalytics.log(event, context, response);
  • });
  • ...
  • };

Header Authorization:Token BOTANALYTICS_TOKEN

Posthttps://api.botanalytics.co/v1/messages/amazon-lex/

Node.js code example