Custom Integrations API

This documentation describes usage of API for custom integrations within new Chatbot Builder plugin. 

Plugin

You can find new plugin in Chatbot Builder called Integration Plugin.

In the plugin you can define multiple things. You can choose from your connected integrations, choose REST method, define endpoint, send parameters, handle errors and debug. All of those points will be described down below in more detail.

Add integration

Before using Custom Integration plugins, you must setup a custom integration in "Integrations" settings (you can find it in top right corner). Chatbot Builder uses OAuth2 for requests authentication. Integration name, Authorization URL, Client ID and Client secret are required. You can also use your API without authorization - just choose "Debug / Public" option.

Endpoint definition

Method

You can choose between `GET` and `POST`. Every method behave differently in terms of how the parameters are transfered.

URL 

You need to define endpoint URL. You can also take Chatbot Builder attributes and use them as URL attributes. (as example we used `%customerId%`)

Sending attributes 

You can send other attributes from Chatbot Builder as parameters.

Whenever chatbot calls your endpoint, the parameters are send in the following format depending on chosen method. For POST method, it's being sent as a json body.

{
    data: {
        sent_attribute: "some value",
        another_sent_attribute: "another value"
    },
    payload: {
        your_data: "value"
    }
}

For GET method, it's being sent as GET parameters in url.

?data[sent_attribute]=some value&data[another_sent_attribute]=another value&payload[your_data]=value

Please note, that in data attribute, we're sending variables defined in plugin setting. In payload attribute, we're sending your own data back to you (see postback action below).

Response format

Response must be in a valid JSON format, with Content-Type: application/json header correctly set.

Every response must provide render array of plugins to be rendered (see below for Content options) Plugins are being rendered in the order they are placed in the array.

Example response for a simple text to be rendered:

{
    "render": [
        {
            "type": "text",
            "text": "This is a text I want to show",
        }
    ]
}

Example response for two plugins to be rendered

{
    render: [
        {
            "type": "text",
            "text": "This is my first text",
        },

        {
            "type": "text",
            "text": "This is another text with a button!",
            "buttons": [
                {
                    "text": "See welcome message",
                    "action": {
                        "type": "redirect",
                        "flow_name": "Welcome message"
                    }
                }
            ]
        }
    ]
}

 

Content options

Text

Send a simple text message.

{
    "type": "text",
    "text": "there is some text"
}

Text with Buttons

Send a simple text message with buttons. You can use up to 3 buttons.

{
    "type": "text",
    "text": "there is some text",
    "buttons": [
        {
            "text": "Button 1 text",
            "action": { action structure, see below}
        },
        {
            "text": "Button 2 text",
            "action": { action structure, see below}
        },
    ]
}

Text with Quick replies

Send a simple text message with quick replies (disposable buttons). You can use up to 10 quick reply buttons.

{
    "type": "text",
    "text": "there is some text",
    "quick_replies": [
        {
            "text": "Button 1 text",
            "action": { action structure, see below}
        },
        {
            "text": "Button 2 text",
            "action": { action structure, see below}
        },
    ]
}

Note: As you can see, you can use buttons and quick replies with a simple text. Please notice, you should not use buttons and quick replies in one response. In this case, one will be picked randomly.

Menu

Send a simple menu. You can use up to 3 buttons.

{
    "type": "menu",
    "title": "Big Heading",
    "subtitle": "optional smaller text",
    "image": "https://domain.com/some_image.png"
    "buttons": [
        {
            "text": "Button 1 text",
            "action": { action structure, see below}
        },
        {
            "text": "Button 2 text",
            "action": { action structure, see below}
        },
    ]
}

Gallery

Send a gallery of choices - basically, this is just more Menu plugins in one.

{
    "type": "gallery",
    "elements": [
        {
            "title": "Big Heading 1",
            "subtitle": "optional smaller text",
            "image": "https://domain.com/some_image.png"
            "buttons": [
                {
                    "text": "Button 1 text",
                    "action": { action structure, see below}
                },
                {
                    "text": "Button 2 text",
                    "action": { action structure, see below}
                },
            ]
        },
        {
            "title": "Big Heading 2",
            "subtitle": "optional smaller text",
            "image": "https://domain.com/some_image.png"
            "buttons": [
                {
                    "text": "Button 3 text",
                    "action": { action structure, see below}
                },
                {
                    "text": "Button 4 text",
                    "action": { action structure, see below}
                },
            ]
        }
    ]
}

Multimedia

Send a file to be shown - image preview, video preview, audio preview or general file to be downloaded. Supported mimetypes are:

• image/jpeg, image/png, image/gif, image/bmp for images

• video/x-msvideo, video/mpeg, video/mp4, video/quicktime for videos

• audio/aac, audio/ogg, audio/wav, audio/mpeg, audio/mp4 for audio

• any other mimetype will be served as a file to be downloaded

  File name (name attribute) is optional.

{
    "type": "multimedia",
    "attachment": {
        "mimetype": "image/png",
        "url": "https://reference.link/to/file",
        "name": "Great file"
    }
}

Button actions

You can define an action to be triggered on button click. Following actions are supported:

• open web url in browser
• redirect to another flow
• postback to another 3rd party endpoint and render its response

Open web url example

{
    "type": "url",
    "url": "https://domain.com"
}

This is pretty straightforward - define a url type and give a url to be opened.

Redirect to another flow example

{
    "type": "redirect",
    "flow_name": "More information",
}

Here you must define a redirect type and provide a full flow name, where you want a user to be redirected.

Postback example

{
    "type": "postback",
    "url": "https://domain.com/api/anotherplugin",
    "method": "POST",
    "payload": {
    }
}

Here you must define a postback type, http method (method attribute) and your endpoint url. You can also define your own data in payload you want us to send you back, when the action is triggered. For GET method, it"s being sent as GET parameters in url. For POST method, it's being sent as a json body.