The Configs Folder

The Configs Folder

To store data, Communications Orchestrator has the following State Diagrams:

• User Profile - users’ profiles received from bots.
• Chats - by userId - saved dialogs with userId reference.
• Chats - by eventId - saved dialogs with eventId reference.
• Attachments - templates of message attachments are stored in JSON.
• Tokens - access tokens to bots in messengers and credentials for integration with Simulator.
• Localization - texts for content localization.
• Simulator Cache - cache of the main Simulator entities for a quick access.

The Communications Orchestrator processes interact with the state diagrams using the dynamic construction for data receiving.

User Profile

This state diagram stores user data. A new user profile is created when this person refers to the bot for the first time; then this profile is updated in the future activities.

A task with user data is created and edited in the Main Process using a reference of the strict template:

{{channel}}_{{chat_id}}, where:

• channel is the name of a messenger a user referred from
• chat_id is unique user identifier in the messenger

Example: viber_2yOPxC85DSpJCJHpYzjqTw=

As the channel and chat_id parameters are required in all the Communications Orchestrator processes, the user data can be received and edited at any step.

Attachments

Along with text messages, the Messengers support various Attachments to the messages, like buttons, keyboards, carousels, and so on.

The Attachments state diagram stores all the objects describing the Attachments. When adding an Attachment to this Diagram, it is recommended to specify the name of Task Reference according to the target action for which this Attachment will be used, for example, mainMenu for displaying the Main menu, exit for a button to exit the current process, etc.

This value is given in the attachment_id parameter when sending a message to a user.

To send a message with an Attachment to a user, a bot uses the following logic:

1. The Send Message process uses dynamic construction {{conv[{{attachment_state_diagram_id}}].ref[{{attachment_id}}]}} to receive an object that describes all Attachments for all messengers.
2. The attachment parameter gets an Attachment that matches the channel parameter.
3. The Attachment is localized. Texts from Localization are put instead of all the {{t'<key>}} variables.
4. Values are dynamically inserted into the Attachment. The values of parameters incoming to the Send Message Process with a Task are put instead of all the {{param}} parameters, which are used in the Attachment description.
5. The composed message is sent to a user.

Example

By default, the Attachments state diagram has samples of ready-made Attachments, for example, mainKeyboard - the main menu keys:

Facebook Messenger:

Viber:

Telegram:

Apple Messages for Business:

More details on attachment types you can find in the API documentation of each messenger:

• Viber
• Facebook Messenger
• Telegram
• Apple Messages for Business

Attachment JSON Example:

REF: exit

    {
        "telegram": {
            "type": "inline_keyboard",
            "buttons": [
                [{
                    "text": "🚪 {{t'exit}}",
                    "callback_data": "/exit"
                }]
            ]
        },
        "viber": {
            "type": "keyboard",
            "buttons": [{
                "Columns": 6,
                "Rows": 1,
                "BgColor": "#F3F3F3",
                "Text": "🚪 {{t'exit}}",
                "ActionType": "reply",
                "ActionBody": "/exit",
                "TextVAlign": "middle",
                "TextHAlign": "center",
                "TextSize": "regular",
                "Silent": true
            }]
        },
        "facebook": {
            "type": "quick_replies",
            "buttons": [{
                "content_type": "text",
                "title": "🚪 {{t'exit}}",
                "payload": "/exit"
            }]
        }
    }

What is Dynamic Attachment for and how it works

When developing a bot, there is often a need to display data of a homogeneous structure, like a catalog of products, a cart with selected goods, a list of current special offers, etc.

The Send Message Process supports the creation of Attachments using a template for a varying number of items.

Adding a Template

Let’s discuss how to add a template using an included-in-attachment template for displaying exchange rates.

JSON Example (Dynamic attachment)

REF: carousel_pattern

{
         "attachment": {
             "facebook": {
                 "type": "carousel",
                 "items": [{
                     "title": "{{value}} {{name}}",
                     "subtitle": "1 USD"
                 }]
             },
             "viber": {
                 "type": "carousel",
                 "carouselRows": "1",
                 "carouselColumns": "6",
                 "items": [{
                     "Columns": 6,
                     "Rows": 1,
                     "ActionType": "reply",
                     "ActionBody": "none",
                     "Text": "1 USD = {{value}} {{name}}",
                     "TextSize": "small",
                     "TextVAlign": "middle",
                     "TextHAlign": "middle",
                     "Silent": true,
                     "BgColor": "#FFFFFF"
                 }]
             }
             "abc": {
        "type": "text_list_picker",
        "maxItemsCountToShow": 10,
        "items": [
            {
                "identifier": "{{name}}",
                "order": 0,
                "style": "small",
                "subtitle": "per 1 EUR",
                "title": "{{value}} {{name}}"
            }
        ],
        "order": 0,
        "title": "💱 {{t'/exchangeRates}}",
        "multipleSelection": false,
        "receivedMessage": {
            "style": "small",
            "subtitle": "",
            "title": "💱 {{t'/exchangeRates}}"
        },
        "replyMessage": {
            "style": "small",
            "title": "💱 {{t'/exchangeRates}}",
            "subtitle": ""
          }
        }
      }  
    }

The Items Sourcing Array

For creating a carousel, an array is needed for providing values to the template:

"items": [
    {
        "title": "4.183966 AED",
        "subtitle": "1 USD"
    },
    {
        "title": "85.890287 AFN",
        "subtitle": "1 USD"
    }
]

Converting JSON

When calling the Send Message Process, it is necessary to pass the following parameters:

{
    "attachment_id": "carousel_pattern"
    "items": "items"
    "currentPage": 1
    "disableExitButton": false|true (a flag to show the Exit button)
}

A Code node named createDynamicAttachment does all other necessary actions over an object.

The Send Message Process considers messenger limitations and does corresponding pagination automatically: it breaks the array into pages and adds the navigation buttons. The Exit button is added if disableExitButton = false.

The Converted JSON:

 "message": {
     "quick_replies": [{
         "content_type": "text",
         "title": "🚪 Exit",
         "payload": "/exit"
     }],
     "attachment": {
         "type": "template",
         "payload": {
             "template_type": "generic",
             "elements": [
                {
                     "title": "4.183966 AED",
                     "subtitle": "1 USD"
                 },
                 {
                     "title": "85.890287 AFN",
                     "subtitle": "1 USD"
                 },
                 ...
             ]
         }
     }
 }

Examples of Displaying:

Facebook Messenger

Viber

Apple Business Chat

Localization

The Localization state diagram stores all texts of all messages and attachments in one Task:

Task example:

REF: localization

    {
        "/exit": {
            "en": "Exit",
            "ru": "Выход",
            "uk": "Вихід"
        },
        "mainMenu": {
            "en": "Main Menu",
            "ru": "Главное меню",
            "uk": "Головне меню"
        },
        "no": {
            "en": "No",
            "ru": "Нет",
            "uk": "Ні"
        },
        "yes": {
            "en": "Yes",
            "ru": "Да",
            "uk": "Так"
        },
        ...
    }

This approach allows you to:

1. Manage all bot texts from one place.
2. Send messages by only specifying a key of the necessary text in the localization object.
3. Localize bot interface. By default, the texts are in the en, ru and ua, languages, but any language can be added.

To send a text message, you need to specify the key name key from the localization task as a value of the text_id parameter.

Example. To send the Main menu to a bot, you need to provide the Send Message process with the following parameters and values:

{
    "attachment_id": "mainKeyboard",
    "channel": "viber",
    "chat_id": "...",
    "text_id": "mainMenu"
}

For localization, attachments should have their parameters of UI texts (button names, labels, etc.) to meet the {{t'<key>}} template, where <key> is the key of a necessary text in the localization object.

Example. Localization of the Exit button:

{
    "content_type": "text",
    "title": "🚪 {{t'/exit}}",
    "payload": "/exit"
}

The Send Message process sends a message in the same language as stored for a user in the User Profile state diagram. The default language is en and can be changed in the Set Parameter node named SET default language == EN of the Send Message process.

Tokens

This state diagram stores bots access tokens and credentials for integration with Simulator.

JSON Example

REF: token

{
"abc": "",
"facebook": "",
"simulator": {
    "token": "",
    "developersGroupId": "",
    "id": "",
    "accId": "",
    "baseUrl": "https://api.simulator.company/v/1.0"
},
"slack": "",
"telegram": "",
"viber": ""
}