Consume

InterBot enables you to use services of other bots or interact with the bots already published on the InterBot directory. You can use the InterBot APIs to consume other bots that are on the InterBot channel.

Do note that your bot has to be already published on InterBot to consume other bots. Read this page to learn how.

This guide will illustrate how you can use the InterBot APIs to send and receive a message from another bot already on the InterBot directory. The APIs you will need to use are:

  • POST /bot/{botname}/refid

  • POST /bot/{botname}/sendmsg

The base URL for above InterBot APIs is: https://ibc.interbot.cc/ibc/

In addition you will also need to use the Gupshup Send Message API

  • POST /sm/api/bot/{botname}/msg

The base URL for the above API is https://api.gupshup.io

  1. Create a bot on Gupshup:

    For this guide, we will create a bot named ‘utilityBot’ that communicates with a translation bot already published on the Interbot channel named ‘engtospanishbot’. Create ‘utilityBot’ on Gupshup. To familiarize yourself with the bot creation process on Gupshup, read this guide. Here’s a diagram that illustrates the sequence of how the bots communicate via InterBot:

  2. The InterBot sendmsg API

    We will use the sendmsg API to send messages to other bots on InterBot. This is the API:

    POST /bot/{botname}/sendmsg

    The API has 4 required parameters and 1 optional parameter:

    • apikey: Your API key on Interbot. It is usually auto-filled but you can find it on the top right corner of the Interbot portal, when you click on your user profile pic.

    • botname: The name of the bot that is sending out the message to another bot. In this case it will be ‘utilityBot’.

    • destbotname:The name of the bot to be communicated with. Here the destbotname is ‘engtospanishbot'

    • refid: The reference ID. Each message has a unique refid. We have an API that generates refid for every message. This parameter is optional

    • message: The message to be sent to the destination bot.

    This API’s response returns a status code of 200 if successful.

    In our ‘utilityBot’, we will make a call to the InterBot sendmsg API using the above parameters, after generating a refid. To generate a refid, we shall use the refid API:

    POST /bot/{botname}/refid

    This API's response body contains the refid that you will use. Here's the code to generate a refid

    var botName = "utilityBot"; 
    var envurl = "https://ibc.interbot.cc/ibc/bot/";
    var apikey = "YOUR-API-KEY";
    
    function generateRefid(cb){
        var url = envurl+botName+'/refid';
        var headers = {
            'content-type': 'application/x-www-form-urlencoded',
            'apikey': apikey
        }
        context.simplehttp.makePost(url, "", headers,cb);
    }
    							
    						

    Whenever a user sends a message, it has to be passed on to the destination bot. Thus in the messageHandler() method, we shall first generate a refid and then make a call to the sendmsg API. Once that is done, we will store the refid (for use later) and then make a call to the InterBot sendmsg API. Here’s how the messageHandler() function will look:

    function MessageHandler(context, event) {
        var _event = event;
        var _context = context;
        generateRefid(function(context,event){
            var refid = String(event.getresp);
            context.simpledb.botleveldata[refid] = JSON.stringify(_event.contextobj);
            context.simpledb.saveData(sendIBCMessage(context,destbotname,refid,_event.message));
        }); 
    }
    function generateRefid(cb){
        var url = envurl+botName+'/refid';
        var headers = {
            'content-type': 'application/x-www-form-urlencoded',
            'apikey': apikey
        }
        context.simplehttp.makePost(url, "", headers,cb);
    }
    
    function sendIBCMessage(context,recipientName,refid,message) {
        context.console.log("Inside sendIBCMessage : message : "+message);
        var url = envurl+botName+'/sendmsg';
        var headers = {
            'content-type': 'application/x-www-form-urlencoded',
            'apikey': apikey
        }
        var formData = 'refid=' + refid + '&message=' + message+'&destbotname='+recipientName;
        context.simplehttp.makePost(url, formData, headers);
    }
  3. Receive messages from a bot

    Assume the user sent 'utilityBot' a message with the words 'Hola Amigo'. In the above code, this message is then sent from 'utilityBot' to ‘engtospanishbot' which is programmed to reply with an English translation. This message is relayed back to 'utilityBot' through the messageHandler() function. Any message that is a reply to an InterBot message will have the event.contextobj.channeltype = 'ibc'. Also, the refid and the event.contextobj will be unique. The refid and the contextobj has to be verified before the Gupshup Send Message API is used.

    var channelName = event.contextobj.channeltype;
        var senderName = event.senderobj.channelid;
        if(channelName == "ibc"){
            var refid = event.contextobj.refid;
            var userContextStr = context.simpledb.botleveldata[refid];
            var userContext = JSON.parse(userContextStr);
            delete context.simpledb.botleveldata[refid];
            context.simpledb.saveData(sendMsg(context,userContextStr,event.message));
    }
    
    Do note that the Gupshup Send Message API is different from the InterBot sendMsg API

    Here are the details of the Gupshup Send Message API:

    POST /sm/api/bot/{botname}/msg

    The API has 3 parameters which are all required. Here are the details:

    -botname: The name of the bot that you are sending a message to

    -context: The context object

    -message: The message to be sent

    function sendMsg(context,userContext,message){
        var url = botenvurl+botName+'/msg';
        var headers = {
            'content-type': 'application/x-www-form-urlencoded',
            'apikey': apikey
        }
        var formData = 'context=' + userContext + '&message=' + message+"&bypass=false";
        context.simplehttp.makePost(url, formData, headers);
  4. Putting it all together

    Now that we have seen how you can send and receive messages from another bot, we can put all this code together. You can of course communicate to different bots based on your requirement. Below is the entire code for the processes described above:

    /** This is a sample code for your bot**/
    var apikey = "YOUR-API-KEY";
    var botName = "utilityBot"; 
    var envurl = "https://ibc.interbot.cc/ibc/bot/";
    var botenvurl = "https://api.gupshup.io/sm/api/v1/bot/";
    var destbotname = "engtospanishbot";
    
    function MessageHandler(context, event) {
        var channelName = event.contextobj.channeltype;
        var senderName = event.senderobj.channelid;
    
        if(channelName == "ibc"){
            var refid = event.contextobj.refid;
            var userContextStr = context.simpledb.botleveldata[refid];
    
            var userContext = JSON.parse(userContextStr);
            delete context.simpledb.botleveldata[refid];
            context.simpledb.saveData(sendMsg(context,userContextStr,event.message));
    
        }else{
            var _event = event;
            var _context = context;
            generateRefid(function(context,event){
                var refid = String(event.getresp);
                context.simpledb.botleveldata[refid] = JSON.stringify(_event.contextobj);
                context.simpledb.saveData(sendIBCMessage(context,destbotname,refid,_event.message));
            }); 
        }
    }
    
    function generateRefid(cb){
        var url = envurl+botName+'/refid';
        var headers = {
            'content-type': 'application/x-www-form-urlencoded',
            'apikey': apikey
        }
        context.simplehttp.makePost(url, "", headers,cb);
    }
    
    function sendIBCMessage(context,recipientName,refid,message) {
        context.console.log("Inside sendIBCMessage : message : "+message);
        var url = envurl+botName+'/sendmsg';
        var headers = {
            'content-type': 'application/x-www-form-urlencoded',
            'apikey': apikey
        }
        var formData = 'refid=' + refid + '&message=' + message+'&destbotname='+recipientName;
        context.simplehttp.makePost(url, formData, headers);
    }
    
    function sendMsg(context,userContext,message){
        context.console.log("Inside sendMsg : message : "+message);
    
        var url = botenvurl+botName+'/msg';
        var headers = {
            'content-type': 'application/x-www-form-urlencoded',
            'apikey': apikey
        }
        var formData = 'context=' + userContext + '&message=' + message+"&bypass=false";
        context.simplehttp.makePost(url, formData, headers);
    }
    
    
    /** Functions declared below are required **/
    function EventHandler(context, event) {
    
    }
    
    function HttpResponseHandler(context, event) {
    
    }
    
    function DbGetHandler(context, event) {
        //context.sendResponse("testdbput keyword was last get by:" + event.dbval);
    }
    
    function DbPutHandler(context, event) {
        //context.sendResponse("testdbput keyword was last put by:" + event.dbval);
    }

    We've hosted some use cases & Bot code snippets on Github. This will help developers to quickly get started with building their first InterBot bots. Check it out at https://github.com/GupshupBot/InterBot

function MessageHandler(context, event) { } function EventHandler(context, event) { } function HttpResponseHandler(context, event) { } function DbGetHandler(context, event) { } function DbPutHandler(context, event) { }
function MessageHandler(context, event) { var channelName = event.contextobj.channeltype; var senderName = event.senderobj.channelid; context.console.log("refid : "+refid+" ; senderName : "+senderName); var ibcbots = botmap.split("|"); var position = ibcbots.indexOf("@"+senderName); var nextBot = ibcbots[position+1] var lastBot = ibcbots[ibcbots.length-1].replace(/@/g,""); context.console.log("nextBot : "+nextBot); if(channelName == "ibc"){ var refid = event.contextobj.refid; if(position < 0 && senderName!=botName){ //IBC Init Point if(!context.simpledb.botleveldata[refid]){ context.simpledb.botleveldata[refid]=senderName; context.simpledb.saveData(sendIBCMessage(context,ibcbots[0].replace(/@/g,""),refid,event.message)); }else{ delete(context.simpledb.botleveldata[refid]) return; } }else if(nextBot){ sendIBCMessage(context,nextBot.replace(/@/g,""),refid,event.message); }else{ recBotname = context.simpledb.botleveldata[refid]; try{ var userContext = JSON.parse(recBotname); delete context.simpledb.botleveldata[refid]; context.simpledb.saveData(sendMsg(context,recBotname,event.message)); }catch(err){ delete context.simpledb.botleveldata[refid]; context.simpledb.saveData(sendIBCMessage(context,recBotname,refid,event.message)); } } }else{ var _event = event; var _context = context; generateRefid(function(context,event){ var refid = String(event.getresp); context.simpledb.botleveldata[refid] = JSON.stringify(_event.contextobj); context.simpledb.saveData(sendIBCMessage(context,ibcbots[0].replace(/@/g,""),refid,_event.message)); }); } } function generateRefid(cb){ var url = envurl+botName+'/refid'; var headers = { 'content-type': 'application/x-www-form-urlencoded', 'apikey': apikey } context.simplehttp.makePost(url, "", headers,cb); } function sendIBCMessage(context,recipientName,refid,message) { var url = envurl+botName+'/sendmsg'; var headers = { 'content-type': 'application/x-www-form-urlencoded', 'apikey': apikey } var formData = 'refid=' + refid + '&message=' + message+'&destbotname='+recipientName; context.simplehttp.makePost(url, formData, headers); } function sendMsg(context,userContext,message){ var url = botenvurl+botName+'/msg'; var headers = { 'content-type': 'application/x-www-form-urlencoded', 'apikey': apikey } var formData = 'context=' + userContext + '&message=' + message+"&bypass=true"; context.simplehttp.makePost(url, formData, headers); } /** Functions declared below are required **/ function EventHandler(context, event) {} function HttpResponseHandler(context, event) {} function DbGetHandler(context, event) {} function DbPutHandler(context, event) {}