Newsletters and notifications | Incoming Request Slot

Main function and general information

Incoming Request Slot enables the Agent to initiate interaction with the Bot User by sending them a message to an existing Chat even if the dialogs have already been closed. The Incoming Request Slot makes it possible for an external system to activate an Agent in a particular Chat by sending an http-request (POST or GET) to its webhook (which is specified in the Slot), for example, to notify a Bot User about their order status. Once the Agent receives an External request, it initiates the Script Branch which follows the Incoming Request Slot.

Creating and configuring the Slot

The Incoming Request Slot can be created only after the Start Slot provided the Script contains a basic branch which processes incoming messages received via the Agent’s Channel.

Only one Incoming Request slot is allowed per Script.

Name is a slot’s name which will be depicted in the Script Tree. The maximum length of the field is 40 characters.
Webhook is a webhook address of this Incoming Request slot:
- When the slot is created, the filed is hidden. It will be depicted once the slot is saved;
- The filed contents can not be edited. However, it can be copied;
- The webhook address is contained in the IR_url system context variable;
- The webhook is activated once the Agent is trained.
Context key — Request key pairs array is necessary for parsing data received in the Incoming request body into context user-declared variables for their further use in the Agent Script:
- Context key is the name of the variable in which the value will be stored; Important: while specifying the CONTEXT KEY, keep in mind the requirements for naming context user-declared variables.
Request key is a key received in the Incoming request body. Its value will be stored in the Context key.

Incoming request parameters and their parsing into context variables.
Incoming request parameters:

body is a request body object. Format: JSON

headers are an object containing HTTP headers of the request

query is a query object of the variables attached to the end of a url after the question mark

Important: body, headers and query objects are not stored in the Chat Context, though they can be parsed.

Parsing details:

Parsing of any objects, arrays and variables of any nesting level is available;
Names of variables and paths to values are case sensitive;
Names of required keys from the request body are specified as text;
To access keys from a low level in a multi-level JSON array, use a period symbol (.);
To access a required array element number, use numbers. Numbering of array elements starts from zero, so to refer to the first element of an array, use 0.

Header: foo: bar
{{ headers }} == {"foo": "bar"}
URL ...?bar=42&baz=aaa
{{ query }} == {"bar": 42, "baz": "aaa"}
Body:
{
    "chat_id": "e2022b50f626d13b8fc12ee0ea2d7582dca09424",
    "is_urgent": true,
    "par": "value",
    "content":
            {       
            "par1": "value1"
            },
    "array": [
            {            
            "par2": "value2"        
            },        
            {            
            "par3": "value3"        
            }    
    ]
}

Incoming Request slot webhook

A webhook address for an Incoming Request slot is generated only after saving the Slot.

WEBHOOK field value is a URL-address (link) which is supposed to be copied and transferred to an external system so that it can send an Incoming request;
Webhook link is activated only after Training the Agent;
The active webhook address is contained in the IR_url system context variable and is unloaded in reports;
You can regenerate a webhook by clicking GENERATE NEW WEBHOOK. It will start processing requests once you retrain the Agent.
Webhook address is not unloaded in the configuration file when the Agent is exported. When a configuration file is imported, a new webhook for an imported Agent is generated.

Use of syntax in the Incoming Request Slot

Expressions and Control structures can be used in the Slots’ Value field. The template’s result will be saved in the Chat Context, similar to the Memory Slot.

Important: only Expressions can be used to parse the is_urgent / chat_id fields. Use of Control Structures is not allowed.

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 by analogy with the access to the response body in External Requests.

Incoming Request slot operation

Incoming request

An HTTP request is sent to the Agent’s REST API webhook in order to activate the Script branch following the Incoming Request in a certain Chat of this Agent. The ID of the target Chat (chat_id) can be specified in the request body or in URL parameters (query params). One Incoming Request can be sent and executed in only one Chat. It is mandatory to pass the destination Chat ID in the body of the request.

Incoming request format

Protocol: HTTP
Request method: POST \ GET POST
1. request body: JSON
Authorization: authorization token is part of the Incoming Request slot webhook URL

Request attribute chat_id:

The chat_id attribute contains the ID of the Chat (value of the chat_id variable) in which the Incoming Request slot branch needs to be started.
- This is a mandatory attribute. Location: the “chat_id” key in the body of the request (body) or the chat_id parameter in the request url parameters (query params)
The search order of chat_id and priority of selection:
First priority — using a specified path in the request body: The user can specify the path to the “chat_id” key in the parsing settings of the Incoming Request slot. This is the priority path to search;

Request attribute is_urgent:

The is_urgent attribute contains an attribute indicating the urgency of the request. It is an optional attribute, and, if not specified, takes the value false;
Valid values:
- true – indicating that an incoming request is urgent; the request is executed immediately and interrupts an active dialog;
- false – indicating that an incoming request is not urgent; executed after the dialog is closed.
is_urgent search order and priority of selection:
- First priority — using a specified path in the request body: The user can specify the path to the “is_urgent” key in the parsing settings of the Incoming Request slot. This is the priority path to search;
- Second priority — in the query params: If the “is_urgent” key has not been found in the body of the incoming POST request with the use of the path specified by the user, the system will look for the chat_id parameter in the URL of the request specified in the query params.
- Third priority — on the first level of the request body: If the “is_urgent” key has not been found in the body of the incoming POST request with the use of the path specified by the user, and the “is_urgent” parameter has not been found in the query params, the “is_urgent” key is searched on the first level of the request body.

Incoming requests examples

Chat_id and is_urgent in request body

URL
https://app.chatbots.gms-worldwide.ch/api/incoming_request/946::VQ_iFZ7qJ2Ze9LeuZMObAphYaeVO-sbZLy51TW2dwyA
BODY
{ "chat_id": "c86821cecf80feadf1e07193b0727335af2f5c1f", "is_urgent": true, "message": " New offer for VIP clients", "name": "Jonh" }
Current example of Incoming request is addressed to the Chat marked by CHAT_ID = c86821cecf80feadf1e07193b0727335af2f5c1f

Platform’s response to an incoming request

API requests limits

Each company has a limit on processing API requests — 20 Incoming requests per second for all webhooks of all Incoming Request slots in all company Agents. If exceeded, the Platform will respond (http response) with code 429.

Incoming request response

The platform responds to requests with the following responses:

HTTP status: 200 OK

BODY: “status”: “Accepted for execution” — the request was received, the Chat with the ID from the chat_id attribute was found, the request was sent for processing.

HTTP status: 404 Not Found

BODY: “status”: “Chat not found” — the request was received, but the Chat with the ID from the chat_id attribute was not found.

HTTP status: 404 Not Found

BODY: “status”: “There is no active channel for received event” — the request was received, the Chat with the ID from the chat_id attribute was found. The Agent channel of this chat has been deleted.

HTTP status: 400

BODY: “status”: “Unsupported content-type.” — the request was received, there is no content-type: application/json header in it.

HTTP status: 400

BODY: “status”: “No chat id passed.” — the request was received, the chat_id attribute was not found.

Executing incoming requests in a script

An Incoming request can be executed only in one Chat — with the specified chat_id in the chat_id attribute.
An Incoming request can be executed immediately (urgent) or when its turn comes after dialog closing (non-urgent).
While executing an Incoming request, data is parsed from the request body into Context variables according to the settings of the Incoming Request slot.

Execution of urgent (is_urgent=true) incoming requests

The script branch of the Incoming Request slot for a Chat with CHAT_ID is executed immediately after receiving and processing this incoming request, the script executed before that is interrupted. Thus, communication (scenario) in the current active Dialog can be interrupted, regardless of who initiated it: the Interlocutor, the previous Incoming request or a special slot, for example, Timer.

Execution of non-urgent (is_urgent=false) incoming requests

The Incoming request is queued for execution with other non-urgent incoming requests. Such requests are executed in turn after the end of the active Dialog.

Incoming chat requests queue

Several Incoming requests can be sent to one Chat by an external system in a row, non-urgent requests do not interrupt the active Dialog, they are queued for execution in the order they are received on the webhook in the Platform. A queue can consist of one or more non-urgent incoming requests waiting to be executed.

It may take a long time to complete several non-urgent requests in one chat

For a Chat that has active Dialog 1 and pending incoming requests in the queue, the Platform waits for Dialog 1 to close, then executes the first non-urgent incoming request in the queue. The completed incoming request opens a new dialog in the Chat — Dialog 2 — the script branch of the Incoming Request slot begins, respectively, the next incoming request from the queue is waiting for Dialog 2 to close. Until all requests in the queue are completed.