Skip to main content
Version: 1.21.3

REST Bot API

In SimpleOne, REST Bot Engine allows you integrate with third-party services (such as messengers, AI systems, and so on) to solve various business tasks depending on the demand. For example, when an incident is created, the responsible group receives notification to the specific messenger with the specified subject.

To integrate with the third-party service, complete the following steps:

  1. Configure the third-party service (register if needed, get an authorization token, check the API documentation).
  2. Create a bot type record.
  3. Configure the REST methods used to interact with the third-party service.
  4. Configure a bot instance.
  5. Set up the routing parameters.
  6. Set up the routing rules.

Create a bot type


A bot type is a connecting element for the bot methods and bot instances. When created, you can easily specify which bots can use configured methods, and vice versa.

To create a new bot type, complete the steps below:

  1. Navigate to Bots API → Bot Types.
  2. Click New and specify a Name for the bot type.
  3. Click Save or Save and exit to apply the changes.

Configure REST bot methods


Configure the REST API methods provided by the third-party system to interact with it. The bot methods are bound to the routing rules and routing parameters.

To create and configure a new bot method, complete the following steps:

  1. Navigate to Bots API → Bot Methods.
  2. Click New and specify a Name for a bot type.
  3. Click Save or Save and exit to apply the changes.

Bot methods form fields

FieldMandatoryDescription
NameYSpecify a method name.
URL SuffixNSpecify a relative path in addition to the request URL. The full URL of the request consists of the constant part specified in the URL field of the bot instance and of this URL suffix.
Request methodNSpecify the request method. Available options:
  • GET
  • POST
To add more request method, add more choice options for this field.
Bot typeNSpecify the bot type that can use this method.
State parameterNDefine the parameter that shows whether the request is successful or not. The field stores a string the response body must return for the request to be considered successful. If left empty, the request is always considered successful (except for errors on the instance).
HeadersNSpecify the method headers if necessary. Variables in the angle brackets are allowed. In the following example, the variable substitutes the token from the bot instance: authorization:Bearer <token>; Content-Type:application/json
BodyNSpecify the body of the request. Variables in the angle brackets are allowed. In the following example, the message is sent out to the messenger channel defined by the variable <routing_parameter_0> and routed to the thread in this channel defined by the variable <routing_parameter_1>. The content of this message is defined by the <content> variable. These variables should be defined in the Bot Routing Rule.
The numeration of the routing parameters starts with 0.
Body example
{
"channel": "<routing_parameter_0>",
"text": "<content>",
"thread_ts": "<routing_parameter_1>",
}

Configure a bot instance


Create a bot instance to continue the integration process (use bot methods, routing rules).

To create a new bot, complete the steps below:

  1. Navigate to Bots API → Bots.
  2. Click New and specify a Name for a bot type.
  3. Click Save or Save and exit to apply the changes.

Bot form fields

FieldMandatoryDescription
NameYSpecify the bot name.
Bot typeYSpecify the bot type. It includes methods that this bot can use.
TokenNSpecify a token if the bot has authorized access to a third-party service. This token should be provided by the API provider.
URLYSpecify a URL for making requests. This part of the URL is permanent, unlike the URL suffixes specified for each bot method.

Configure routing parameters


The routing parameters are used in the bot's routing rules to make them more specific.

The main purpose of this functionality is to set up a correlation between a column value when the bot routing rule is triggered, and a column value used in the request body.

To create a routing parameter, complete the steps below:

  1. Navigate to Bots API → Routing Parameters.
  2. Click New and specify a Name for a bot type.
  3. Click Save or Save and exit to apply the changes.

Routing Parameter form fields

FieldMandatoryDescription
Bot methodYSpecify the method related to this routing parameter.
Column valueYSpecify a column value for additional routing.
Parameter valueNSpecify the value for the parameter that substitutes the <routing_parameter> variable in the request body for the record that has the Column value in the specified column.
You can create more than one parameter. They should be numbered starting from 0:
  • routing_parameter_0
  • routing_parameter_1

Configure bot routing rules


The Bot routing rules table contains conditions and rules to trigger; when conditions are met, the trigger executes a request to the external service. The request history is in the Related Lists area for each record.

To create a new bot routing rule, complete the steps below:

  1. Navigate to Bots API → Bot Routing Rules.
  2. Click New and specify a Name for a bot type.
  3. Click Save or Save and exit to apply the changes.

Bot Routing Rule form fields

FieldMandatoryDescription
NameYSpecify a routing rule name.
ActiveNSelect this checkbox to activate the rule.
BotYSpecify the bot for which you need to configure the routing rule.
Bot methodYSpecify a related bot method.
Business ruleNThe business-rule is generated automatically after the record is saved. It is based on the parameters defined in the Bot and Bot method fields. This business rule triggers events in the system that meets the rule conditions.
When updating the routing rule, the business rule updates automatically.
When deleting the routing rule, the business rule deletes automatically.
TableYSpecify the table on which the routing rule works on.
Routing by columnNSpecify the columns that refer to the routing parameters.
When you have to match more than one routing parameter with relevant columns, the columns should be stated in this field in the same order as the routing parameters in the request body.
Use ResponseNSelect this checkbox when the processing of the designated REST response is needed. When selected, the Use Response tab appears on the form.

Bot request history


To check out the history of the requests to the third-party services, complete the following steps:

  1. Navigate to Bots API → Bot Request History.
  2. Click the record you need to read.

Bot Request History form fields

FieldDescription
RecordThe record ID on which the request was generated.
StateThe request state. Available options:
  • Sent – the request is sent and processed successfully; third-party service did not throw any exceptions.
  • Error – the request is sent and processed with errors displayed in the Response field.
  • Sending – the request is sent and is waiting for the answer from the API provider.
If no answer is received in 10 minutes, the request state is changed to Error automatically.
Bot Routing RuleThe bot routing rule on which the request has been generated.
URLThe URL of the request specified.
MethodThe method of the request specified.
HeadersThe headers of the request specified.
BodyThe body of the request specified.
ResponseThe request response. It is used for debug or troubleshooting. You can find the errors returned by third-party REST API, and arisen on the server-side when a request was created or sent.