Receive and send messages

You can use the Bot Connector API to connect your bot to multiple channels, such as Messenger, Slack or Kik.

Once you've connected your bot to channels on the platform, you can use this SDK to receive and send messages.

Usage

Start by instantiating either a Client or a Connect object, as shown below:

var sapcai = require('sapcai').default

var client = new sapcai('YOUR_TOKEN')
var connect = client.connect

// ...is the same as...

var connect = new sapcai.connect('YOUR_TOKEN')

Connect

You can now connect your bot, access all incoming messages and send replies accordingly.

This SDK currently works with Express and Koa >= 2.0.0. If you use another http server package, feel free to open an issue or a pull request, all contributions are welcome. :-)

You can find more details on the message format your bot can send here.

Express

var express = require('express')
var bodyParser = require('body-parser')
var sapcai = require('sapcai').default

var connect = new sapcai.connect('YOUR_TOKEN')

var app = express()

/* Server setup */
app.use(bodyParser.json())
app.post('/', function(req, res) {
  connect.handleMessage(req, res, onMessage)
})

function onMessage (message) {
  // Get the content of the message
  var content = message.content

  // Get the type of the message (text, picture,...)
  var type = message.type

  // Add a reply, and send it
  message.addReply([{ type: 'text', content: 'Hello, world' }])
  message.reply()
    .then(res => console.log('message sent'))
}

Koa

var Koa = require('koa')
var bodyParser = require('koa-bodyparser')
var sapcai = require('sapcai').default

var connect = new sapcai.connect('YOUR_TOKEN')

var app = new Koa()

/* Server setup */
app.use(bodyParser())
app.use(function(ctx) {
  connect.handleMessage(ctx.request, ctx.response, onMessage)
})
app.listen(8080)

function onMessage (message) {
  // Get the content of the message
  var content = message.content

  // Get the type of the message (text, picture,...)
  var type = message.type

  // Add a reply, and send it
  message.addReply([{ type: 'text', content: 'Hello, world' }])
  message.reply()
    .then(res => console.log('message sent'))
}

Connect with SAP Conversational AI

This is a small example using both the Connect and the Request APIs to receive messages from a channel, send the content to SAP Conversational AI to get back the bot reply, and send it back to the channel.

var express = require('express')
var bodyParser = require('body-parser')
var sapcai = require('sapcai').default

var client = new sapcai('YOUR_TOKEN')

var app = express()

/* Server setup */
app.use(bodyParser.json())
app.post('/', function(req, res) {
  client.connect.handleMessage(req, res, onMessage)
})

function onMessage (message) {
  // Get the content of the message
  var content = message.content
  // Get the type of the message
  var type = message.type
  // Get the senderId, which we'll use as a conversation token.
  var conversationToken = message.senderId

  // If it's a text message...
  if (type === 'text') {
    // ...make a request to SAP Conversational AI to get the bot reply...
    client.request.converseText(content, { conversationToken: conversationToken })
      .then(function(res) {
        // ...extract the reply...
        var reply = res.reply()

        // ...and send it back to the channel
        message.addReply([{ type: 'text', content: reply }])
        message.reply()
          .then(res => console.log('message sent'))
      })
  }
}

Methods

Send messages to a specific conversation

Method	Params	Return
sendMessage(messages, conversationId)	messages: Array[object], conversationId: String	object: the API response

This methods allow you to push a message to a specific conversation.

const messages = [
  {
    type: 'text',
    content: 'Roger that',
  }
]

connect.sendMessage(messages, 'A_CONVERSATION_ID')
  .then(function(){
    console.log('Message successfully sent')
  })
  .catch(function() {
    console.log('An error occured while sending message')
  })

Broadcast messages to all bot conversations

Method	Params	Return
broadcastMessage(messages)	messages: Array[object]	object: the API response

This method allow you to push a message to all the conversations of your bot.

connect.broadcastMessage(messages)
  .then(function() {
    console.log('Message successfully sent')
  })
  .catch(function() {
    console.log('An error occured while sending message')
  })

Message

A Message object is what you receive in the Connect#handleMessage callback.

Attributes

An instance of the Message class provides each of the following attributes:

Attributes	Type
content	String: the content of the message
type	String: the type of the message
conversationId	String: the id of the conversation this message belongs to
sapcaiToken	String: the SAP Conversational AI token of the bot
chatId	String: the native ID of the chat
senderId	String: the native ID of the message's sender
attachment	Object: the raw content of the message

Methods

Add a reply to the message's array of replies

Method	Params	Return
addReply(messages)	messages: Array[object]	nothing

var express = require('express')
var bodyParser = require('body-parser')
var sapcai = require('sapcai').default

var client = new sapcai('YOUR_TOKEN')

var app = express()

/* Server setup */
app.use(bodyParser.json())
app.post('/', function(req, res) {
  client.connect.handleMessage(req, res, onMessage)
})

function onMessage (message) {
  var payload = [
    { type: 'text', content: 'Hello' },
    { type: 'picture', content: 'MY_URL_IMAGE' },
  ]
  // Add the replies...
  message.addReply(payload)
  
  // ...and send them
  message.reply()
}

Send replies from the message

Method	Params	Return
reply(messages)	messages: Array[object]

var express = require('express')
var bodyParser = require('body-parser')
var sapcai = require('sapcai').default

var client = new sapcai('YOUR_TOKEN')

var app = express()

/* Server setup */
app.use(bodyParser.json())
app.post('/', function(req, res) {
  client.connect.handleMessage(req, res, onMessage)
})

function onMessage (message) {
  var payload = [
    { type: 'text', content: 'Hello' },
    { type: 'picture', content: 'MY_URL_IMAGE' },
  ]
  message.addReply(payload)
  message.reply()

  //...is the same as...

  message.reply(payload)
}