The Request block allows the bot to communicate with external systems using REST API. The bot can search for or retrieve customer information and send new data obtained during the conversation.
For example, an incoming call is received from a customer. The bot identifies the customer and queries the CRM system to retrieve data. Upon learning that the customer has an active order, it asks if they are interested in its status. If the answer is yes, it provides information about the order before the customer states the purpose of their call.
The Server Request block cannot be the last block in the script; at least one outgoing link must lead from it. If you need to end the scenario with a request block, you can link an empty block after the request.
¶ Block properties
| Property | Description |
|---|---|
| Label | The block name displayed in the script editor, not used in the dialog with the client. It serves for the convenience of the user creating the script. |
| Marker | A conditional designation of the block, arbitrary text. It can be used in analytics in reports as a block passage marker – it allows tracking which blocks the bot has passed. |
| Message | The text that will be said by the robot after transitioning to the block. It is displayed in the block in the scenario editor if no Label is set, and also appears as a tooltip when hovering over the block. |
| Delay | The delay after which the message will be sent after transitioning to the block. With the delay before sending, you can emulate message typing – as if a real person is communicating with the client, not a bot. Set in seconds. > This feature works only in text-based dialogs, provided that at least one question has been asked earlier in the dialog. |
| Send immediately | Allows sending messages before fully forming the queue in conjunction with the request block. |
| Maximum wating time | The maximum wait time for a response from the server (in seconds), after which the response is considered not received. The minimum value is 0, the maximum is 300. If there were no Question blocks before the Request block, this value is ignored, and the wait for a response from the server will last no more than 5 seconds. |
| Wait message delay | The time in seconds after which the robot will play the repeated message until a response is received from the server. The message is filled in below in the field Wait more message field. |
| Wait more message | Phrases with a request to wait, which are voiced by the robot one at a time if no response is received or cannot be processed. Each phrase must be entered or added in a separate field. These phrases can be used to fill a pause during which the system performs an API call to a third-party service or CRM system. |
| Records | Allows you to select a voice file from the list. To load a new file, press  and select a file from your computer in WAV format. To record an audio file, press  . To listen to an audio file, press  . To change the file name, hover over the file name and click  . To remove an unwanted audio file from the voiceover, press  . |
¶ Key properties of the request
The main properties of a request are not displayed unless the request has been configured in the request editor.
| Property | Description |
|---|---|
| Метод | The way the block interacts with the server. - GET — used to get data from the server. This request type can get data about an order, product, user, etc. - POST — used to send new data to the server. This request type can save order data, create a product, etc. - DELETE — used to delete data on the server. The request requires specifying the ID of the resource being changed. This request type can delete order data, product data, etc. - PUT — used to make changes to information already on the server. It is used for full replacement or creation of a resource. If the resource exists, it will be completely replaced with the provided data. If the resource does not exist, it will be created. This request type can update user data, edit an order, etc. - PATCH — used to make changes to information already on the server. It is used for partial updating of an existing resource, i.e., changing individual fields or properties of the resource. This request type can update the client's phone number, change the order status, etc. |
| URL | The address of the page to which the request is sent, representing the main request parameter. This address is tied to the page with which the bot interacts, and allows using variables in the address string to pass information to the service, ensuring effective interaction between the bot and the service. |
| Callback URL | The name of the field in the request body where the URL to which the external system should send the response will be included. If this field is filled in, the bot's operation will be paused until it receives a response from the external system. |
¶ Request editor properties
To open the editor, click the Open request editor button in the block settings.
| Tab | Property | Description |
|---|---|---|
| Parameters | Key | A string that identifies a specific parameter. The key is usually a name or label that describes what exactly is being passed in the request. To add a key, click Add, to delete, click . |
| ^^ | Value | The specific value associated with the key. The value represents the data that is passed in the request and corresponds to the specified key. |
| Authorization | Auth type | The type of authorization in the server request: - None; - Login and Password; - Token Header. The set of the following fillable fields is determined after specifying the type of authorization. |
| Headers | Key | A string that identifies a specific parameter. The key is usually a name or label that describes what exactly is being passed in the request. To add a key, click Add, to delete, click . Cookies can be sent by adding a header named Cookie. |
| ^^ | Value | The specific value associated with the key. The value represents the data that is passed in the request and corresponds to the specified key. |
| Request body | Type | - JSON – Allows to send data in JSON format with the Content-Type header set to application/json - Form data – Allows to send data in Form Data format with the Content-Type header set to application/x-www-form-urlencoded - File upload – Allows to directly upload a file to the request body’s file field by specifying the name of the variable containing the file ID in the TWIN system. - Variable – Allows to specify the name of the variable containing a pre-formatted request body. The application/json and application/x-www-form-urlencoded types are supported |
| ^^ | Key | For JSON: path to a specific JSON parameter in JSONPath format (e.g., data.0.operator.name).For Form Data: name of a specific parameter. |
| ^^ | Value | The specific value associated with the key. The value represents the data that is passed in the request and corresponds to the specified key. |
| cURL | cURL | Allows you to import and export requests in cURL format. When you paste a complete cURL request into the text field on the cURL tab, all parameters—such as the method, URL, headers, and request body—are automatically recognized and transferred to the corresponding tabs in the editor (Method, URL, Parameters, Authentication, Headers, Request Body). If you manually configure request parameters on other tabs (e.g., Parameters, Authentication), the cURL code is automatically generated on the cURL tab. This makes it easy to copy the request in cURL format for later use in the command line or other tools that support cURL. |
¶ Link properties
| Property | Description |
|---|---|
| Label | The name of the link that appears above the link in the script editor. |
| Action type | Link type. Transition to the next script block occurs when a specific request result is achieved (successful or unsuccessful). If no label is set for the link and it is the default link, the link will be named "Default". |
¶ Action types
| Type | Description |
|---|---|
| Default | This type is used to transition to a link if the conditions in all other links of this block are not met. No additional parameter settings are required. |
| Success | The transition to the link will occur if the server response is successful. |
| Failure | The transition to the link will occur if the server response could not be obtained. No additional parameter settings are required. |
If Success action type is used, additional options become available:
¶ Successful response properties
| Property | Description |
|---|---|
| Response code | The successful response code that the system will expect after the request is executed. For example, 200, 201. All response codes are considered successful, even 500 and 404. The response is considered unsuccessful if it was not received at all. |
| Conditions | A set of conditions by which a decision is made. The transition to the link will occur if the server response code matches the one specified in the link properties and the specified conditions are met. The server response result will be saved in the result variable. Each condition is added in a separate field by clicking the Add button and removed by clicking on .The following fields are filled for conditions: 1. Name – the name of the condition by which the decision will be made. 2. Operator – the logical operator in the condition: - = – equals, - != – does not equal, - < – less than, - <= – less than or equal to, - > – greater than, - >= – greater than or equal to, - * – contains, - ** – matches. 3. Value – the value in the condition. |
| Variables | Each variable is added in a separate field by clicking the Add button and removed by clicking on . In the Name and Response Field fields, the names and values of the variables are specified. In variable names it is allowed to use: Latin letters, digits, dot (.), underscore (_), hyphen (-), square brackets ([]). Space is not recommended. To extract data from the server response, use the body field, for example, body.token. You can find more examples in the article Getting information from the server response. |