Graphlogic.ai documentation

How to create and configure Slots

Mailings in WhatsApp | Notification slot

Purpose and general information

⁠

@Notification⁠

is a

@Slot⁠

designed for sending mailing. The

@Slot⁠

allows you to send a message when the

@Chat⁠

with the

@Bot User⁠

has not yet been created (no chat_id), or the

@Chat⁠

has been created, but the

@Agent⁠

cannot be the first to write to the

@Chat⁠

after a certain timeout (limitation of some channels). The

@Slot⁠

allows you to process statuses for a mailing.

Note: Currently works with
@360Dialog (WhatsApp)⁠
,
@Edna Pulse⁠
and
@Chat2Desk⁠
.

The

@Notification⁠

@Slot⁠

receives a

@Mailing Request⁠

with data for mailing from an external system (CRM, for example), generates and sends the request to the

@Project Channel⁠

, then receives a response from the

@End Channel⁠

and, depending on the received status, the

@Conversation⁠

goes to one of the

@Subslot⁠

A correct

@Mailing Request⁠

through the

@Notification⁠

@Slot⁠

will create a

@Chat⁠

if it does not exist in the

@Platform⁠

, even if the

@Bot User⁠

does not exist in the

@End Channel⁠

(for example, the recipient’s phone number in the

@Mailing Request⁠

is correct, but the person is not registered in WhatsApp)

The

@Notification⁠

@Slot⁠

is a

@Complex Slot⁠

and cannot exist without three

@Child Slot⁠

@Notification fail⁠

@Notification no account⁠

and

@Notification success⁠

, which begin their own branches to which the transition will be made after receiving the mailing status.

It is not possible to add other

@Child Slot⁠

⁠

The

@Notification fail⁠

@Subslot⁠

is intended to continue the

@Script⁠

if it was not possible to send a mailing to the

@End Channel⁠

The

@Notification no account⁠

@Subslot⁠

is intended to continue the

@Script⁠

after a mailing that was successfully sent to the

@End Channel⁠

, but the

@End Channel⁠

reported that the recipient was not found (for example, the recipient does not have a WhatsApp account when sending messages via WhatsApp).

The

@Notification success⁠

@Subslot⁠

is intended to continue the

@Script⁠

after a mailing that was successfully sent to the

@End Channel⁠

and a successful status or response from the

@Bot User⁠

was received.

Features of the Notification slot in different channels

Features of the Notification slot in different channels

360Dialog (WhatsApp)

1. Field of type “text”; 2. From 10 to 18 digits (from 11 to 19 including +); 3. A + sign is allowed at the beginning.

Edna Pulse

1. Field of type “text”; 2. From 10 to 18 digits (from 11 to 19 including +); 3. A + sign is allowed at the beginning.

Chat2Desk

1. Field of type “text”; 2. From 10 to 18 digits (from 11 to 19 including +); 3. A + sign is allowed at the beginning.

360Dialog (WhatsApp)

Interlocutor identificator in End channel

Phone number in format

ID key in the body of the mailing request

phone_number

Format of Interlocutor identificator in End channel

1. Field of type “text”; 2. From 10 to 18 digits (from 11 to 19 including +); 3. A + sign is allowed at the beginning.

Example of a mailing request

POST <URL>

headers: {"Content-Type": "application/json"}

body: {

"phone_number": "79291642944",

"is_urgent": true,

"extra": {

"foo": 42

}

Notification success

Due to the peculiarities of how Edna works, the order of receiving status-responses to the mailing may be confused, or the statuses may arrive after the interlocutor’s response, therefore, to go to the Notification success branch, we take into account the first of the following events received from the channel after sending the mailing

status sent in response to mailing

status delivered in response to mailing

status read in response to mailing

Message from the interlocutor

Due to the peculiarities of Edna, if before the Interlocutor responds to the mailing list, the Agent tries to send new messages using the regular sending method rather than mailing (if there are Text, Attachment, Button Menu Slots after the Notification success Sub-Slot), then the channel will respond with an error and will not accept them.

Notification fail

The Slot implementation allows you to enter text in the Content field that does not correspond to the agreed distribution template. When sending a mailing with such a message, if there is an Active dialogue, then the text and success will come, and if there is no such thing, then an error and the failed branch

Notification no account

Checking chat availability

Checking the availability of Chat in WhatsApp 360dialog provides a special method to check for account availability:

If the method returns information about the absence of an account, then the Script follows the Notification no account Subslot branch:

in the context variable

@notification_raw_status

⁠

is written {‘description’:’no account on <phone number\key identifier of the interlocutor>’, 'channel_response': response body from the channel as is (object) } (if application/json = object, if text = str; otherwise, null is written).

‘no_account’ is written to the

@notification_status

⁠

context variable.

Check account <phone number>: No account will be written in

Chat history

⁠

If the account is found, then the mailing is carried out

⁠

Slot creation and settings

Slot settings differ depending on the End Channel, for detailed information on how to create a Notification Slot and set up mailings in different End Channels, read the articles:

Slot attributes

General Tab

The General tab contains the basic settings of the Slot.

⁠

Name — the name of the

@Slot⁠

, which will be displayed in the

@Script Tree⁠

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

Destination channel — the

@End Channel⁠

through which the mailing will be carried out.

Chatbot webhook — a webhook to which the

@Agent⁠

will receive a

@Mailing Request⁠

The value will appear in the field after saving and reopening the

@Slot⁠

. The webhook will start working after the

@Agent⁠

is trained.

Webhook copy button — when you click the button, the webhook address is copied to the clipboard.

GENERATE NEW WEBHOOK button.

The button becomes clickable only when the Chatbot webhook field is filled with the webhook value.

When the button is pressed, a new webhook is generated.

Changes after webhook regeneration take effect after the

@Agent⁠

is retrained.

Incoming Data tab

The Incoming Data tab is intended for settings for parsing the body of the

@Mailing Request⁠

for subsequent use of the received data in the Script.

⁠

PARSE REQUEST BODY — an array of Context key - Request key pairs.

Context key — name of the context variable for parsing;

Request key — the key from the body of the

@Mailing Request⁠

, the value of which will be written in the Context key, or

@Expression⁠

Important: access 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"] }}

Destination Tab

On the Destination tab, you configure the sending of mailing to the Destination Channel selected on the General tab, based on its requirements.

WhatsApp (360dialog)

Destination Tab for Whatsapp Channel (Dialog360) GENERAL PARAMETERS — general settings for sending a message: Template name — the name of the template in 360dialog used for the distribution (Name field in the Whatsapp (360dialog) account). More details: /_suIj5 Allowed values: String; Expression Namespace — the name from the parameter in the account in 360dialog (Namespace field) required in the Mailing Request. Allowed values: String; Expression Language code — the name from the "template language" parameter (Languages field) in the account in 360dialog, required in the Mailing Request. Allowed values: String; Expression TEMPLATE PARAMETERS — parameters for substitution in the distribution template specified in the Template name field, array of parameter-value pairs: The syntax corresponds to the WhatsApp documentation. Template parameter — type of parameters. The order of specifying parameters in the Slot must correspond to the order of parameters in the template. Possible values of the field: Parameters for media substitution in the template: image - for image substitution; document - for document substitution; video - for video substitution. Only 1 media parameter is allowed in the template. Parameters for text and button substitution in the template: body - for text data substitution. The number of parameters of this type is not limited. button_url - for button substitution. The maximum number of buttons supported by Whatsapp (360dialog) is 3. Value — the exact value, Expression, or Context Variable that should be substituted in the template. Variables from the Context key field in the Incoming Data tab can be used, as data parsing is performed before the request is formed in the End Channel. Important: when referring to an object key whose name matches #_tuqo-, use square brackets and quotes. Example: {{ data["keys"] }}

WhatsApp (edna)

Cascade id — the value of the field is pulled from the Channel webhook Token field in the settings of the Project Channel. More about the Project Channel settings: /_suljg Content — a JSON object with the content of the distribution. Format (optional elements that need to be added only if there is corresponding content in the distribution template are highlighted in red italics): { "whatsappContent": { "contentType": "TEXT", "header": { "headerType": "<"Type of header (video/image/document)”>", "text": "<header text>", "headerExampleMediaUrl": "<link to example header file>" }, "text": "Mailing text", "footer": { "text": "<footer text>" }, "keyboard": { "rows": [ { "buttons": [ { "text": "<button text>", "buttonType": "<URL for link-button>", "url": "" }, { "text": "", "buttonType": "", "phone": "" } ] } ] } } } 2. It is necessary to specify the data of the agreed distribution template, otherwise the recipient will not receive the mailing.

Chat2Desk

Channel id — channel ID. It is obtained from the Chat2Desk API using the GET channels request. Transport — the value of this field is always wa_dialog. Attachment URL — URL of the attachment in the message template, if available. Content — information about the message template. Format: Without parameters in the template @HSM@ <template name>|<language code> The language code is taken from the Chat2Desk account. Example: @HSM@ test_simple|ru With parameters in the template: @HSM@ test_simple|ru {{ var1 }} {{ var2 }}

WhatsApp (360dialog)

Notes

Destination Tab for Whatsapp Channel (Dialog360)

⁠

GENERAL PARAMETERS — general settings for sending a message:

Template name — the name of the template in

360dialog⁠

used for the distribution (Name field in the

Whatsapp (360dialog)⁠

account). More details:

360Dialog (WhatsApp)⁠

Allowed values:

String;

⁠

@Expression⁠

⁠

Namespace — the name from the parameter in the account in 360dialog (Namespace field) required in the

@Mailing Request⁠

Allowed values:

String;

⁠

@Expression⁠

⁠

Language code — the name from the "template language" parameter (Languages field) in the account in 360dialog, required in the

@Mailing Request⁠

Allowed values:

String;

⁠

@Expression⁠

⁠

TEMPLATE PARAMETERS — parameters for substitution in the distribution template specified in the Template name field, array of parameter-value pairs:

The syntax corresponds to the

WhatsApp documentation⁠

Template parameter — type of parameters. The order of specifying parameters in the

@Slot⁠

must correspond to the order of parameters in the template.

Possible values of the field:

Parameters for media substitution in the template:

image - for image substitution;

document - for document substitution;

video - for video substitution.

Only 1 media parameter is allowed in the template.

Parameters for text and button substitution in the template:

body - for text data substitution.

The number of parameters of this type is not limited.

button_url - for button substitution.

The maximum number of buttons supported by

Whatsapp (360dialog)⁠

is 3.

Value — the exact value,

@Expression⁠

, or

@Context Variable⁠

that should be substituted in the template.

Variables from the Context key field in the Incoming Data tab can be used, as data parsing is performed before the request is formed in the

@End Channel⁠

Important: when referring to an object key whose name matches
Reserved methods of objects⁠
, use square brackets and quotes.

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

⁠

Notification fail, Notification no account and Notification success subslots

⁠

When creating a

@Slot⁠

, three

@Child Slot⁠

s are automatically generated:

@Notification fail⁠

@Notification no account⁠

and

@Notification success⁠

These

@Child Slot⁠

s cannot be changed and can only be deleted with a

@Parent Slot⁠

The location of

@Child Slot⁠

s is determined automatically; they cannot be moved:

⁠

@Notification fail⁠

is always the topmost

@Subslot⁠

in a given

@Complex Slot⁠

;

⁠

@Notification no account⁠

is always the second in order

@Subslot⁠

in a given

@Complex Slot⁠

;

⁠

@Notification success⁠

is always the lowest

@Subslot⁠

in a given

@Complex Slot⁠

You cannot add new

@Subslot⁠

s to the

@Parent Slot⁠

@Notification⁠

Subslot attributes

Notification Fail

⁠

1. Name — the name of the

@Slot⁠

, which will be displayed in the

@Script Tree⁠

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

Notification No Account

⁠

Name — the name of the

@Slot⁠

, which will be displayed in the

@Script Tree⁠

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

Notification Success

⁠

Name — the name of the

@Slot⁠

, which will be displayed in the

@Script Tree⁠

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

Notification Webhook Slot Request

The

@Notification⁠

@Slot⁠

allows the

@Agent⁠

to accept a

@Mailing Request⁠

in the form of an

@Incoming Request⁠

to the Chatbot webhook (from the General tab), incl. to a non-existent

@Chat⁠

(in this case the Chat will be created)

⁠

The

@Mailing Request⁠

must include the identifier of the recipient in the destination channel, which is part of the

@channel_chat_id⁠

and is used to generate the

chat_id⁠

(for example, the phone number in the case of

@360Dialog (WhatsApp)⁠

). Based on this identifier, the Platform will determine the chat or, if it does not exist, create a new chat for sending the request.

The

@Mailing Request⁠

can be urgent or non-urgent (parameter ”is_urgent"):

value true — for an urgent

@Mailing Request⁠

— it is executed immediately and interrupts the

@Active Dialog⁠

value false — for a non-urgent

@Mailing Request⁠

— it is executed after closing the

@Dialog⁠

if the key is_urgent is not found, the default value false is used.

Important: in the
@Notification⁠

@Slot⁠
the search for the ”is_urgent" parameter will be performed only in the request body, unlike the
@Incoming Request Slot⁠
, where the search for the ”is_urgent" parameter is performed in both the body and the request parameters in the URL.

Requirements for the

@Mailing Request⁠

POST request with a valid JSON body and header ”Content-Type": "application/json".

The

@Mailing Request⁠

body at the first level of the JSON must include a valid identifier of the

@Bot User⁠

in the

@End Channel⁠

, the key name depends on the type of

@End Channel⁠

The default

@Limit on mailing requests⁠

is 20 requests per second per

@Company⁠

. The limit can be changed through technical support.

Example of a

@Mailing Request⁠

@360Dialog (WhatsApp)⁠

: POST <http://localhost:10040/notification/13::9de6d0fbc9a547659457a0f7a0e21eda/chat> headers: {"Content-Type": "application/json"} body: { "phone_number": "79291642944", "is_urgent": true, "extra": { "foo": 42 } }

Example of a

@Mailing Request⁠

@Edna Pulse⁠

: POST <https://admin.chatme.ai/api/notification/42282::0a04b116e59032ef014d649602cc0b54/chat'> headers: {"Content-Type": "application/json"} body: { "phone_number": "79291642944", "is_urgent": true }

Example of a

@Mailing Request⁠

@Chat2Desk⁠

: POST <https://admin.chatme.ai/api/notification/42282::0a04b116e59032ef014d649602cc0b54/chat'> headers: {"Content-Type": "application/json", "Authorization: 3cb81e05cf1679e1af9e5d9164ab89"} body: { "phone_number": "79291642944", "is_urgent": true }

The authorization token is taken from the Chat2Desk personal account:

Chat2Desk⁠

Slot operation

The

@Slot⁠

operation begins from the moment the Platform receives a

@Mailing Request⁠

from an external system.

1. Processing Incoming Mailing Request

The following operations are performed in the specified order:

Checking the

@Mailing Request⁠

Body Size:

The size of the request body for the

@Mailing Request⁠

is checked:

If the size exceeds 100 KB:

The request body is replaced with {}.

Otherwise, proceed to the next operation.

Checking the

@Mailing Request⁠

Limit:

If the

@Limit on mailing requests⁠

is exceeded:

The request processing is stopped.

Send a response to the

@Mailing Request⁠

with the status: HTTP status: 404.

Checking the Method of the

@Mailing Request⁠

If the method used for the

@Mailing Request⁠

is not a POST method:

The request processing is stopped.

Send a response to the

@Mailing Request⁠

with the status: HTTP status: 405.

Checking the content-type: application/json Header:

If the

@Mailing Request⁠

does not have the content-type: application/json header:

The request processing is stopped.

Send a response to the

@Mailing Request⁠

with the status: HTTP status: 400.

Validating the Correctness of JSON:

If an invalid JSON is found in the request body of the

@Mailing Request⁠

The request processing is stopped.

Send a response to the

@Mailing Request⁠

with the status: HTTP status: 400.

Finding the

@Bot User⁠

ID:

If the

@Bot User⁠

ID is not found or is invalid:

The request processing is stopped.

Send a response to the

@Mailing Request⁠

with the status: HTTP status: 405.

Finding the active

@Project Channel⁠

If the

@Project Channel⁠

for the notification slot is deleted or inactive:

The request processing is stopped.

Send a response to the

@Mailing Request⁠

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

Determining or creating a

@Chat⁠

The system finds an existing chat based on the

@Bot User⁠

ID ("phone_number") or generates a new one if the chat is not found.

Finding the "is_urgent” Parameter:

Creating a

@Mailing Task⁠

A mailing task is created with a unique task ID, which is recorded in the system context variables

@notification_task_id⁠

Queuing or Starting the

@Mailing Task⁠

2. Execution of Mailing Task

Initialization of System Variables.

Parsing User Variables in Notification Slot parses data from the

@Mailing Request⁠

into a

@Context Variable⁠

according to the settings on the Incoming Data tab:

If the data fails to parse and the

@Context Variable⁠

exists, its value remains unchanged.

If the data fails to parse and the

@Context Variable⁠

does not exist, it is not created.

Preparing the Request to the Channel assembles the request to the

@End Channel⁠

from the parameters on the Destination tab and the

@Bot User⁠

ID (phone_number):

If the request fails to be constructed for any reason, the

@Notification⁠

@Slot⁠

execution is terminated, the request is not sent to the

@End Channel⁠

, and it transitions to the

@Notification fail⁠

branch. In this case:

the

@notification_raw_status⁠

is set to {‘description’:’failed to build request’};

the

notification_status⁠

is set to ‘failed’.

If the request is successfully constructed, its body is stored in

notification_raw_request⁠

Sending the Mailing Request to the Channel and Handling Channel Responses The

@Notification⁠

@Slot⁠

sends the mailing request to the selected

@End Channel⁠

If the End Channel accepted the request and responded with a successful response, then:

{‘description’:’received by channel’, ‘channel_response’: body of the response from the channel (object}is written to

@notification_raw_status⁠

⁠

'sent' is written to

@notification_status⁠

If the request to the

@End Channel⁠

is sent, but a response with code 4xx or 5xx is received in response, then:

{‘description’:’channel error <response code> ‘channel_response’: body of the response from the channel} is written to

@notification_raw_status⁠

;

‘failed’ is written to

@notification_status⁠

There is a transition to the

@Notification fail⁠

branch.

If the request to the

@End Channel⁠

failed (the channel is unavailable, ping does not work, etc.), then:

{‘description’:’channel inaccessible’} is written to

@notification_raw_status⁠

‘failed’ is written to notification_status;

There is a transition to the

@Notification fail⁠

branch.

3. Transition to subslot branches and responses from the channel

The transition to the

@Notification fail⁠

branch occurs in the event of any problems related to this specific mailing task, except for the lack of an account on this

@Bot User⁠

ID. In case of such an error:

{‘description’:’channel couldn’t sent message’, ‘channel_response’: response body from the channel as is (object)} is written in

@notification_raw_status⁠

If a JSON object was received in response to the launch of a mailing, then this JSON object is stored in 'channel_response'. If the response contains text, the text is saved. Otherwise, None is saved.

‘failed’ is written to

@notification_status⁠

⁠

The transition to the

@Notification no account⁠

branch occurs if there is no account on the given

@Bot User⁠

ID (in the case of WhatsApp, phone number). Wherein:

{'description':'no account on <phone number\key identifier of the interlocutor>', 'channel_response': body of the response from the channel as is (object)} (if application/json = object, if text = str) is written in

@notification_raw_status⁠

; in other cases, null is written).

'no_account' is written to

@notification_status⁠

;

The transition to the

@Notification success⁠

branch occurs upon receipt of the Technical status of the mailing — the statuses of sending, delivery and reading of the message by the

@Bot User⁠

in the messenger ('sent', 'delivered', 'read'), or

@Bot user’s Message⁠

If the transition to