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.

Authorization

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

Behavior

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

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:

https://help.mindbehind.com/portal/en/kb/articles/messages-format-14-2-2022