1. Bot Architecture
1.1. Dialog Structuring
Split the bot design into logical blocks. Those blocks will become bot dialogs.
Example:
In this example the bot will have 6 dialogs:
- Welcome Dialog
- Main Menu Dialog
- Sub Menu 1 Dialog
- Sub Menu 2 Dialog
- Escalation Dialog
- Fallback Dialog
1.2. When to split into separate bots vs consolidate
Complexity - Bot that’s bulky, complex , has more than 30 dialogs, will make sense to split into separate bots. (i.e welcome bot, escalation Bot).
Multiple channels - Bot that’s built for several channels, has a lot of structured content, will be best split into separate bots by channels (i.e web bot, SMS bot, ABC bot). You have to create a separate skill for each channel and name them according to the channel.
1.3. When to split dialogs vs consolidate
Splitting dialogs
Complexity - in case of high complexity, existence of subtopics, will make sense to split the dialog into logical parts and create dialogs from them.
Number of interactions - Dialog should not have more than 10 interactions.
API calls - In case several dialogs are using the same API request, Interaction with API request will need to be in a separate dialog. (Save the "next interaction name" as a variable and route to this interaction after the API interaction)
Consolidating dialogs
Purpose - In case multiple dialogs have identical logical meaning, you can consolidate them into a single dialog.
Example:
Several escalation dialogs that differ only by skill, you can consolidate all of them into 1 Escalation Dialog and use variables to transfer users to correct skill.
1.4. Conversation Builder integrations vs FaaS
Leverage FaaS function
- Multiple API requests are needed simultaneously.
i.e: You need to retrieve 5 cars and show them to user.
- Multiple consecutive API requests.
i.e: You need to get JWT, then get user profile, then user cards.
- Need to always have an actual data.
i.e: JWT has a 2 hour TTL. Rather than making API call for JWT every time when you need it, you can schedule FaaS which will update the JWT every 2 hours.
- Action to specific event needed.
i.e: React on Idle event by closing conversation.
- Same API request from different bots.
Leverage Conversation Builder Integrations
- 1 straightforward API call is needed.
- Short sequence of simple API calls.
1.5. Bot Environments
Bot environments
- Always leverage Bot Environments.
- Environments allow storing configuration data, such as: API domains, skill ids, email addresses, phone numbers
If you use a static email address or support phone number, links, working hours in the bot and these data are different for development and production environments.
In order not to change this data in the bot during deployment, we advise you to store them in the bot environment.
- Environment allows to prevent code duplication and expedite the launch process.
- If you use credentials to make an API call like API Key or API Token, it is better to make this request from FaaS and use FaaS Secret Storage to keep API credentials
2. Bot Implementation
2.1. Naming Conventions
- Numerate your dialog and give it appropriate name:
- Numerate your interactions and give them appropriate name:
This helps to quickly understand the flow of the bot, we also number all the cards in the design, and it is very convenient for the client to find a suitable card and update it if necessary.
If you need to add an extra interaction in the middle of the dialogue, you can always name it 2.1 or 2.2.
- The name of the interaction have to match the name of the card in the bot design:
2.2. Variables
- Get the system data in the init function and save it to variables so that they can be accessed from anywhere in the bot:
- Use created variables in the integrations in order to set headers, query params and payload for POST and PUT API calls:
- Use variables in the interactions to set dynamic data in verbiages. For example you can dynamically set data retrieved from the API call in the next interaction:
2.3. Functions
- Global Helper Functions are recommended and useful for building bots that involve any coding logic that must take place in Pre/Post-Process code or in integrations. Global Helper Functions are recommended to use in global functions that can help to capture needed information and process common methods without the need to write the botContext methods in your bot.
- The functions are designed to simplify the use of pre/post process code. All functions are provided with the dialog template.
- Store your function in global functions, to be able to get access to it at any part of the bot.
2.4. Error Handling
- We should make try-catch blocks inside interactions where there is a block of code which has one or more methods that can throw exceptions needed to be caught. The error will be saved in Custom Log Event.
- Create a dialog to catch the __agent_escalation_failed__ pattern allows you to send an appropriate message to the consumer or close a conversation.
2.5. Logs and Debug
Examples of Logs Custom Event:
botContext.logCustomEvent(interaction, “Caught Errors”, error);
botContext.logCustomEvent(interaction, “LogPreApi”, payload);
botContext.logCustomEvent(interaction, “LogPostApi”, payload);
botContext.logCustomEvent(interaction, “ApiRequestFail”, error);
botContext.logCustomEvent(botContext.getCurrentUserMessage(), “KnowledgeBase”, articleTitle);
botContext.logCustomEvent(botContext.getCurrentUserMessage(), ‘UserJourney’, question);
- Use debug logs during the development to check data received from the API calls, conditioning, and other data that can be helpful during the debug process.
- Use custom logs events to log data that will be helpful during fixes in the long term. Like API calls status, errors.
- Log any error in custom log events. Usually custom log used to log error in integrations, escalations to agent, your custom logic, data validation. Also you can log API statuses, API payloads and etc.
2.6. Integrations
Integrations dependencies
- Requires RESTFul Webservice/APIs for CB bots to integrate with
- Requires XML/JSON compliant response format
- If you have IP restrictions in place, you’ll need to do some whitelisting so that Conversation Builder can make calls to your brand’s systems and vice versa.
Post body have to be object or bot variable which is saved like JSON.stringify(payload)
Use data from bot environments and from bot variables to make an API request
Add permissions for the bot token to make an API call to the certain service
- We do not recommend Transform Result Script and Custom Data Fields, instead process data in integration post-process. Log results / errors:
- In integration pre-process save API payload to Custom Log Event for debugging, don't save PII data:
2.7. Environment
- Use environmental system variables to handle user intermediate response.
- Store any static data, like skillIds, domains, urls and etc. in the environment.
2.8. Rich Content
- Use “Multiple Choice” interaction over other interaction options if possible.
- Use “Button” card only if you need to put link into the button or you are going to use slideout menu.
- Use “Universal‘ card for dynamic card.
- If you want to collect data like zip code, phone, email use “Question” type interaction with regex condition or slots to detect value.
- In rules use bot patterns and evaluate option conditions:
- Do not use pattern * in rules or dialog starters, it can lead to unexpected behaviors.
- Try to avoid using No match conditions, it can break your fallback logic.
2.9. Delays
Set delays in consecutive messages to prevent mixed up cards.
3. Bot Evaluation
To evaluate a bot, need to check for following:
3.1. Agent Connectors
- Production bot should have at least two agent connectors. It's needed for reliable and stable work.
Connectors can only reliably handle 250 simultaneous conversations each
- Custom configuration fields to resolve stuck conversations.
- Connectors should be in production mode.
3.2. Global Functions
- The code must be written in a clean and understandable way.
- Must not contain any hardcoded data, instead static data should be stored in bot environments.
- Getting and saving system data should take place in __initConversation function.
- Creating CCS namespace should be done __initConversation function.
3.3. Dialogs
- Dialogs should have appropriate names that have to reflect the logic in that dialogs.
- Have to not contain more than 10 interactions.
3.4. Fallback Dialog
- Any initial message from a customer should lead to the correct dialog or welcome message.
- Fallback counter attempts should work correctly.
- The first failure should return conversation to the previous interaction.
3.5. Interactions
- Use advanced interactions instead of legacy (Agent Transfer, Dynamic Routing).
- Interactions should have appropriate names and match the name in the bot design.
- Do not use duplication of integrations, it can be handle using variables.
- Use correct patterns in custom rules (a, b, 1, 2).
- Use correct patterns in dialog starters, don’t use * pattern.
- Use custom log event to save all errors and main points of dialogs, don’t store PII.
- Use delays between interaction.
- Use special interactions for the corresponding channel (List Picker, Apple Rich Link).
