Custom Integrations · Documentation

A custom integration is a piece of software built on top of the Botsociety API that allows users to export their Botsociety design to their platform of choice. The Botsociety team released two of them - the Dialogflow and the Rasa integrations - but you can build your own. The custom integration is written by you but it runs on the Botsociety servers. You can make your custom integration private or public.

Custom integration example

Getting started

The Botsociety2 API is currently in developer preview. If you want to be added to the development preview, fill out this form.

A custom integration is a NodeJS application built on top of the Botsociety API that can run by itself using serverless.

A good place to start developing your custom integration is the open source boilerplate that you can find here on Github. Git clone it on your computer:

git clone git@github.com:botsociety/botsociety-integration-js-boilerplate.git

You will find a file called handler.js. You can edit it to customize your integration:

  //[...]
  const { user_id, api_key_public } = headers
  const body = prop('body', event)
  // You can write your custom integration here

Your integration can call your own API, or return a file.

Once you are done, you can try your custom integration with:

npm start

Do you want to write a custom integration in a language that is not NodeJS? Drop us a line at info@botsociety.com

Developing your custom integration

Your custom integration is a piece of software that runs on serverless when a user clicks on 'Export' in the Build Mode, while having your custom integration selected. When a user clicks on export, Botsociety will send a POST request to your custom integration, on the endpoint /export. The POST will be formatted as follows:

headers: {
  user_id: "The user id of the user who triggered the integration",
  api_key_public: "The Botsociety API api key of the user who triggered the integration"
},
body: {
    domain: "app.botsociety.io", // the domain from which the request originated
    welcomePathId: "you can specify here a path id for your integration", // Optional: The Id of the path selected by the user as the WelcomePath
    designId: "The designId of the design file from where the custom request originated",
    callbackUrl: "" // You will call this endpoint with the result of your request. Note that this is a relative URL and you will need to combine it with the domain above
}

Botsociety then expects your integration to return a 200 Response to this POST. The 200 Response should be as fast as possible, and it represents only that the request has been recevied correctly. Once your integration code has run (either exporting to an API or via file), Botsociety expects to receive a POST call on the callbackUrl. The parameters change a little bit depending if your integration exports to a file that the user downloads, or if your integration calls a third-party API.

To trigger a file download, send a POST to the callbackUrl to the domain defined in the previous call with these parameters:

headers: {
  'Content-Type': 'application/json',
  user_id: "You have this from the call that Botsociety gave you",
  api_key_public: "You have this from the call that Botsociety gave you"
},
body: {
    type: 'file_dowload'
    file: '', // Optional: If your application exports to a file that the user downloads, put the file base64 encoded here
    file_name: 'export.csv', // Optional: If your application exports to a file that the user downloads, put the file name with extension here
}

To notify that the third party API export was successful, send a POST to the callbackUrl to the domain defined in the previous call with these parameters:

headers: {
  'Content-Type': 'application/json',
  user_id: "You have this from the call that Botsociety gave you",
  api_key_public: "You have this from the call that Botsociety gave you"
},
body: {
    type: 'api',
    message: '', //optional: If you want to show a custom confirmation message to the user, put it here
}

Testing your custom integration

Start serverless in your local environment, then call your localhost with a POST on the endpoint /dev/export with those parameters:

{
  headers: {
    user_id: "your Botsociety API user id",
    api_key_public: "your Botsociety API api key"
  },
  body: {
      domain: "app.botsociety.io",
      welcomePathId: "you can specify here a path id for your integration",
      designId: "put a design id that you have access to",
      callbackUrl: ""
  }
}

If the test is successful, your integration does not crash. You can write additional tests to make sure that the output format of your integration is as expected.

Testing using the NodeJS boilerplate

If you are building the custom integration starting from the NodeJS boilerplate, it's a bit faster to test your integration. First, you need to create a .env file. Check out the .env-example for an example of the values you need. If you don't know your API key, check out the Botsociety documentation here.

Run:

nodemon -e js,yml ./node_modules/.bin/serverless offline start

Then open another tab in your terminal and run

mocha

If the test is successful, your integration does not crash. You can write additional tests to make sure that the output format of your integration is as expected.

Private and public integrations

There are two types of custom integrations:

Private integration
Public integration

A private integration is visible only to your team space or Organisation. It can be used by any user that belongs to your team, but it's not visible to the Botsociety user base.

A public integration is visible to all of the Botsociety users base. You can build a custom integration and submit it to our team. We will review it and then make it available to our user base.

An example of a private custom integration would be an export to your own bot-building codebase. You can write once a piece of code that exports a format that is importable by your technology; you can then have it appear in the Build mode dropdown of your team's designs.

Submitting your custom integration for public use

We just launched this submission process. Let us know how we can improve it.

To submit your custom integration for public use:

Push your integration code to a Github repository
Fill out this form.

Submitting your custom integration for private use (Enterprise only)

To submit your custom integration for public use, write us an email at info@botsociety.com