Graphlogic.ai documentation

How to create and configure Slots

Mailings and notifications | Incoming Request slot

Purpose and general information

⁠

@Incoming Request Slot⁠

is a

@Slot⁠

that allows an

@Agent⁠

to write to a

@Chat⁠

when

@Dialog⁠

s are closed. The presence of an

@Incoming Request Slot⁠

allows an external system to activate an

@Agent⁠

in a specific

@Chat⁠

by sending an http request (POST or GET) to its webhook, for example, to send a notification to an

@Bot User⁠

about the status of his order. Upon receiving an

@Incoming Request⁠

, an

@Agent⁠

begins a

@Script Branch⁠

following the

@Incoming Request Slot⁠

⁠

Slot creation and settings

The

@Incoming Request Slot⁠

can be created only after the

@Start⁠

@Slot⁠

if there is a regular branch for processing messages incoming through the

@Project Channel⁠

⁠

Only one

@Incoming Request Slot⁠

is allowed per

@Script⁠

Slot attributes

⁠

Name — the name of a

@Slot⁠

that will be displayed in a

@Script Tree⁠

. The maximum length of a field value is 40 characters.

Webhook — Webhook address of an

@Incoming Request Slot⁠

The field is empty until the

@Slot⁠

is saved;

The field is not available for editing, but its contents are available for copying to the clipboard;

The webhook address is available in

@System Context Variables⁠

@IR_url⁠

The webhook starts working after the

@Agent⁠

is trained.

An array of Context key - Request key pairs for parsing data from the parameters of an

@Incoming Request⁠

into

@User Context Variables⁠

for subsequent use in a

@Script⁠

. More details about parsing: Incoming request parameters and their parsing into context variables.

Context key — the name of

@User Context Variables⁠

into which the value will be written.

Request key — a key from the parameters

@Incoming Request⁠

@Expression⁠

@Expression with Control Structure⁠

, the value of which will be written to the Context key. Read more:

Using syntax in the Incoming Request Slot⁠

⁠

Trimming spaces: by clicking the CREATE button (when creating a

@Slot⁠

) or SAVE (when editing a

@Slot⁠

), spaces and line breaks at the beginning and end of the Request key field are trimmed.

Webhook for Incoming Request slot

The

@Incoming Request Webhook⁠

is generated only after the

@Slot⁠

is saved.

The

@Incoming Request Webhook⁠

becomes available in the

@Slot⁠

editing window when it is opened after saving.

⁠

The value of the Webhook field is a url address (link) that must be copied and passed to an external system for sending an

@Incoming Request Slot⁠

, example: https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4

The

@Incoming Request Webhook⁠

via the link becomes active after saving the

@Script⁠

, but responds with an error to all requests until the moment of

@Agent⁠

@Training⁠

The address of the active

@Incoming Request Webhook⁠

is available in the

@Chat Context⁠

in the

@IR_url⁠

@Context Variable⁠

and is uploaded to

Chat context report⁠

You can substitute query_params into the

@Incoming Request Webhook⁠

, for example chat_id and is_urgent (parsing other parameters from URLs is not yet supported)

The

@Incoming Request Webhook⁠

can be regenerated using the GENERATE NEW WEBHOOK button; it will respond after saving the

@Slot⁠

(with an error), but will begin processing requests after retraining the

@Agent⁠

Note: In this case, from the moment the
@Slot⁠
is saved until the
@Agent⁠
is retrained, both
@Incoming Request Webhook⁠
will work: the old one will continue to receive and process requests, the new one will respond with an error to requests. After retraining the
@Agent⁠
, the old
@Incoming Request Webhook⁠
will be deleted and stop responding, and the new one will begin to receive and process requests

The

@Incoming Request Webhook⁠

is not saved in the configuration file when exporting the

@Agent⁠

; when importing the configuration file, a new

@Incoming Request Webhook⁠

is generated for the

@Agent⁠

created by import.

When replacing the

@Agent⁠

@Script⁠

with a configuration file with

@Incoming Request Slot⁠

If the

@Agent⁠

@Script⁠

already had an

@Incoming Request Slot⁠

before the replacement, the

@Incoming Request Webhook⁠

in the new

@Script⁠

will remain the same as before the replacement.

If there was no

@Incoming Request Slot⁠

in the

@Agent⁠

@Script⁠

before the replacement, a new

@Incoming Request Webhook⁠

address will be generated for this

@Slot⁠

Using the Syntax in the Incoming Request Slot

In a

@Slot⁠

, it is permissible to use

@Expression⁠

and

@Expression with Control Structure⁠

in Request key field. More details:

Syntax⁠

The result of the template calculation will be saved in the

@Chat Context⁠

, similar to the

@Memory⁠

@Slot⁠

IMPORTANT: To parse is_urgent / chat_id fields, only
@Expression⁠
is allowed. The use of
@Expression with Control Structure⁠
is not allowed.

When parsing the body of a request, the “variables” specified in the Request key field are not
@Context Variable⁠
s, but are calls to the body, headers, query objects — parts of the
@Incoming Request⁠
— and their properties. Read more: Incoming request parameters and their parsing into context variables

Incoming Request

@Incoming Request⁠

is an HTTPS request sent to the

@Incoming Request Webhook⁠

for the purpose of activating the

@Script Branch⁠

following the

@Incoming Request Slot⁠

in a specific

@Chat⁠

for that

@Agent⁠

. The ID of the target

@Chat⁠

—

@chat_id⁠

— must be specified in the body of the request or in the url parameters (query params).

Incoming request format

Protocol: HTTPS

Request method: POST\GET

POST request body: JSON

Authorization: the authorization token is part of the URL of the

@Incoming Request Webhook⁠

chat_id request attribute:

The chat_id attribute contains the

@Chat⁠

identifier (the value of the

@chat_id⁠

variable) in which the

@Incoming Request Slot⁠

@Script Branch⁠

must be started.

Required attribute. Location: key "chat_id" in the body of the

@Incoming Request⁠

or the chat_id parameter in the url parameters of the

@Incoming Request⁠

(query params).

Chat_id search order and selection priority:

For a POST request:

Priority 1 — along the specified path in the body of the request: The user can define the path to the "chat_id" key in the parsing settings in the

@Incoming Request Slot⁠

— this is the priority path for searching

⁠

Priority 2 — in the request parameter: If the "chat_id" key is not found in the body of the incoming POST request at the path specified by the user, the system will look for the chat_id parameter in the query params in the request url. Example: https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb89244f6dea

Priority 3 — at the first level of the request body: If the “chat_id” key is not found at the path specified by the user in the request body, and the chat_id parameter is not found in the query params, the “chat_id” key is searched at the first level of the request body

For a GET request: the search occurs only in the URL parameters of the

@Incoming Request⁠

is_urgent request attribute:

The is_urgent attribute contains an indication of the urgency of the request. Optional attribute, if not specified, evaluates to false

Valid values:

true — a sign of an urgent

@Incoming Request⁠

— executed immediately and interrupts an

@Active Dialog⁠

false — sign of a non-urgent

@Incoming Request⁠

— executed after closing the

@Dialog⁠

Is_urgent search order and selection priority:

For a POST request:

Priority 1 — along the specified path in the request body: The user can define the path to the "is_urgent" key in the parsing settings in the

@Incoming Request Slot⁠

— this is the priority path for searching

⁠

Priority 2 — in the request parameter: If at the path specified by the user the "is_urgent" key is not found in the body of the incoming POST request, the system will look for the is_urgent parameter in the query params in the request url — example: https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?is_urgent=true

Priority 3 — at the first level of the request body: If the "is_urgent" key is not found at the user-specified path in the request body, and the is_urgent parameter is not found in the query params, the "is_urgent" key is searched at the first level of the request body

If the is_urgent attribute is not found by the above methods, it takes the value false

For a GET request: the search occurs only in the URL parameters of the

@Incoming Request⁠

⁠

Important:

* the locations of chat_id and is_urgent may be the same (example: https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb8924 4f6dea&is_urgent=true)

* the locations of chat_id and is_urgent may differ, for example, is_urgent can be passed in the request parameters, and the path to the “chat_id” key (in the request body) can be specified by the user in the parsing settings

User data in the incoming request:

variables, arrays and objects — key-value pairs in the

@Incoming Request⁠

body for transfer to

@Context Variable⁠

s when parsing in the

@Incoming Request Slot⁠

. Optional fields.

Can only be sent in a POST request.

Parameters of the incoming request and their parsing into context variables

Incoming request parameters:

When an

@Incoming Request⁠

arrives, it is possible to access its parts (headers, body, parameters) as objects to parse the contents of these parts.

Request body

body — request body object. Format: JSON.

Accessing keys nested in the body (JSON): body.<key>

⁠

Important: If the size of the
@Incoming Request⁠
body exceeds
@Limit on the size of the received body in the Incoming Request⁠
, then it is replaced with an empty body {}.

Request headers

headers — an object containing request headers. Accessing headers: headers.<header name>

⁠

Query parameters

query — an object containing query parameters from the URL (after the ? sign in the URL)

Accessing parameters: query.<parameter name>

⁠

Important: body, headers, query objects are not saved in the
@Chat Context⁠
, but are available for parsing when this
@Incoming Request Slot⁠
is running.

Body, headers and query can be parsed entirely into
@Context Variable⁠
s.

⁠
⁠
⁠

In
@Context Variable⁠
s in the Context key field, you can set names that match the names of parts of the request, for example, parse the entire body object into the body variable.
⁠

Parsing features:

It is possible to parse objects, arrays and variables of any nesting;

Example: {{ body.content.par1 }} — access to the par1 variable nested in content and body

Variable names and paths to values are case sensitive;

Example: {{ body.name }} and {{ body.Name }} — calls to different keys (name and Name) in the request body.

The dot (.) refers to the keys at the lower levels of the multi-level object\JSON;

Example: {{ body.content.par1 }}

The corresponding array element number is accessed using numbers. The numbering of array elements starts from zero, so access to the first array element is designated as 0.

Example: {{ body.array.0.par1 }} — accessing the first element of the array

Referring to the key of an object, if its name matches the name of

Reserved methods of objects⁠

, occurs through square brackets and quotes.

Example: {{ data["keys"] }}

Examples of incoming requests and their parsing

1) With chat_id and is_urgent in the request body

Below is an example of an and parsing the data of this request into variables

POST Request is sent to the

@Incoming Request Webhook⁠

and contains the following query parameters: ...?bar=42&baz=aaa

The request contains an Authorization header with the value Token fjrv44344fjvr

Request body:

{

"chat_id": "e2022b50f626d13b8fc12ee0ea2d7582dca09424",

"is_urgent": true,

"par": "value",

"content":

{

"par1": "value1"

"array": [

{

"par2": "value2"

{

"par3": "value3"

}

]

}

Parsing this request into variables:

In the example, in the case of body and query, individual keys and parameters are parsed into variables, but it is also possible to parse the entire object, as in the example below with headers.

⁠

var1 will contain the value value

The value value1 will be written to var2

The value value2 will be written to var3

The value (object) {'Authorization': 'Token fjrv44344fjvr'} will be written to var4

42 will be written to var5

2) With chat_id and is_urgent in the request URL parameters

URL: https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb89244f6dea&is_urgent=false

BODY:

{

"message": "Discounts for new clients",

"name": "John"

}

In this example, the

@Incoming Request⁠

is addressed to

@Chat⁠

with

@chat_id⁠

= 1b7637033b3fc4c15a95bfad048ceb89244f6dea.

This request will be queued and will be executed after the

@Dialog⁠

is closed, because it is not urgent (is_urgent = false).

Parsing this request into variables:

The values from the message and name keys will be parsed into

@User Context Variables⁠

if the

@Slot⁠

is configured as shown in the screenshot below.

⁠

Slot operation

The operation of the

@Slot⁠

begins from the moment the

@Platform⁠

receives an

@Incoming Request⁠

from an external service on the

@Incoming Request Webhook⁠

After receiving a request, the following operations are performed in the order specified:

Checking the limits on API requests: for each

@Company⁠

there is a

@Limit on Incoming Requests⁠

— 20

@Incoming Request⁠

s per second in total for all

@Incoming Request Webhook⁠

s in all

@Agent⁠

s of the

@Company⁠

If the limit is exceeded: Processing of the request stops. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 429

Otherwise, the transition to the next operation occurs.

Method verification: The POST/GET method is checked in the

@Incoming Request⁠

If a request was sent using a different method (not POST/GET): Processing of the request stops. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 405

Otherwise, the transition to the next operation occurs.

Checking the header content-type: application/json: if the request method is POST, the presence of the header content-type: application/json is checked:

If the

@Incoming Request⁠

does not have a content-type: application/json header: Processing of the request stops. Sending a response to an

@Incoming Request⁠

: with status: HTTP status: 400 BODY: “status”: “Unsupported content-type.”

Otherwise, the transition to the next operation occurs.

Checking body size of

@Incoming Request⁠

If the body size of the

@Incoming Request⁠

exceeds 10 KB, then the body is replaced with {}.

Otherwise, the transition to the next operation occurs.

Validation of JSON correctness: if the request method is POST, the body of the

@Incoming Request⁠

is validated for correct JSON:

If it was not possible to parse the body of the

@Incoming Request⁠

, i.e. invalid JSON: Processing of the request stops. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 400 BODY: {"status": "Document parse error."}

Otherwise, the transition to the next operation occurs

Search for the

@Incoming Request Slot⁠

: the system searches among the

@Trained Agent Model⁠

for the

@Incoming Request Slot⁠

whose

@Incoming Request Webhook⁠

received a request:

If the

@Incoming Request Slot⁠

is not found among the

@Trained Agent Model⁠

, the

@Incoming Request Webhook⁠

for which the request was received: Processing of the request stops. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 404 BODY: {"status": "Incoming request not found."}

Otherwise, the transition to the next operation occurs.

Search for chat_id:

If the request method is GET, the system looks for the chat_id parameter in the URL parameters of the

@Incoming Request⁠

⁠

If the request method is POST, the system looks for the chat_id parameter in the body of the

@Incoming Request⁠

and then, if not found, then in the URL parameters of the

@Incoming Request⁠

If the chat_id parameter is not found: Processing of the request stops. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 400 BODY: {"status": "No chat id passed."}

Otherwise, the transition to the next operation occurs.

Search for is_urgent:

If the request method is GET, the system looks for the is_urgent parameter in the URL parameters of the

@Incoming Request⁠

⁠

If the request method is POST, the system looks for the is_urgent parameter in the body of the

@Incoming Request⁠

and then, if not found, then in the URL parameters of the

@Incoming Request⁠

If there is no is_urgent or it exists, but it was not possible to read the correct Boolean, the system considers it as false.

Search for

@Chat⁠

by chat_id.

If the

@Chat⁠

by chat_id

received in the body or request parameters is not found⁠

: Processing of the request stops. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 400 BODY: {"status": "Chat not found."}

If a

@Chat⁠

with an identifier from the chat_id attribute is found, but the

@Project Channel⁠

of this

@Chat⁠

is deleted: Processing of the request stops. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 400 BODY: {"status": "There is no active channel for received event."}

Otherwise, the transition to the next operation occurs.

Running the script.

If is_urgent == true, (step 7) then the

@Incoming Request Slot⁠

@Script Branch⁠

is launched. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 200 OK BODY: “status”: “Accepted for execution”

If is_urgent == false, and there is no active

@Dialog⁠

in the

@Chat⁠

, then the

@Incoming Request Slot⁠

@Script Branch⁠

is launched. Sending a response to an

@Incoming Request⁠

with the status: HTTP status: 200 OK BODY: “status”: “Accepted for execution”

If is_urgent == false and there is an active

@Dialog⁠

in the

@Chat⁠

, then the request goes to the

@Incoming Request Queue⁠

and will be processed in the

@Inactive Chat⁠

when its turn comes.

Purpose and general information

Slot creation and settings

Slot attributes

Webhook for Incoming Request slot

Using the Syntax in the Incoming Request Slot

Incoming Request

Incoming request format

Parameters of the incoming request and their parsing into context variables

Examples of incoming requests and their parsing

Slot operation

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.