Core elements

Core elements are available across all channels. They handle logic, external integrations, data operations, and conversation routing.

API

Use the API element to retrieve information from external systems and send information to these systems through the chatbot.

Configure the request and response parameters in the element. You can also do the following:

• Load an API request configuration by importing a cURL command.
• Retry the API call.
• Configure a fallback option.
• Preview the API call.

Import an API call

You can load an API request configuration by importing a cURL command from your API request collection. The headers and body of the request in the API element are automatically updated from the imported command.

The following are examples of scenarios where you can import an API request instead of configuring it manually:

• You have tested the API call in Postman and want to use the same data in the API element in the chatbot.
• You want to copy an Infobip API cURL command and test it in the API element.

Do the following:

1. In the API element, select Import cURL command.
2. In the cURL field, enter the cURL command for the API. A GET request is made to the API endpoint and the data is fetched from the specified URL.
3. Select Import.

The fields in the element are automatically updated.

Request

Go to the Request tab and complete the following fields.

Method

Choose one of the following API methods:

• GET
• POST
• PUT
• DELETE
• PATCH
• HEAD

URL

Enter the base URL of your external system, along with the required endpoint. You can include placeholders.

The following is an example of a base URL. Do not use it in your code.

https://example.infobip.com/sms/2/text/advanced

where https://example.infobip.com is the base URL used in the send SMS endpoint.

Enable escaping of URL parameters

Select this field if your base URL contains attributes that have one or more of the following:

• Non-ASCII characters
• Reserved characters
• Characters that are unsafe by web standards

Selecting this field replaces these characters.

Example: The base URL has parameters that return an empty space. Enabling the escape option escapes that character and returns a valid URL.

Include mTLS certificate in API request

Mutual TLS (mTLS) is an enhancement of the standard TLS protocol. It adds an extra layer of security by requiring both the client and server to authenticate each other. Both participants in the communication are verified, providing a secure channel that protects sensitive data from unauthorized access.

To include mTLS certificates in your API requests, provide both a valid client certificate and a private key. This enables the chatbot to authenticate itself to the server, while the server also shares its certificate for verification.

To set up and use mTLS certificates, do the following:

1. Set up mTLS certificates: Before making mTLS requests, set up the necessary client certificate and private key. Contact Infobip Support to configure the certificates.
2. Configure API requests: After your mTLS certificates are set up, configure your API requests to include the certificates. In the API call configuration, select Include mTLS certificate in API request.
3. Multiple certificates (optional): You can set up multiple mTLS certificates and choose a different certificate for each API element, depending on your security requirements.

Content type

Specify the type of content for the request header. Example: Choose JSON to indicate that the request data is sent in JSON format.

Depending on the content type you choose, the header and body are as follows:

Headers (optional)

Use the request header to provide information about the request so that the server can customize the response. Example: Use the Accept-Encoding header to specify the required encoding for the response.

This metadata is specified in key-value pairs and is sent along with the request. For some content types, the key-value pair has a predefined value that specifies the type.

If you need additional values in your header, do the following:

1. Select Add key-value pair.
2. In the Key field, select the required criterion from the list. Example: Accept-language.
3. In the Value field, enter the value. You can also add an attribute that contains the value.

If a key-value pair is not in the list, do the following:

1. Select Add key-value pair.
2. In the Key field, select Enter custom.
3. Enter the name of the key.
4. Select the checkmark.
5. In the Value field, enter the value. You can also add an attribute that contains the value.

Body (optional)

Specify the body of the API call. Depending on the content type, you can use a key-value pair and/or the editor.

Key-value pair: To add a key-value pair, do the following:

1. Select Add key-value pair.
2. In the Key field, enter the required criterion. Example: Language. You can also add an attribute that contains the key.
3. In the Value field, enter the value. You can also add an attribute that contains the value.

Editor: Specify the text to include as the body of your request.

Response

Responses to API calls are saved in attributes.

For information about saving XML files received in the response, see How to.

To save the response you expect to receive, go to the Response tab and complete the following fields.

Save response code to attribute (optional)

To save response types to your APIs, do the following:

1. Create an attribute.
2. Select the attribute from the Save response code to attribute list.

Response headers attributes

To save the response header to an attribute, do the following:

1. Create one or more attributes to save the response header.
2. Select Add attribute.
3. In the Attribute field, select the attributes from the list.
4. In the Header name field, enter the name of the header. This field is not case sensitive.

Response body attributes

When you expect values in the return body of your API call and want to save them, do the following:

1. Create one or more attributes to save the response body.
2. Select Add attribute.
3. In the Attribute field, select the attributes from the list.
4. In the Path field, 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, include all the previous levels separated by a dot "." in the attribute path.

Timeout

Specify how long to wait for the response. The minimum value is 1 second and the maximum value is 60 seconds. The default value is 10 seconds.

Fallback

Retry on error

Use this option to retry the request in case of the following errors:

• 408
• 500, 502, 503, 504
• Timeout

For all other errors, Fallback is triggered.

In the How many times to retry field, do one of the following:

• Select the number of times the chatbot must retry the request. You can retry a maximum of 3 times.
• Select No retry if you do not want to retry the request.

Fallback

Use fallback to ensure the end user gets a response from the chatbot even if there is an error — for example, if the request fails or the API element fails.

In such cases, the fallback action is triggered. For more information about configuring these fields, see the Fallback documentation.

Preview the API call

To check whether the API call works as expected, use predefined values that represent real-life scenarios in the payload.

Do the following:

1. Select Preview in the API element.
2. In the Preview API call window, enter sample values in the attribute fields.
3. Select Send request.

The response is generated and displayed in a structured format, such as JSON. You can view the response data in the Body tab and the attributes updated in the Resolved attributes tab.

If there are any errors, a notification is displayed.

Test in the simulator

Use the Simulate feature to check whether the API element has been configured correctly and that it works as expected. In the simulator, you can see the API response that is saved in an attribute.

To simulate the API call, go to the Test tab in your chatbot and start the simulation.

SOAP API calls

SOAP API calls can be sent only in XML format. There can be only one root element, which acts as the envelope, in the file.

Most SOAP APIs use Web Service Definition Language (WSDL (opens in a new tab)). WSDL defines the structure of the XML. Example: Whether an element or attribute can appear multiple times, whether it is required or optional, and the order of the elements. If the service you are connecting with has a WSDL, it is easier to connect with it.

SOAP calls accept the values of text, xml, and xml list. Choose the format depending on how you want to use the values later in the Code element. Example: Whether there are XML tags to extract from the response.

Request

You can write XML for SOAP API calls in the following ways:

Response

SOAP response XML follows the same logic as the incoming request. In case of an error, the XML contains the message details.

SOAP versus REST API

Consider using REST for the following reasons:

• SOAP APIs are slower and more complex than REST APIs.
• SOAP APIs work only with XML files.
• SOAP APIs do not cache information.

Authentication

Use the Authentication element to authenticate the end user within the chatbot flow.

In the chatbot editor, drag and drop the Authentication element from Chatbot actions.

Complete the following fields:

• URL: The URL of the authentication endpoint.
• Method: Choose the HTTP method. Supported methods are GET and POST.
• Headers (optional): Add request headers.
• Body (optional): The request body. Applicable for POST requests.
• Authentication attribute: Choose the attribute in which to save the authentication token or result.
• Fallback: The action to take if authentication fails.

Close session

Use the Close session element to end the chatbot session. After the session closes, the end user must start a new session to interact with the chatbot again.

In the chatbot editor, drag and drop the Close session element from Chatbot actions.

Code

Use the Code element to write custom JavaScript code within the chatbot flow. This enables you to perform complex logic, calculations, data transformations, and other operations not available with other elements.

In the chatbot editor, drag and drop the Code element from Chatbot actions.

Available classes

In the Code field, write your JavaScript code. Use the attributeApi object to get and set attribute values.

Available API methods:

• attributeApi.get('attributeName'): Get the value of an attribute.
• attributeApi.set('attributeName', value): Set the value of an attribute.

Use the encryptionUtils object to hash attribute values.

Available hash functions:

• encryptionUtils.md5('value'): Hash using MD5.
• encryptionUtils.sha1('value'): Hash using SHA-1.
• encryptionUtils.sha256('value'): Hash using SHA-256.
• encryptionUtils.sha512('value'): Hash using SHA-512.

Configure the element

Enter the code manually

In the Code field, enter your JavaScript code directly.

Example: Set the value of an attribute based on a condition.

const score = attributeApi.get('score');
if (score > 80) {
  attributeApi.set('result', 'pass');
} else {
  attributeApi.set('result', 'fail');
}

Use GenAI to create and manage code

Use the built-in GenAI assistant to create, edit, improve, and fix JavaScript code for the Code element.

Create code with AI

1. In the Code element, select Create with AI.
2. Describe what you want the code to do. Example: Calculate the total price from a list of items and save it to the totalPrice attribute.
3. Select Generate.

Review the generated code before applying it. Make any required changes manually.

Edit with AI

1. In the Code element, select Edit with AI.
2. Describe the changes to make. Example: Add a check to make sure the score is a number before comparing it.
3. Select Generate.

Improve code readability

Select Improve readability to format and simplify the existing code without changing its behavior.

Fix code

If the code has errors, select Fix code to let the AI assistant identify and correct the issues.

Use cases

Randomize existing information

Use the Code element to randomize attribute values. Example: Randomly select a message variant or product recommendation.

const options = ['Option A', 'Option B', 'Option C'];
const randomIndex = Math.floor(Math.random() * options.length);
attributeApi.set('selectedOption', options[randomIndex]);

Use counters

Use the Code element to increment or decrement a counter attribute.

let count = attributeApi.get('retryCount') || 0;
count = parseInt(count) + 1;
attributeApi.set('retryCount', count);

Transfer large JSON files into attributes to enable data manipulation

Use the Code element to parse a JSON response saved in an attribute and extract specific values.

const responseJson = JSON.parse(attributeApi.get('apiResponse'));
attributeApi.set('orderId', responseJson.order.id);
attributeApi.set('orderStatus', responseJson.order.status);

Add encryption to attributes

Use the Code element to hash attribute values using encryptionUtils before sending them to an external system.

const value = attributeApi.get('sensitiveData');
const hashed = encryptionUtils.sha256(value);
attributeApi.set('hashedData', hashed);

Component

Use the Component element to add a reusable component to the chatbot dialog. Components are prebuilt sets of dialog logic that you can reuse across multiple chatbots.

In the chatbot editor, drag and drop the Component element from Chatbot actions.

Configure the element

In the Component field, choose the component to add. For more information about components, see the Components documentation.

Conditions

Use the Conditions element to add branching logic to the chatbot. Based on the condition, the chatbot takes different paths.

In the chatbot editor, drag and drop the Conditions element from Chatbot actions.

A condition consists of one or more rules. Each rule compares an attribute value to a specified value using an operator.

Add a Conditions element to the chatbot

Guidelines

• You can only add one Conditions element to a dialog.
• You can add a maximum of 10 conditions.
• Each condition can have a maximum of 10 rules.
• The element has an inbuilt Else condition. You cannot remove or rename this condition.
• Conditions are evaluated in the order they appear. The chatbot takes the path of the first condition that evaluates to true.
• If no condition evaluates to true, the chatbot takes the Else path.

Add the Conditions element

1. In the chatbot editor, drag and drop the Conditions element from Chatbot actions.
2. Select Add condition.
3. In the Condition name field, enter a name for the condition. Example: Is returning customer.
4. Select Add rule.
5. In the rule, complete the following:
   • Attribute: Choose the attribute to evaluate.
   • Operator: Choose the comparison operator.
   • Value: Enter or choose the value to compare against.

Operators:

• Equal to
• Not equal to
• Contains
• Does not contain
• Starts with
• Ends with
• Is empty
• Is not empty
• Greater than
• Less than
• Greater than or equal to
• Less than or equal to

Configure the branches

Each condition creates a branch in the chatbot flow. Connect each branch to the appropriate next element or dialog.

The Default branch is taken when no condition evaluates to true. Connect it to a fallback dialog or element.

Example

Simple condition

Attribute: customerType | Operator: Equal to | Value: premium

The chatbot takes this branch when the end user's customer type is premium.

Condition that uses OR operator

Rule 1: language Equal to en OR Rule 2: language Equal to en-US

The chatbot takes this branch when the language is either en or en-US.

Condition that uses AND operator

Rule 1: orderValue Greater than 100 AND Rule 2: customerType Equal to premium

The chatbot takes this branch when both rules are true.

Condition that uses OR and AND operators

You can combine AND and OR logic within a single condition using condition groups.

Delete a condition

Select the delete icon next to the condition name to delete it.

Remove all conditions

Select Remove all to delete all conditions and start again.

Delete criteria within a condition

Select the delete icon next to the rule to delete it from the condition.

Duplicate a condition

Select the duplicate icon next to the condition name to create a copy of the condition.

Reorder conditions

Drag and drop conditions using the handle next to the condition name to change the order in which they are evaluated.

Rename a condition

Select the condition name to edit it inline.

Conversation tags

Use the Conversation tags element to add tags to the ongoing conversation. Tags help you categorize and filter conversations in Inbox.

In the chatbot editor, drag and drop the Conversation tags element from Chatbot actions.

Prerequisites

Create the tags in Inbox before using them in Chatbots. For more information, see the Inbox documentation.

Configure the element

Select one or more tags to add to the conversation.

Example: redirect to the correct queue

Use conversation tags to route a conversation to the correct support queue in Inbox.

1. In the chatbot flow, identify the point at which the chatbot determines the end user's issue type.
2. Add the Conversation tags element.
3. Select the tag that corresponds to the issue type. Example: billing, technical-support, or sales.
4. Add the To Agent element after the tags element.

When the conversation is transferred to an agent, the tags are visible in Inbox and the conversation can be routed to the correct queue.

CSAT survey

Use the CSAT survey element to send a customer satisfaction survey to the end user at the end of a conversation.

In the chatbot editor, drag and drop the CSAT survey element from Chatbot actions.

Scoring question

Scoring scale

Choose the rating scale for the survey. The following options are available:

• 1–2 scale: 1 = negative, 2 = positive.
• 1–5 scale: 1 to 3 = not satisfied, 4 to 5 = satisfied.
• 1–10 scale: 1 to 6 = not satisfied, 7 to 10 = satisfied.
• Emoji scale: positive, neutral, negative.

Scoring question message

Enter the message to send to the end user with the scoring question. Example: How would you rate your experience today? You can use attributes to personalize the message.

Repeat count

Choose the number of times to repeat the scoring question if the end user does not provide a valid response. The default value is 1. Maximum is 3 times.

Fallback message

Enter the message to send to the end user if they do not provide a valid response after all repeats are exhausted.

Feedback question (optional)

Add an open-ended follow-up question to collect written feedback from the end user. Example: What could we have done better?

Thank you message (optional)

Enter the message to send to the end user after they submit the survey. Example: Thank you for your feedback!

Next steps

Connect the CSAT survey element to the next element or dialog in the flow.

• If you add the CSAT survey element to a standard dialog, add a Close session element after it to end the conversation.
• If you add the CSAT survey element to the Session Expire dialog, no additional element is needed. The session closes automatically.

Guidelines and best practices

• Place the CSAT survey at the end of the conversation, after the end user's issue has been resolved.
• Keep the survey short to maximize completion rates.
• Save the survey results to attributes and use them for analytics or routing.

Analytics

CSAT survey results are available in Chatbots analytics. You can view the average score, score distribution, and individual responses.

Results are also available in advanced analytics:

• Voice of the customer predefined dashboard.
• CSAT metrics in Custom dashboards.

Delay

Use the Delay element to pause the chatbot flow for a specified time before proceeding to the next element. This is useful when you want to simulate a more natural conversation pace or wait for an external process to complete.

In the chatbot editor, drag and drop the Delay element from Chatbot actions.

In the Delay field, specify the delay duration in seconds. Minimum value is 1 second. Maximum value is 30 seconds.

Customer Profiles custom event

Use the Customer Profiles custom event element to trigger a custom event in Customer Profiles. This enables you to track specific end user actions or behaviors during the conversation.

In the chatbot editor, drag and drop the Customer Profiles custom event element from Chatbot actions.

For full instructions on creating custom events and mapping attributes, see Customer Profiles.

Contact information

In the Contact information attribute field, enter the Chatbots attribute that contains the end user's contact information. Example: customerContact.

In the Contact information attribute type field, select the attribute type. Make sure this matches the data type of the attribute selected in the Contact information attribute field.

Custom events

In the Custom event configuration section, specify the event to save against the Person profile.

1. Select Add custom event.
2. Choose the event you created in Customer Profiles.
3. (Optional) Select Add attribute mappings to map Chatbots attributes to Customer Profiles event properties.

Customer Profiles profile

Use the Customer Profiles profile element to retrieve or update the Customer Profiles profile of the end user.

In the chatbot editor, drag and drop the Customer Profiles profile element from Chatbot actions.

For full instructions, see Customer Profiles.

Select action

In the Select action field, choose one of the following:

• Get information: Retrieve data from the end user's Person profile.
• Create or update person profile: Save data collected during the conversation to the Person profile.

Contact information

In the Contact information attribute field, specify the attribute to use to identify the Person profile. You can use a standard channel-specific attribute stored in Customer Profiles, or a custom attribute in Chatbots. By default, this value is set to endUserDestination.

Map attributes

Select Add attribute mapping to map attributes in Chatbots to attributes in Customer Profiles.

Make sure that the attribute types are compatible. See the Attribute mapping table for supported combinations.

Customer Profiles tags

Use the Customer Profiles tags element to add, retrieve, or remove tags on the end user's Customer Profiles profile.

In the chatbot editor, drag and drop the Customer Profiles tags element from Chatbot actions.

Select action

In the Select action field, choose one of the following:

• Add or create tags: Add existing tags or create new ones.
• Get tags: Verify whether specified tags are present on the profile.
• Remove tags: Remove one or more tags from the profile.

Contact information

In the Contact information attribute field, enter the attribute that identifies the end user's profile.

Add existing or create new tags

Select the tags to add. You can select existing tags or type a new tag name to create one.

Remove tags

Select the tags to remove from the profile.

Get tags

Enter the tags to check for. The element saves the result (true/false) to a specified attribute, which you can use in a Conditions element.

Validate status of profile update

Add a Conditions element after the Customer Profiles tags element. Configure the element as follows:

• In the attribute field, choose the predefined attribute lastCustomerProfilesStatusCode.
• Set the operator to is.
• Specify the status — Success.
• Branch the chatbot flow as required.

Save user response

Use the Save user response element to capture a specific part of the end user's response and save it to an attribute.

In the chatbot editor, drag and drop the Save user response element from Chatbot actions.

How to use the element

Get and save end user's response

Use this element directly after an element that prompts the end user for input. The Save user response element captures the end user's reply and saves it to the specified attribute.

Save response from other elements

Use this element to save a specific value extracted from the end user's response, such as a detected entity or a parsed value.

Configure the element

Complete the following fields:

Skip question if attribute is already collected

Enable this option to skip the element if the attribute already has a value. This prevents the chatbot from asking for information that has already been collected.

Message

Enter the message to send to the end user requesting a response. You can use attributes to personalize the message. You can also add message variations — the end user receives one variation at random.

Save answer as

Choose the attribute in which to save the end user's response. You can choose an existing attribute or create a new one.

Enable custom validation

Enable this option to validate the end user's response before saving it. Specify the validation rule using a regular expression or by choosing a predefined format such as email, phone number, or URL.

Repeat message

Choose the number of times to repeat the message if the end user does not provide a valid response. Default is No repeat. Maximum is 3 times.

Fallback

Configure the fallback action to take if the end user does not provide a valid response after all repeats are exhausted. See the Fallback documentation.

Link preview (optional)

Enable link preview to show a preview of the URL when the chatbot sends a message that contains a link. Available for WhatsApp.

Timeout

Specify how long the chatbot waits for the end user to respond. If there is no response within the timeout period, the chatbot takes the fallback action. See the Timeout documentation.

To Agent

Use the To Agent element to transfer the conversation to a human agent in Inbox.

In the chatbot editor, drag and drop the To Agent element from Chatbot actions.

Complete the following fields:

• Queue (optional): Choose the agent queue to which to transfer the conversation.
• Message (optional): The message to send to the end user before transferring.

Tags

Add tags to the conversation before transferring to an agent. Tags help route the support request to the right queue in Inbox.

Create a tag

Tags must be created in Inbox before they can be used in Chatbots. For more information, see the Inbox documentation.

Add a tag to the conversation

In the Tags section of the To Agent element, select one or more tags to add to the conversation.

For more information about agent transfers, see Inbox.

To Dialog

Use the To Dialog element to redirect the chatbot flow to another dialog.

In the chatbot editor, drag and drop the To Dialog element from Chatbot actions.

In the Dialog field, choose the dialog to go to. You can choose an existing dialog or create a new one.

Share attributes

You can select which attributes to transfer when redirecting to another dialog. Use the Share attribute option to enable the attribute selector and choose the attributes to pass to the target dialog.

User response

Use the User response element to capture input from the end user and save it to an attribute. The chatbot waits for the end user to respond before proceeding.

In the chatbot editor, drag and drop the User response element from Chatbot receives.

Configure the element

Keywords

Use keywords to define the valid responses that the end user can provide.

Add keywords

Select Add keyword to add a keyword or phrase. When the end user sends a message that matches a keyword, the chatbot saves the response and proceeds.

Reorder keywords

Drag and drop keywords using the handle next to the keyword to change the order in which they are evaluated.

Natural language processing

Enable natural language processing (NLP) to allow the chatbot to understand responses that are similar in meaning to the configured keywords, rather than requiring exact matches.

Repeat message

Choose the number of times to repeat the message if the end user does not provide a valid response. Default is No repeat. Maximum is 3 times.

Fallback

Configure the fallback action to take if the end user does not provide a valid response after all repeats are exhausted. See the Fallback documentation.

Timeout

Specify how long the chatbot waits for the end user to respond. If there is no response within the timeout period, the chatbot takes the fallback action. Minimum is 15 seconds. Maximum is 14400 seconds (240 minutes). See the Timeout documentation.

Webhook

Use the Webhook element to send data to an external system when the chatbot reaches this element in the flow.

In the chatbot editor, drag and drop the Webhook element from Chatbot actions.

Configure the element

Complete the following fields:

• Webhook URL type: Choose whether the webhook URL is Static (the same URL is used every time) or Dynamic (the URL is constructed from an attribute at runtime).
• URL: The webhook URL. If you selected Dynamic, enter the attribute that contains the URL.
• Session ID body parameter name (optional): Enter the name of the body parameter to which the chatbot session ID is sent. Use this to correlate the webhook request with the chatbot session.
• Method: Choose the HTTP method. Supported methods are POST and PUT.
• Headers (optional): Add request headers.
• Body (optional): The request body. You can use attributes to personalize the body.

Webhook request codes

The webhook returns an HTTP status code in response to the request. Use a Conditions element after the Webhook element to branch the chatbot flow based on the response code.

Save the response code to an attribute using the Save response code to attribute option in the Response tab, then evaluate it in the Conditions element.

Common response codes:

• 2xx: The request was successful.
• 4xx: The request failed due to a client error.
• 5xx: The request failed due to a server error.

Throughput limits

The maximum throughput for each endpoint is 100 requests per second. The maximum throughput for each endpoint per IP address is 50 requests per second.

Example of using Webhook element

Use the Webhook element to notify an external CRM system when an end user completes a purchase through the chatbot.

1. At the end of the purchase flow, add a Webhook element.
2. Configure the URL to point to the CRM endpoint.
3. In the Body, include the relevant attributes such as the end user's contact information and the order details.
4. Add a Conditions element after the Webhook to check the response code and branch the flow accordingly.