Requests to external systems | External Request slot

Function and general information

The External Request slot is designed for integrating the Agent with external IT systems via the HTTP protocol (REST API or GraphQL, for example). When this slot is processed in the Script, an HTTP request to the API of the external system is executed, and the response to this request is received and processed.

Creating and configuring the Slot

Slot’s parameters
The External Request slot does not contain settings for the HTTP request it sends. It contains a link to the External Request from the Company Resources, and the External Request in its turn contains all the necessary settings for sending the request and processing the response.

  1. NAME is a slot’s name which will be depicted in the Script Tree. The maximum length of the field is 40 characters.
  2. REQUEST is an External request from the Company Resources.

Creating an External Request in the Company Resources

  1. To create an External Request, go to the External Requests tab.
  2. Click Create new.
  3. Fill out the fields in the Main tab:
    • Name is the name of the slot. The maximum length of the field value is 1000 characters. Once the maximum length is reached, no more characters can be entered into the field;
    • Description is the description of the slot. Maximum length of the field is 1000 characters. On reaching the maximum value no more characters can be entered into the field;
    • Request method is the HTTP method for this request:
      • GET
      • POST
      • PUT
      • PATCH
      • DELETE
      • HEAD
    • Endpoint is the address of the webhook to which this request will be sent. The maximum length of the field value is 1000 characters. When the maximum value is reached, no more characters can be entered in the field.
  4. The request’s headers can be added on the Headers tab:
    • New name is the name of the header. The maximum length of the field value is 1000 characters. When the maximum value is reached, no more characters can be entered into the field;
    • Value is the header value. Maximum length of the field value – 1000 symbols. After reaching the maximum value, no more characters can be entered into the field;
      • Use of variables: it is allowed to use a variable in this field in the format {{ var }}. The variable value will be substituted at the moment of request headers assembling; if the variable is not in the Chat Context, a header with an empty value will be sent.
      • Concatenation: concatenation of strings and variables in this field is allowed.

Use of syntax in External Request

Expressions and Control structures can be used in the following fields of External requests: URL and Value fields (Headers, Query parameters, Data tabs), Name field (Response tab).
Important: when parsing the request body, all variables used in the template are searched in the request body rather than in the Chat Context. The request body is accessed through the body variable. For example, if a response to the request is a JSON object {“one”: {“two”: [0, 1, 2]}}, the entire JSON object (dictionary) will be saved in the resp_body variable; the object (dictionary) {“two”: [1, 2, 3]} will be saved in the resp_one variable; the integer number 1 will be saved in the resp_two variable. resp_invalid variable will not be saved because the request body is accessed through the body variable.

Slot operation

The process of executing the External Request slot:

1. Defining a request for execution

A Trained Agent model (in each External Request slot) stores a copy of its External Request from the External Request List created at the time the Agent was last Trained.

2. Assembling the final URL of an external request

  1. Expressions and Control structures can be used in the Endpoint field.
  2. In case the Endpoint field contains a Context variable, it is retrieved and assigned to the final URL immediately before the request execution. If the Endpoint field contains an Expression or Control structure, the result is assigned to the final URL after the Expression/Control structure evaluation.
    • The correctness of the URL in the Context variable value is not checked;
    • The existence of the Context variables used in the URL is not checked;
  3. Encoding the final URL of an external request.
    • The system checks whether there are any invalid characters in the final URL of the external request and encodes them.

3. Assembling request headers

  1. Before sending a request, the names and values of headers are retrieved from the Headers tab.
  2. The retrieved headers are substituted in the request

4. Assembling the request body

  1. Before sending a request, the names and values of request body are retrieved from the Data tab.
  2. The retrieved request body is substituted in the request.

5. Sending a request

  1. A request is sent once.
  2. If the connection is broken during the timeout, there are no retries to send a request.

6. Receiving Response and Writing Context Variables

  1. The timeout for the response to an external request is 30 seconds.
  2. An attempt will be made to parse the response to the request, according to the parsing settings specified in the Response tab.
    • If the value has been found during the parsing process with the use of the specified path, the corresponding Context will be created/updated;
    • If the value has not been found during the parsing process with the use of the specified path, the corresponding Context will not be created/updated.

3.  An attempt to parse the request response will be made in case of any request response code if the parsing settings are specified on the Response tab.


4.  When processing the response to the request, the response code to the request is written into the variable response_status_code:

  1. If the request cannot be executed, the code 400 will be written;
  2. If a 30 second timeout occurs, the code 408 will be written;
  3. If there is no response from the server, the code 499 will be written.


5. The request_success variable is created as a result of executing the external request, in which the result of executing the request is written as success (True) or failure (False):

  1. If the request cannot be executed or there is no response from the server, a False value will be attached to the request_success;
  2. If the response code is >=400, a False value will be attached to the request_success;
  3. If the response code is 200 but there is no response (including an empty {} BODY) or the body is invalid for the expected response type, if a parsed response is expected (there are entries in the Response tab) a False value will be attached to the request_success;
  4. In other cases a True value will be attached to the request_success: the request has been successfully executed.


6. Based on the result of executing the external request, the raw_response variable is created in the format {“request result”, “response body”}. Example: {“success”:true, “temperature”:”-7.3″, “feels_like”:”-14.3″}.

7. The variable consists of two parts:

  1. The first part contains the result of the request execution “success”:true or “success”:false, which is a duplicate of the raw_response variable (the result depends on the conditions described in item 5);
  2. On successful execution, the body of the response contains the parsing result specified in the settings on the Response tab;
  1. If the execution is unsuccessful, the response body contains the text of the error received from the external system;
  1. When receiving an .xml from an external system, the response is written as a string;
  2. When an empty {} BODY is received from an external system, an empty string is written to the body of the response.

Exporting and importing external requests

Exporting an Agent also exports all the External Requests contained in its Trained Agent Model. The Agent with external requests used in it is exported as a .cfg file. When you import an Agent, the External Requests used in it are imported, with:

  1. If the company has an External Куйгуые with an identical name and content, there is no duplication of the External Request. An existing External Request will be used in the imported Agent. In other cases, a new External Request will be created;
  2. If a company has an External Request with an identical name but different content, a duplicate of this External Request will be created with a name generated automatically:
  1. If the company has an External Request with a different name but identical content, the External Request from the configuration file will be imported.
  2. If the company does not have such an External Request, it will be imported and appear in the list of External Requests.