Chatbot elements

API

Use the API element when you need to retrieve and send information to and from external systems through your chatbot. The element is made up of simple request and response parameters.

Start by defining the request method which can be any of the standard API methods (POST, GET, PUT, PATCH, DELETE), then provide the base URL to your external system along with the required endpoint.

Use the escaping option to replace all characters that are deemed “unsafe” by web standards. For example, if you have parameters in your URL that will return an empty space, this will escape that character and return a valid URL.

There are several options of content type for the API call and depending on what you select, you will be given the option to either use a Key-value pair and/or the Editor where to write the body of the API call.

• None - Select if your API has no body (only header)
• Raw - Use for unstructured requests (for example containing only numbers or blocks of texts). Also, can be used for content types not available on the predefined list (text/xml for example)
• JSON - Commonly selected for most REST API calls. For the body you can choose between key-value pair(s) or writing in the Editor
• Text - Supported only through Editor
• XML - Supported only through Editor
• URL-encoded - Sends the body as key-value pairs in one query
• Form Data - Used when sending binary (non-alphanumeric) data or a significantly sized payload

Headers are optional but this is where data is sent in the URL. Data is entered in Key-Value format. Body is also optional and contains the data sent along with the URL. Body is entered in Key-Value format or using the Editor to manually add the body. These options depend on what content type you have selected, for example, you can only use Body for raw data.

For all content types except None and Raw, the header key-value pair will have a predefined value specifying the type. After that, if you need additional values in your header, you can select them from the list of most commonly used header options (authorization, cache-control, cookie, etc.)

The list is not definitive. If a key-value pair is not on the predefined list, use the Add option to add the values needed for your API call.

Responses to API calls are saved to attributes. To save the response you expect to receive, go to the Response tab. In case you want to save response types to your APIs (whether they were successful, bad, unauthorized, etc.), you can select an attribute from the Response code dropdown list.

When you expect values in the return body of your API call and want to save them, use +Add attribute and select the appropriate one from the list of existing attributes (or more than one depending on your API).

You will also need to enter the path to the attribute. The path is the location in the JSON file hierarchy where the value of that attribute is located. Depending on the level where the attribute is located, all the previous levels need to be included in the attribute path separated by a dot “.”.

The Timeout in seconds is how long you want to wait for the response – default setting is 10 seconds and the maximum you can set is 60 seconds The minimum is 1 second.

If you want to see how to save received XML files, check out the section on the topic.

SOAP API calls can only be sent in XML format, meaning that there can only be one root element in that file, acting as the envelope.

There are two ways to write XML for SOAP API calls in answers: 

• Content type Raw and in the Header enter key-value pair: Content-Type + text/xml
• Content type XML where you will have a predefined header value for the selected content type (application/xml)

When deciding between the two, consider that if a user can read your XML document (the source XML document), text/xml is preferable to application/xml. In either case, only Editor is available for xml configurations.

Most SOAP APIs use WSDL (Web Service Definition Language). WSDL defines the structure of the xml, for example, if an element or attribute can appear multiple times, whether it is required or optional, or the order of the elements. If the service you are interfacing with has a WSDL, it will be much easier to connect with it.

SOAP response xml will follow the same logic as the incoming request, and in case of an error, will contain the message detailing.

Considering that SOAP APIs are slower and more complex than REST APIs, that they cannot handle anything except XML files and do not cache information, it is recommended to use REST communication protocol in Answers.

At the moment, SOAP calls accept the values of text, xml, and xml list. The choice depends on how you want to use values later in the Coding element (whether there are xml tags you want to extract from the response you receive).

Attribute

Use attributes to capture and store information against the attributes you have added in the Attributes tab by providing a request and allowing the user to respond.

The response is stored against the attribute and can be used, quoted, and can act as part of the chatbot's logic down the line in the customer journey.

The attribute element works in the same way you would send a generic text element, but you will additionally need to define which attribute to store responses against.

You will already have to have your attributes created in the Attributes tab to be able to use this element. Or you can use the quick-create option directly in the chatbot editor to add attributes. Existing attribute types are non-configurable here.

Use the skip option if your chatbot is using NER attributes and the attribute already has a prepopulated value. This'll be because the customer would have already mentioned the relevant information earlier on, and your NER-enabled chatbot will have captured it.

If you are using the Attribute element after a button element or reply or quick reply, make sure to leave the text field in Attribute empty as the postback value defined previously will be used as the user response to be saved to the attribute. 

Link previews are used to display a preview in the chat for channels which support this function.

The validation regex pattern allows you to enter your own regex pattern for attribute value validation. The validation based on regex supports BRE (Basic Regular Expressions) standard. Regex is useful in situations where you want to check, match, or validate different inputs, like check if a string contains numbers, or validate if the input is a phone number.

The Repeat option lets you set how many times a user can provide an unrecognized response or action before the fallback option is triggered. Set the number of times they can repeat an attempted response.

Fallback is used in cases where the user is provided an unknown response or action. Set whether to send them to another dialog if this happens, or whether to transfer them to an agent, as well as an optional message if required.

Audio

Send audio files when you need your chatbot to send pre-recorded messages or voice notes. Send audio either by directly uploading into the Answers editor or by providing a direct open URL. The link option also supports attributes if you need to customize the URL.

Add an optional quick reply option(s) to let customers respond directly to the message with the requested information.

Supported audio files differ depending on which channel your chatbot is using. Make sure to check out the relevant Message types sections for each channel type.

Authenticate

The Authentication element is only available for the Authentication dialog and is used to trigger authentication at the end of authenticated dialog flows.

Set up a secured chatbot using authentication

Button

Send options for the user to select from when they receive this message. Add buttons and define their postback values, rather than letting the user input their own value. This allows you to capture the specific responses you need from users.

Provide a button message, then use the add options to add generic buttons or buttons based on attribute values. 

Carousel

Carousel messages enable you to send multiple rich cards in a single message. In addition to text, you can include an image, a hyperlink, and buttons for each rich card. End users can use horizontal scroll to view the rich cards, compare the items, and take action for individual rich cards.

To add a carousel, drag and drop the Carousel element from Chatbot sends.

Cards: Add rich cards to the carousel. You can add them either manually or from a list attribute. 

To add a rich card manually, click Add card. To add a rich card from a list attribute, select Build multiple cards from list attribute.

Each rich card contains the following elements:

• From attribute: The attribute used to create the rich card. Applicable if you create a rich card from a list attribute
• Item name: Applicable if you create a rich card from a list attribute
• Title (optional): One line with a maximum of 80 characters
• Description: Maximum of three lines. Maximum of 240 characters totally
• Either upload an image or add the URL for the image. Supported file types are .jpg and .png. Even if one rich card has an image, all other rich cards must also have an image
• Buttons: Maximum of four buttons

Buttons: You can add buttons either manually or from a list attribute. To add a button manually, click Add button. To add a button from a list attribute, select Add button from list attribute.

Buttons contain the following elements:

• From attribute: The attribute used to create the button. Applicable if you create a button from a list attribute
• Iteration label: Name of the attribute value placeholder. Applicable if you create a button from a list attribute
• Button title: Text that is displayed on the button. Maximum of 32 characters, including spaces.
• Button action and Postback: Choose an action. Depending on the action, specify the postback value.

Button action		Postback
Postback	Instead of typing a reply to your message, end users can click these buttons to send you a predefined reply. This enables you to capture specific responses from end users.	Postback value
URL	Share a URL. When end users click the button, the link opens.	URL of the website

Quick replies (optional): You can add a maximum of 10 quick replies to the carousel. Quick replies are for the entire carousel and are not specific to a rich card. 

You can add quick replies either manually or from a list attribute. To add a quick reply manually, click Add quick reply. To add a quick reply from a list attribute, select Add quick replies from list attribute.

Quick replies consist of the following elements:

• From attribute: The attribute used to create the quick reply. Applicable if you create a quick reply from a list attribute
• Iteration label: Name of the attribute value placeholder. Applicable if you create a quick reply from a list attribute
• Button: Text displayed on the quick reply button. Maximum of 25 characters

For more information about carousels, refer to the Live Chat documentation.

Close session

Use this element to terminate the entire session. This element is not configurable and only works y ending the chat with the end user when they reach this stage of the conversation.

If the user continues to talk with a chatbot that has closed the session, the chatbot will treat it as a new session and will start afresh. 

It requires no configuration – but bear in mind that when you add it to the dialog, the element will finish the conversation between the end user and the chatbot. In case the user wants to continue talking with the bot, they will have to start the conversation from the beginning.

Code

Coding element gives you more flexibility when designing a dialog and what you can do with attribute values, and also provides encryption capabilities.

Currently, two classes are available:

• attributeAPI which enables you to work with the attributes in the platform using the following functions:

► GET

► SET

• encryptionUtils which currently supports the following hash functions:

►MD5,

►SHA-1,

►SHA-256,

►SHA-512

You can use the element for the following:

• randomization of available information

const items = [1, 2, 3, 4, 5];
const item = items[Math.floor(Math.random() * items.length)];
attributeApi.set('random', item);

• Usage of counters (can be followed by the Conditions element to branch the results)

let correct = attributeApi.get('correct');
correct = correct == null ? 1 : (correct + 1);
attributeApi.set('correct', correct);

• Transfer of large json files into variables (for easier manipulation of attributes)

const qa = attributeApi.get('qa');
let answers = [...qa.incorrect_answers, qa.correct_answer];
answers.sort();
 
const answerId = answers.findIndex(a => a === qa.correct_answer);
 
attributeApi.set('answers', answers);
attributeApi.set('answerId', String(answerId + 1));
 

• Secure hashing of attributes

const encryptedMd5 = encryptionUtils.md5('test');
const encryptedSha1 = encryptionUtils.sha1('test');
const encryptedSha256 = encryptionUtils.sha256('test');
const encryptedSha512 = encryptionUtils.sha512('test');

 

The Answers platform compiles and validates whether the code syntax is correct (will not display where the error occurs). The validation happens at the moment you activate the bot and an error will occur in case validation fails.

const encryptedMd5 = encryptionUtils.md5('test');

const encryptedSha1 = encryptionUtils.sha1('test');

const encryptedSha256 = encryptionUtils.sha256('test');

const encryptedSha512 = encryptionUtils.sha512('test');

const qa = attributeApi.get('qa');

let answers = [...qa.incorrect_answers, qa.correct_answer];

answers.sort();

 

const answerId = answers.findIndex(a => a === qa.correct_answer);

 

attributeApi.set('answers', answers);

attributeApi.set('answerId', String(answerId + 1));const encryptedMd5 = encryptionUtils.md5('test');
const encryptedSha1 = encryptionUtils.sha1('test');
const encryptedSha256 = encryptionUtils.sha256('test');
const encryptedSha512 = encryptionUtils.sha512('test');

Conditions

Use conditions to set up branching logic depending on the attribute values received back from users. This allows your chatbot to proceed down different routes once they get the information they need.

Drag the conditions element into the chat journey after a point where you are expecting to receive a response and add as many conditions as required based on the possible inputs.

Start by selecting an attribute in a condition, then select an operator to work with (matching, containing, not containing, not matching, null). Available operators change depending on the attribute type (e.g. if an attribute is a boolean, only 'is' and 'is not' is selectable).

Then provide the match data in the value field to run the condition against. Null operators do not require any match data.

When you have added all of your required conditions, you can then continue to build the customer journey by dragging the relevant channel elements under each condition in the editor.

Conditions always display an Else route for cases when conditions can be matched against anything. Use this route to tell the chatbot what to do in this case (to another dialog, send a message, etc.)

To reduce the number of branches in dialogs, each dialog can have only one Conditions element. Each branch in the Conditions element can have a maximum of two elements.

If you don’t add the To dialog element, the NLP engine will take care of the conversation by resolving the intent and selecting the appropriate dialog to continue the conversation for intent-driven chatbots.

CSAT survey

Customer Satisfaction surveys are added at the end of dialogs when the conversation is coming to a close. They are used to gather important feedback from the customer about the level of service they received through the chatbot, thus acting as a powerful tool for optimization.

CSAT surveys are usually made up of a numeric score, text, and a feedback question. Scores are always required and can be in the following configurations: 1-2, 1-5, or 1-10. Use the text field as required to as whatever information you want, or to explain the scoring logic.

Set a feedback question to let customers respond with a personal note. Use fallback messages to tell customers their inputs are not recognized.

Answers will assume the following logic based on CSAT scores:

• 1 - 2 scale: 1 = negative | 2 = affirmative
• 1 - 5 scale: 1 to 3 = unsatisfied | 4 to 5 = satisfied
• 1 - 10 scale: 1 to 6 = unsatisfied | 7 to 10 = satisfied

Delay

Use the delay element to add as long or as short pauses as desired to mimic the natural tempo of talking to a human. Delay simply adds a pause between elements.

Insert the delay between any elements where it would fit in a normal conversation, and set the delay time in seconds.

File

Send files and documents directly to end users either by uploading the file in the Answers editor or by providing a link to the file.

Supported file formats depend on the channel that your chatbot uses. Refer to the Message types section for the relevant channel.

For WhatsApp, you can either define the individual file types that the chatbot should handle or you can set to all.

Live Chat

Live Chat is a real-time two-way communication channel that helps businesses communicate with end users. 

Integrate Live Chat into your company website or app, End users can use your Live Chat chatbot to request immediate assistance while browsing.

Live Chat offers a variety of message types such as carousels and buttons. Refer to the messaging limitations for each message type.

To use Live Chat in Answers, you must enable this channel in your Infobip account.

Message randomization

Answers enables you to vary the messages you send to your end users and enables you to enter up to 5 different messages for one text field. There are a few ways you can set up the randomization logic:

• Text
• Attributes
• Repeats and fallbacks

This means that every time your end user is in the situation to receive a message that has this option configured, the system will randomly select one of the available messages to send to the end user, thus making the user experience varied.

To add message randomization, use the +Add variation option in channel elements to add additional messages.  You can add a maximum of 5 messages to be sent at random.

People

Connect to the Infobip People solution which allows your chatbots to go and find the required data on your customers, using the existing information you have stored against their profiles. This information can be used in customer journeys and updated along the way by updating people profiles.

By connecting to People you can also update and create new customer profiles when a profile is not found. This allows you to capture and store information effortlessly.

Add the People element to a dialog and select an action of what you need the system to do at this stage. You can either select to go and find information or to create/update a profile depending on the scenario.

Set up a chatbot integrated with People

Text

Send text-only messages and use personalization options in conjunction with attributes, objects, links, and emojis. If you are using links, use the link preview option to auto-display previews in messages. Note however not all channels support this. This option is enabled by default.

Character limits differ depending on which channel your chatbot is using. Make sure to check out the relevant Message types sections for each channel type.

To agent

Send customers to live agents when your chatbot can no longer assist them with their requests. This element is used in cases where intents are no longer able to be resolved, or the chatbot is not recognizing any user inputs.

You must have the Infobip Conversations solution enabled to use this option. Once redirected to an agent in Conversations, a human will be able to take over the support request over chat. Chats cannot be sent back to the chatbot.

Use tags to route the support request or chat to the right queue in Conversations.

If your chatbot is secured and is using sensitive attributes, support center agents will not be able to see any comprehensible values for these attributes.

To dialog

Use this element when you are ready to send the user on to another dialog when they reach this point in the conversation. It can be to a dialog with an intent to finish the conversation, or it can simply be a transition to a new dialog based on a different intent where the end user is asking for new information.

For intent-driven chatbots, you can select which attributes to be transferred over to other dialogs. Use the share attribute option to enable the attribute selector.

You can add as many attributes as you have set up already, but make sure to take into consideration those which are used in the intent and have values that can be transferred. Once selected, the attribute is no longer selectable.

User input

User inputs are used by taking the value of the response by users and applying further logic to the chatbot. There are a few ways you can set up the user input logic:

• Keyword recognition
• Natural language processing
• Repeats and fallbacks

You need to have your keywords already added and set up in the Keywords tab. You chatbot will recognize keyword inputs from users matched with your configured keywords. This allows you to route the dialog on to the next step depending on what the user responds with.

Use the +Add option to add a new keyword to the user input element, and select from the dropdown list from your existing keywords.

In addition to using keywords mapping to direct the conversation, you can also enable the NLP engine to process input in case the correct keyword or keyword synonym is not entered.

You can learn more about how NLP engine processes data under Advanced Options - NLP.

Chatbots always need to have logic set up in cases where they don't know how to handle a request on response. The first option is to ask the user to try answering again before moving them on to a fallback option. Configure the repeat settings to determine how many times they can try answering again, along with any text to go with it.

Link previews are used to display a preview in the chat for channels which support this function.

Lastly, configure the fallback option so the chatbot knows what to do in cases where user input has not been successful. Using fallbacks you can route users to another dialog, or offer them to connect to a human if you have a support center.

Video

Send pre-recorded videos either by directly uploading into the Answers editor or by providing a direct open URL. The link option also supports attributes if you need to customize the URL. Add an optional caption to your video.

Supported video formats differ depending on which channel your chatbot is using. Make sure to check out the relevant Message types sections for each channel type.

Webhook

Webhooks are user-defined HTTP callbacks in a webpage which are triggered depending on a specific and defined event, for example when a user is required to provide authorization criteria. They are generally used for real-time notifications and data synchronization.

When triggers occur, webhooks register events, collect the required data, and send it back to your specified URL in your HTTP request. Using the example above, the trigger event would be requiring the user to provide authorization criteria, and where you want that information to be sent.

In Answers, webhooks usually follow the API element whereby you would use the API element to send the webhook URL to an external system. Once the requested data or criteria become available, the webhook destination URL sends the request back. The webhook then saves the response and saves it to a defined attribute.

Start by defining the webhook URL type to use the sessionID as a parameter or to use it in the body of the request. The Webhook URL is predefined and should not be changed, depending on the webhook URL type, it will update itself

Set the Method to either POST or GET then define the Attribute(s) where the values will be saved.If you use Body parameter sessionID you can only use it with the POST method, and you need to define the sessionID body parameter name that will be automatically added to the Webhook URL.

If you are using the POST method, you can select an attribute from the Attribute dropdown list, and in this case, what you need to define is the path to the parameter where that value is saved.

The path is the location in the JSON file hierarchy where the value of that attribute is located, levels are defined by the number of entries separated by a dot “.”.

Maximum throughput per endpoint is 100 requests per second. Maximum throughput per endpoint per IP is 50 requests per second.

If using the GET method, and you want to save the value to an attribute, select the attribute from the Attributes dropdown list and define the Query parameter which contains the required value.

Webhook request codes:

• 200 - Successful
• 40401 - Unsuccessful. No session
• 40026 - Unsuccessful. Session cannot handle request

Example: Webhook element used in conjunction with API element

You need to authorize your end user with an external authorization service, so you use API element to send an authorization request towards the service which contains the webhook URL and you wait for the response

Answers receives the response with the URL for the user authorization and you store that URL in an attribute in Answers (attribute is defined in the API element)

The next step is to ask the user to authorize themselves through the URL you received from the external authorization service. You can use the Text element to send the authorization link to the user

After the user authorizes themselves, the webhook receives a request from the external authorization service with a token that the user is authorized, and that token is also stored in an attribute (for further authorization needs if necessary)

For the receipt of the user authorization and for saving the token, you use the Webhook element where you have defined the method and the attribute where the token value is going to be saved