How to Use Integration Action

How to Use Integration Action

Action usage

Use the integration action when you want to call an HTTP integration endpoint to achieve some custom business needs. You can process the parameters saved during the life cycle of the assistant, and either only store them out in some other system for later usage, or even modify the flow of the assistant by pushing some messages or cards after that action or force it to fallback.

The story begins by drag and drops (Or simply click on) the  Integration action from the actions menu in the left side to your assistant design canvas:


After that, you will need to click on the action to configure its needed parameters, you will need to configure basically the URL of your integration endpoint, the connection of the next coming action, and the fallback action. And optionally you can put a name, choose the request method, choose the authorization type, choose the parameters that will be read from the response and put some comments for your action as next:


To clear things more, I will make a small scenario with that action, my assistant will ask for a product name from the user and it will fetch all comments related to that product.  I will use an Amazon  AWS Lambda function to implement the integration endpoint. My assistant will look like next:


The assistant will start with a welcome message, then will ask the user to put the product name he wants to fetch its comments, then the input action will get the product name from the user and store it inside a parameter. And while all the parameters will be sent with integration action to my endpoint I will use that product name to query for its comments. I will write my Lambda function as next:


The Lambda function will start by validating the data coming from the assistant, make a call to some endpoint that returning the comments, and then formatting the response that suits the integration action in this part of code:


 And in case of fallback, the Lambda function will call the fallback function defined as next to tell the integration action to fallback.


The integration action will push the messages returned by my Lambda function to the assistant so the user will see a list of product comments messages appeared after he put the name of the product:


Finally, the assistant will ask the user if he wants to repeat the query or just end the conversation.

So this is a very simple scenario that shows how you can deal with integration service, but for sure the door is opened for any business logic you can think about or you need. Also, you can use any integration point whether its a container backend point, a code in a VM, any serverless function while it supports the HTTP POST method, and returns the result in "application/json" content type.


Some endpoints support specific type of authorization layer. In this action we are supporting some common ways for authorization in order to authorize the  call to these endpoints, they are as next:

  • Basic: involves sending a verified username and password with your request.  So the action is going to pass the API a Base64 encoded string representing your username and password values. After selecting this option you will see two field to put the username and password you want to use.
  • Bearer Token: Bearer tokens allow requests to authenticate using an access key, such as a JSON Web Token (JWT). The token is a text string, included in the request header. After selecting this option you will see a filed to put your token.
  • OAuth2: here you first retrieve an access token for the API, then use that token to authenticate future requests. But of course this token should not be expire or it will not be logical to use it here. After selecting this option you can put your token and the header prefix that should be used.

Getting parameters from response

In some scenarios and if the endpoint is not returning the format Mindbehind is waiting for, you can access the response variables using "Variables" section and convert them into a bot parameters. The cool thing here is that you can access any deep variable using dot operations or even items inside array using indexes. Next you can see an example of that:


So we have an endpoint that is returning variants of a product, so let's say we need to save the product id and the cheapest variant price in bot parameters as next:

  • PRODUCT_ID: That we will use to store the product id, so we will need to put "PRODUCT_ID" in the variable name field and "id" in the other field to access that id coming in the response.
  • PRICE_ID: That we will use to store the price of the first variant, so we will need to put "PRICE_ID" in the variable name field and "variants.0.price" in the other field to access that price of the first variant coming in the response.

Please note: That for now we are just supporting JSON response type


Integration action is used to call an integration endpoint with the HTTP POST method, sending the following parameters in the body of the message:

  • node: The id of the integration action in the assistant design canvas
  • params: The current state parameters
  • lastIntent: The last intent the AI predicts for the user input
And it's expecting three optional parameters as next:
  • params: New params to be pushed to the current state, it should be a Javascript map of key-value pairs, like {key1: value1, key2: value2}
  • modules: Some messages that should be sent to the user after the integration action, it should be an array of message object that we will talk about next
  • fallback: If it was true, it will make the integration action to fallback

And the flow will continue using the integration action connection normally unless the integration endpoint returned NULL result or it includes fallback set to true, then the action will fallbacks.

If you didn't configure a fallback for your action, your assistant will stop responding in case you force fallback or your endpoint failed to work for any reason and returned an error.

Defining a delay for this action will delay the call to integration endpoint concluding delays in the upcoming messages after the integration action.

Note: Integration action will not respond to connect messages coming from channels.

Pushing messages programmatically

Integration action supports the ability to push dynamic messages programmatically, which will be returned in the "modules" parameter in the response of integration endpoint.

The "modules" parameter is an array that can contain different messages objects, in order to know more about messages format and their properties please review them in the next article:

    • Related Articles

    • How to Use the Integration Action for Non-developers

      Why do we need the Integration Action? Virtual assistants are there to provide information and guidance for the user. The knowledge of the assistants is, however, limited to the conversation itself. When virtual assistants are incapable of providing ...
    • How to Use Payment Action

      Before using Payment Action, please make sure that you have at least one digital payment solution from the Integrations section under the company settings. You can find more details about adding Masterpass Integration to your company by clicking ...
    • How to Use Zapier Action

      Action usage Zapier action is used when you want to integrate MindBehind with other famous platforms online thanks to Zapier wide market. This action will send the current assistant state to Zapier for any custom further actions you want to do with ...
    • How to Use Wait for Action

      Action usage Use the wait for action when you want to control the assistant behavior from your outside system. The story begins by drag and dropping (Or simply clicking on) the Wait for action from the Actions menu on the left side of your assistant ...
    • How to Use E-Commerce Action

      First of all, to use this action you need to integrate your store to MindBehind. If you haven't done that yet, please check the integrations section under company settings and if you need any further help, please check our article about e-commerce ...