NAV
javascript shell

Introduction

Quick start

Get an Url for your bot

To be able to receive messages, your bot will have to run on a server online. If you want to do it in local, you can download ngrok and run it on the port you want. Leave the windows running, and use the secured Url for the next step.

console ngrok

Create bots

To create a new bot, log on the Connector and click on the blue button “+ NEW BOT”

create bot

Create channels

Select your bot on the right of the screen, and then select which channel you want your bot to be connected at (Messenger, Slack or Kik for example).

create channel

Once you have selected the type of channel you want to create, you have to fill the form on the left of the screen, in the ‘Connect’ tab.

The fields will change according to the channel you want to create. A simple tutorial will guide you to each channel, and will show you how to find the various information you need.

Repeat the process for every connections you want to add.

How it works

When your bot receive a message

incoming message

When your bot send a message

outgoing message

SDKs

An open-source Node.JS SDK is available on github. You can find more information in the README and the Wiki of the repository.

Language Latest version Repositories
NodeJS 1.0.1 Github - NPM

Contribute

The BotConnector is open-source, and can be found here on Github.

Contributions are always welcome, no matter how large or small, from everyone. If you’d like to help make Connector better, you totally rock! Here are some ways to contribute:

You can find more information here.

Messages

Incoming messages

How to

const express = require('express')
const bodyParser = require('body-parser')
const request = require('superagent')

const app = express()
app.set('port', process.env.PORT || 5000)
app.use(bodyParser.json())

app.post('/', (req, res) => {
  console.log(req.body)
})

app.listen(app.get('port'), () => {
  console.log('Our bot is running on port', app.get('port'))
})

Messages will be sent to the endpoint Url you’ve set during the bot creation. To catch them, you have to listen post requests coming to your server. The body will contain the precious message.

Format

Format

{
  "message": {
    "participant": "PARTICIPANT_ID",
    "conversation": "CONVERSATION_ID",
    "attachment": {
      "content": "hi",
      "type": "text"
    },
    "createdAt": "2016-12-10T16:58:46.043Z"
  }
}

Your bot will always receive the same format of message, no matter from which channel it comes from. Here’s an example:

Outgoing messages

How to

To send a message, you need to make a post request with your bot id, your user slug, and your user token. You can find them easily on your homepage. You also need to provide the id of the recipient and the id of the conversation. You can find them in the body of an incoming message.

app.post('/', (req, res) => {
  const conversation = req.body.message.conversation
  const message = [{
    type: 'text',
    content: 'my first message',
  }]

  request.post('https://api-botconnector.recast.ai/users/' + userSlug + '/bots/' + botId + '/conversations/' + conversation '/messages')
    .set({ 'Authorization': userToken })
    .send({ message, senderId: req.body.senderId })
    .end((err, res) => {
      if (err) {
        console.log(err)
      } else {
        console.log(res)
      }
    })
})

create bot

Format

Text message

{
  "type": "text",
  "content": "STRING"
}

Quick Reply message

{
  "type": "quickReplies",
  "content": {
    "title": "STRING",
    "buttons": [
      {
        "title": "STRING",
        "value": "STRING"
      }
    ]
  }
}

Picture message

{
  "type": "picture",
  "content": "STRING"
}

Video message

{
  "type": "video",
  "content": "STRING"
}

Card message

{
  "type": "card",
  "content": {
    "title": "STRING",
    "imageUrl": "STRING",
    "buttons": [
      {
        "title": "SEE ON THE LEFT",
        "type": "SEE ON THE LEFT",
        "value": "SEE ON THE LEFT"
      }
    ]
  }
}

You can send multiple types of message, from a simple text to a more elaborated card. The BotConnector will then adapt the content of your message to the channel it’s destined at. You can see examples of the different messages formats on the right of the screen.

Note that the type field of buttons in cards can be:

API

Requests

Responses

On the right you can see examples of responses returned by the API.

Renders a collection

{
  "results": [
    {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "url": "https://MY_BOT_URL.com",
      "name": "bot-1"
    },
    {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "url": "https://MY_BOT_URL.com",
      "name": "bot-2"
    }
  ],
  "message": "Bots successfully found"
}

Renders a resource

{
  "results": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "bot-1",
    "url": "https://MY_BOT_URL.com",
    "channels": [],
    "conversations": []
  },
  "message": "Bot successfully found"
}

Renders an error

{
  "results": null,
  "message": "Parameter id is invalid"
}

Format

All responses have the same format, containing two keys: results and message.

In results, we provide the answer of your request.

In message, we provide information about the response (See Status codes).

When requesting a collection or a resource, the results key will respectively contain an array of resources or a resource.

Request Variable Resource  Type
Collection results Found Array: [{}, ...]
results Empty Empty array: []
message   String
Model results Found Object: {"id":1, ...}
results Empty null
message   String

Status codes

Every request will have one of these status codes:

Code Name Response message Description
200 Success Resource successfully rendered Returned when resource is successfully rendered.
200 Success No Resource Returned when collection is successfully rendered but empty.
200 Success Resource successfully deleted Returned when resource is successfully deleted.
201 Created Resource successfully created Returned when resource is successfully created.
400 Bad Request Request is invalid. Returned if a request parameter is invalid.
401 Unauthorized Request can not be processed without authentication. Returned if you are not authenticated.
403 Forbidden Request can not be processed with your role. Returned if you do no have sufficient permissions with your role.
404 Not found Resource not found. Returned if request or resource is not found.
500 Internal Server Error Internal server error. Returned if a server error occured.
504 Timeout Service timeout Returned if a service timeout.

In cases of 2xx status codes, Resource is replaced by the resource name (e.g: Bots successfully rendered).

Authentication

Your can access to BotConnector’s API with your user token.

All your requests must contain a header called Authorization, with a value of this form: Token USER_TOKEN.

/bots

{
  "results": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "bot-1",
    "url": "https://MY_BOT_URL.com",
    "channels": [],
    "conversations": []
  },
  "message": "Bot successfully found"
}

This endpoint manages bots.

Bot model

Variable Type Description Constraints
id Mongoose Id An unique bot id 
name String The bot name  
url String The bot’s endpoint
channels Array of Channel The bot Channels
conversations Array of Conversation The bot Conversations

Getting an user’s bot

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID

This call returns a bot model in the results field.

Getting an user’s bots

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID

This call returns a collection of bot models in the results field.

Updating a bot

curl -H "Authorization: Token USER_TOKEN" \
     -d "{name=NAME,url=URL}" \
     -X PUT "https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID"
var request = require('superagent');

request
  .put('https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID')
  .send({
    name: NAME,
    url: URL,
  })
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

PUT https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID

This call returns a bot model in the results field.

Deleting a bot

curl -H "Authorization: Token USER_TOKEN" \
     -X DELETE "https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID"
var request = require('superagent');

request
  .delete('https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID

This call does not return any content.

/channels

{
  "results": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "bot": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "slug": "my-channel",
    "type": "slack",
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "isActivated": true,
  },
  "message": "Channel successfully rendered"
}

This endpoint manages channels.

Channel model

Variable Type Description
id Mongoose Id An unique channel id 
bot Mongoose Id The bot Id  
slug String The channel’s name
isActivated Boolean The channel state

Getting a bot’s channel

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG

This call returns a channel model in the results field.

Getting a bot’s channels

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/channels"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/channels')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/channels

This call returns a collection of channel models in the results field.

Updating a channel

curl -H "Authorization: Token USER_TOKEN" \
     -d "{isActivated=true,slug=SLUG}" \
     -X PUT "https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG"
var request = require('superagent');

request
  .put('https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG')
  .send({
    isActivated: ISACTIVATED,
    slug: SLUG,
  })
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

PUT https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG

This call returns a channel model in results variable.

Deleting a channel

curl -H "Authorization: Token USER_TOKEN" \
     -X DELETE "https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG"
var request = require('superagent');

request
  .delete('https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/channels/$CHANNEL_SLUG

This call does not return any content.

/conversations

{
  "results": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "bot": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "chatId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "channel": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "participants": [],
    "messages": []
  },
  "message": "Conversation successfully rendered"
}

This endpoint manages conversations.

Conversation model

Variable Type Description
id Mongoose Id An unique conversation id 
bot Mongoose Id The bot Id  
channel Mongoose Id The channel Id  
chatId String The native ChatId
participants Array of Participant An array of participants
messages Array of Message An array of messages

Getting a bot’s conversation

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID

This call returns a conversation model in results variable.

Getting a bot’s conversations

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations

This call returns a collection of conversations models in results variable.

Deleting a conversation

curl -H "Authorization: Token USER_TOKEN" \
     -X DELETE "https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID"
var request = require('superagent');

request
  .delete('https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api-botconnector.recast.ai/v1/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID

This call does not return any content.

/messages

{
  "results": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "attachment": {
      "content": "hello",
      "type": "text"
    },
    "participant": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "conversation": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "message": "Message successfully posted"
}

This endpoint manages messages.

Message model

Variable Type Description
id Mongoose Id An unique message id 
conversation Mongoose Id The conversation Id  
participant Mongoose Id The participant Id  
attachment Object The content of the Message

Posting a Message to a Bot’s Conversation

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID/messages"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID/messages')
  .post({
    [
      {
        type: 'text',
        content: 'hello',
      }
    ]
  })
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/conversations/$CONVERSATION_ID/messages

This call returns a message model in results variable.

Posting a Message to every Bot’s Conversations

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/messages"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/messages')
  .post({
    [
      {
        type: 'text',
        content: 'hello',
      }
    ]
  })
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/messages

This call returns a message model in results variable.

/participants

{
  "results": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "senderId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "isBot": false
  },
  "message": "Participant successfully rendered"
}

This endpoint manages messages.

Participant model

Variable Type Description
id Mongoose Id An unique participant id 
senderId String The native ParticipantId  
isBot Boolean The participant’s state 

Getting a participant

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/participants/$PARTICIPANT_ID"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/participants/$PARTICIPANT_ID')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/participants/$PARTICIPANT_ID

This call returns a participant model in results variable.

Getting participants

curl -H "Authorization: Token USER_TOKEN" \
     -X GET "https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/participants"
var request = require('superagent');

request
  .get('https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/participants')
  .send()
  .set('Authorization', 'Token USER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api-botconnector.recast.ai/users/$USER_SLUG/bots/$BOT_ID/participants/$PARTICIPANT_ID

This call returns an array of participant models in results variable.