Attributes

Attributes are data objects that can capture and store information.

The following are some ways in which you can use attributes:

• Capture information from end user messages. Example: phone numbers
• Personalize messages that you send to end users. Example: Instead of saying 'Hello', you can say 'Hello, {firstName}', where firstName is an attribute.
• Add context to conversations. Example: Instead of saying 'Are you contacting us regarding your order?', you can say 'Are you contacting us regarding order number {orderNumber}?', where orderNumber is an attribute.
• Capture payload from Answers elements, such as quick replies and reply buttons. For more information, refer to the How To section.
• Direct the chatbot flow based on the attribute value. Example: Use a Conditions element to direct the chatbot flow to the Booking dialog if the attribute value contains the word booking.
• Share information with other solutions. Example: Get the updated email address from the end user through Answers, save it in an attribute in Answers, pass this attribute to People, and update the email address in the Person profile in People.

How Attributes Work

The following example shows how to use an attribute to save the end user's response.

1. The Reply button element asks the end user to select an option.
2. The end user's response is saved in the product_name attribute in the Save user response element.
3. The Conditions element then uses this attribute value to branch the flow. The chatbot checks whether the value of the attribute meets specific criteria, and directs the flow accordingly.

You can simulate the conversation. The end user's response is Answers. This response is saved in the product_name attribute. In the Conditions element, the condition product_name contains Answers is met. So, the chatbot directs the flow to the Answers dialog.

Attribute Types

Standard Attributes

Standard attributes are the attributes that you can create and use with any type of chatbot. These attributes are present in the Attributes tab.

Fields in a standard attribute

Each attribute has the following fields:

• Name: Name of the attribute. For more information about the name, refer to the Guidelines and Validation of Attribute Names sections.

• Type: A standard attribute type. Refer to the Data Types for Standard Attributes documentation.

• Default value (Optional): Specify a default value for the attribute. Example: Specify a default phone number.

  The value that you can add to this field depends on the data type of the attribute. Example: For Text data type, you can add only text values.

• Scope: Can be one of the following:

  • Dialog: The attribute value is specific to a dialog. In other dialogs, the attribute value either has the default value or is blank.

    Example: The default value of the opt_in attribute is False. In a specific dialog, the opt_in attribute value changes to True. But in all other dialogs, the attribute still has the default value, False.

  • Chatbot: The attribute value is the same across all dialogs in the chatbot.

    Example: The default value of the opt_in attribute is False. In a specific dialog, the opt_in attribute value changes to True. In all other dialogs, the attribute now has the value, True.

• Available to agents: If you select this field, the attribute value is visible to an agent when the chat is transferred from the chatbot to an agent in Conversations. In Conversations, the attribute value is displayed in the context card of the conversation and the conversation history.

  If you also select Sensitive data, the attribute value is displayed as a hashed value in Answers and Conversations.

  To hide the attribute value from agents, deselect this field.

  Example: In Answers, for the accountId attribute, the Available to agents field is enabled. So, in Conversations, this attribute is displayed in the context card, as shown in the following image.

  

• Sensitive data: If you select this field, the attribute value is encrypted when it is stored in the database. It is displayed as a hashed value in Answers and Conversations. Example: The message is displayed as follows.
  When this field is disabled: Your account balance is 2123.32.
  When this field is enabled: Your account balance is ####.##.

  Use this field if the attribute contains sensitive data. This setting is especially useful when chats are transferred to live agents.

  This setting is applicable only for sensitive attributes that are present in outbound messages.

Data Types for Standard Attributes

Each standard attribute must be of one of the predefined data types.

Depending on the channel, data types for standard attributes can be inbound or outbound. Use an outbound data type if you want to use the attribute in a message to the end user. Use an inbound data type if you want to you use the attribute to capture responses from the end user or when you expect the end user to send you an attachment such as a file, image, or video.

To avoid errors, use the correct data type. Example: To save contact information from a contact card, use the Contacts data type.

Standard attributes can have one of the following data types.

• Text: The attribute value must be text. You can add sentences and paragraphs.
• Number: Numbers written in digits
• Phone number
• Boolean
• Date: Inbound attribute type. The date is stored in the format, YYYY-MM-DD. If end users send a date in a different format, it is treated as an invalid input.
• Send location: Location from Google Maps. Shared in the form of either a pin or latitude-longitude.
• URL
• Email
• List
• JSON
• XML
• XML list
• Audio
• Contacts
• Document
• Image
• Receive location: Location from Google Maps. Shared in the form of either a pin or latitude-longitude. For information about how to share the location in the simulator, see the Simulation documentation.
• Video
• Message: Inbound attribute type. Use this attribute type to receive files when you do not know the file type that the end user may send. Example: The end user may send an image or a document. Refer to this example to understand how to use an attribute of type Message to receive a file and to use the Code element to identify the file type.
• WhatsApp order response (WhatsApp only): Contains the order details when you use the Single Product or Multi-product elements.

The following table shows the inbound messages supported by each channel.

	Message	Video	Location	Image	Document	Contact	Audio
Apple Messages for Business	✓
Instagram Messaging	✓
LINE	✓
Live Chat	✓
Messenger	✓
RCS	✓	✓	✓	✓	✓		✓
SMS	✓
Telegram	✓	✓		✓	✓		✓
Viber Business Messages	✓
Viber Bots	✓
WhatsApp	✓	✓	✓	✓	✓	✓	✓

For information about creating and using standard attributes, refer to the How to section.

Predefined Attributes

Predefined attributes are data objects that contain basic information about end users. They are used for background processes in Answers.

You cannot create a predefined attribute. These attributes are not listed in the Attributes tab.

Predefined attributes are available in all chatbots. Use these attributes in Answers elements.

• The API element does not support predefined attributes. To use the value of a predefined attribute in an API element, refer to the How to section.
• Some elements, such as the Conditions element, do not support channel-specific predefined attributes. To use channel-specific predefined attributes in these elements, refer to the How to section.

Answers has the following predefined attributes.

Predefined attribute	Description
All channels
authenticated	A Boolean attribute that is set to either True or False depending on the end user's authentication status. Authentication can be configured to expire. So, even if this attribute is set to True, it can change to False after the authentication expires.
callbackdata	Stores the payload or metadata from the most recent message received from the end user. Use this information to personalize end user journeys in the chatbot. To receive the payload, you need to define the callbackdata parameter in the API call when sending messages to end users. If you send multiple parameters within the payload, use the Code element to extract the data. The callbackdata parameter is available in all Infobip APIs and for all channels that support sending outbound messages.
chatbotSender	A chatbot can have multiple senders. The end user can contact the chatbot on one of these senders. The chatbotSender attribute stores the specific sender on which the end user contacts the chatbot.
conversationId	The ID that is used to identify a conversation that is transferred from a chatbot in Answers to an agent either in Conversations or an external contact center solution.
endUserDestination	Stores the identification used by the channel for an end user. Each channel identifies the end user differently. Example: The Messenger channel uses the Facebook ID and Live Chat channel uses the browser's session ID.
lastpeoplestatuscode	Returns whether the chatbot was able to successfully update or retrieve information from a Person profile in People. Example: The chatbot saves an event to People or gets the email address from People. Attribute values are as follows: SUCCESS: Update or retrieve information succeeded. FAIL: Update or retrieve information failed. VALIDATION_ERROR: Validation check failed when processing the request. Example: Formatting of the person profile is incorrect. You can use this attribute if you use any of the People elements in the chatbot. Example: People profile element. Use the Conditions element to take relevant action based on the attribute value.
lastReceivedMessage	Captures the last inbound message received by the chatbot. Use this attribute if you expect your end users to start the conversation with a predefined message. Compare the attribute value against a keyword and branch the dialog accordingly. Example: You offer a discount and you expect the end user's message to contain the promotional code. You can also pass this attribute value to People and use it in other Infobip solutions, such as Broadcast. The attribute value is saved in JSON format. Example: If the last message sent by the end user is "Thanks for the update.", the attribute value is {"type":"TEXT","content":"Thanks for the update"} The attribute is applicable for all MO attribute values received, except text messages. For text messages, use lastReceivedTextMessage.
lastReceivedTextMessage	Captures the last inbound text message received by the chatbot. Use this attribute if you expect your end users to start the conversation with a predefined message. Compare the attribute value against a keyword and branch the dialog accordingly. Example: You offer a discount and you expect the end user's message to contain the promotional code. You can also pass this attribute value to People and use it in other Infobip solutions, such as Broadcast. The attribute value is in text format. Example: If the last message sent by the end user is "Thanks for the update.", the attribute value is the content of the message, that is, "Thanks for the update".
sessionId	A unique identifier for the end user. Example: E32DCDD3056F21C9FBA26BBD84FC079F5FFD
uniqueSessionId	A unique identifier for the session. If an end user initiates multiple sessions, the uniqueSessionId is different for each session. Example: 6d554323-2e44-4c9d-8ff0-5ee62931165e Use this identifier to find the session in the Answers analytics.
Apple Messages for Business When an end user initiates a conversation with your chatbot, the following parameters are included in the information that is sent to the chatbot.
appleBusinessChatIntent	The purpose of the chat. Example: product query. This information is obtained from your Apple business account.
appleBusinessChatGroup	The department or individual that is assigned the task of managing the end user's question. This information is obtained from your Apple business account.
appleBusinessChatDeviceAgent	The end user's device. Example: Android
appleBusinessChatLocale	The locale settings of the end user's device. Example: en-uk indicates that the language is English, and the location is the United Kingdom.
appleBusinessChatReferenceId	The reference ID that you define in your Business update messages. Example: Order ID. When an end user contacts your chatbot in response to your Business update message, the reference ID is included in the end user's message.
appleBusinessChatUserPhoneNumber	The phone number of the end user. The chatbot gets this information from the end user's message.
Live Chat
lcAuthenticationIdentity	Stores the authentication identity of the end user. Depending on how the end user is authenticated, this attribute can contain the end user's email address, phone number, external ID, or push registration ID. For more information about authentication for Live Chat, refer to the Live Chat documentation.
RCS, SMS, Viber
phoneNumber	Captures the phone number from the end user's message. The attribute is of the type Number and scope Chatbot. This attribute is applicable only for channels that use MSISDN as the destination.
WhatsApp
displayName	The display name that is set by end users to identify themselves in the app for a channel. In WhatsApp, this is the name that is displayed to people who have not saved the sender's phone number.
phoneNumber	Captures the phone number from the end user's message. The attribute is of the type Number and scope Chatbot. This attribute is applicable only for channels that use MSISDN as the destination.
whatsAppMoReferralSourceId	A Text attribute that stores the unique ID of the Instagram ad, Facebook ad, or Facebook post, which directed the end user to the chatbot. Example: 615533673545722. If this attribute is empty, it indicates that the end user did not contact the chatbot through one of these entry points, but used a different entry point. This attribute is one of the parameters of WhatsApp referral. Use this attribute, along with the whatsAppMoReferralSourceType and whatsAppMoReferralSourceUrl attributes, for routing, validation, and personalization. For more information, refer to the Get WhatsApp Referral Information section.
whatsAppMoReferralSourceType	A Text attribute that indicates the entry point to the chatbot. Valid values are as follows: POST: The entry point is a Facebook post. AD: The entry point is either an Instagram ad or a Facebook ad. UNKNOWN: The entry point is not an Instagram post, Facebook post, or Facebook ad. This attribute is one of the parameters of WhatsApp referral. Use this attribute, along with the whatsAppMoReferralSourceId and whatsAppMoReferralSourceUrl attributes, for routing, validation, and personalization. For more information, refer to the Get WhatsApp Referral Information section.
whatsAppMoReferralSourceUrl	A Text attribute that stores the URL of the Instagram post, Facebook post, or Facebook ad, which directed the end user to the chatbot. Example: https://fb.me/7OdfE45gk (opens in a new tab). If this attribute is empty, it indicates that the end user did not contact the chatbot through one of these entry points, but used a different entry point. This attribute is one of the parameters of WhatsApp referral. Use this attribute, along with the whatsAppMoReferralSourceId and whatsAppMoReferralSourceType attributes, for routing, validation, and personalization. For more information, refer to the Get WhatsApp Referral Information section.
whatsAppMoReferralCtwaClickId	A Text attribute that stores the unique identifier that is generated when an end user clicks an Instagram post, Facebook post, or Facebook ad, which contains WhatsApp call-to-action, and starts a conversation with the chatbot. If this attribute is empty, it indicates that the end user did not contact the chatbot through one of these entry points, but used a different entry point.The ID is unique for each click. Example: If an end user clicks the ad 2 times, 2 IDs are generated. Use this information to identify the number of unique clicks for the post or ad. For more information, refer to the Get WhatsApp Referral Information section.
whatsAppIdentityAcknowledged	Indicates whether the end user's identity is correct. The value can be True or False. This attribute is used as part of the WhatsApp identity change feature.
whatsAppIdentityHash	Contains the unique code of the identity check for a specific end user. This attribute is used as part of the WhatsApp identity change feature.
whatsAppIdentityCreated	Provides the timestamp of when the identity change data was created. This attribute is used as part of the WhatsApp identity change feature.

Named Entity Recognition Attributes

Named entity recognition (opens in a new tab) (NER) is a part of natural language processing (NLP). The goal of NER is to recognize and categorize information (entities) in the end user's message.

For more information, refer to the AI section.

Attributes Tab

For information about the Custom data types and NER attributes tabs, go to the AI section.

To view a list of standard attributes, go to the Attributes tab > Attributes. For information about the fields for a standard attribute refer to the standard attributes documentation.

Validation for Attributes

This section provides details of how attribute names and values are validated.

Validation of Attribute Names

The following validation is applied to attribute names:

• Attribute names can contain alphabets, numbers, underscores, and circumflexes.
• Attribute names cannot contain spaces, dashes, or other special characters. Example: customer number, customer-number, customer's number
• Attribute names cannot start with a numeric value. Instead, use an alphabet or an underscore. Example: Instead of '1daypromo', use  '_1daypromo'.
• Use an underscore if the attribute name contains multiple words. Example: Instead of 'customer number', use 'customer_number'.

Validation of Attribute Values

When attributes are used in a Conditions element, they are validated as shown in the table. For information about validation of NER attributes, refer to the AI section.

Attribute type	Condition	Validation for the attribute value
Text	is | is not | contains | starts with | ends with | is null | is not null	Can contain letters, numbers, or space
Phone Number	is | is not | contains | starts with | ends with | is null | is not null	Can contain only numbers
Boolean	is | is not | is null | is not null	True, False
Date	is equal to | is not equal to | is before | is before or equal to | is after | is after or equal to | is null | is not null	YYYY-MM-DD, only numbers
Location	is equal to | is not equal to | is null | is not null
URL	is equal to | is not equal to | is null | is not null	Validated using URL validator
Email	is | is not | contains | starts with | ends with | is null | is not null	Validated using email address validator
Inbound attribute type	Condition	Validation for the attribute value
MO Audio	is null | is not null	Accepts audio files. Valid file format depends on the channel
MO Contacts	is null | is not null	Accepts address, name, birthday, phone, organization, and URL
MO Document	is null | is not null	Accepts documents. Valid file format depends on the channel
MO Image	is null | is not null	Accepts image files. Valid file format depends on the channel
MO Location	is null | is not null	Accepts latitude and longitude of a location
MO Video	is null | is not null	Accepts video files. Valid file format depends on the channel

Guidelines and Best Practices

• You can create attributes either before or during the configuration of dialogs.
• Attribute names cannot contain spaces. Instead, use a connector, such as an underscore or a hyphen.
• Attribute names must start with a letter or underscore.
• You can create an unlimited number of attributes.

How to

Create an Attribute

To create a NER attribute, refer to the AI section.

To create a standard attribute, do the following:

1. On the Infobip web interface (opens in a new tab), go to Answers > Chatbots and navigate to your chatbot.

2. Go to the Attributes tab > Attributes section.

3. Click Add attribute.

4. In the Create new attribute screen, configure the following fields. For information about these fields, refer to the standard attributes documentation.

   • Name: Enter a name for the attribute. Refer to the Guidelines and Validation of Attribute Names sections.
   • Type: Choose a standard data type. If you want to use the attribute in a Conditions element, refer to the Validation of Attribute Values section to make sure that you choose the correct type.
   • Default value (Optional): Specify a default value for the attribute.
   • Scope (Optional): Choose whether the attribute is Dialog or Chatbot.
   • Available to agents (Optional): Deselect this field to hide attribute values from agents when the chat is transferred from the chatbot to an agent in Conversations.
   • Sensitive data (Optional): Select this field if you want to display attribute values as hashed values in Answers and Conversations.

5. Select Save.

Edit an Attribute

Do one of the following:

• Click the attribute name to edit the fields.
• Click the menu against an attribute and choose Edit.

Delete an Attribute

Click the menu against an attribute and choose Delete.

You need to confirm the action.

Hide attribute values from agents

Deselect the Available to agents field so that agents cannot view these values in the context card and conversation history in Conversations.

Display attribute values as hashed values

Select the Sensitive data field to display the attribute value as a hashed value in Answers and Conversations.

Use a predefined attribute in an API element

The API element does not support predefined attributes. Follow this workaround to use the value of a predefined attribute in an API element,

1. Create a new attribute.
2. In the Code element, save the value of the predefined attribute in the new attribute.
3. Pass the new attribute to the API element.

Use channel-specific predefined attributes in chatbot elements

You cannot use channel-specific predefined attributes in some of the Answers elements, such as the Conditions element. To use these predefined attributes in the elements, follow these steps.

1. Create a standard attribute for each channel-specific predefined attribute that you want to use in the chatbot. Example: To use the whatsAppIdentityAcknowledged attribute, create a standard attribute IdAcknowledgeStatus.
2. In the dialog, add the Code element.
3. In the Code element, set the value of the predefined attribute to a standard attribute. Example: var x = attributeApi.get('whatsAppIdentityAcknowledged');attributeApi.set('IdAcknowledgeStatus', x)
4. Use the standard attribute in the Conditions element.

Get WhatsApp Referral Information

Overview

Use the WhatsApp call-to-action feature in your Instagram ads, Facebook ads, and Facebook posts. When an end user clicks these ads or posts, they can contact your chatbot through WhatsApp.

Then, in your chatbot, you can use predefined attributes to receive and store information from these ads or posts.

• Use the whatsAppMoReferralSourceType predefined attribute to identify whether the end user contacted the chatbot through an Instagram ad, Facebook ad, Facebook post, or a different entry point.
• Use the whatsAppMoReferralSourceId predefined attribute to obtain the unique ID of the ad or post.
• Use the whatsAppMoReferralSourceUrl predefined attribute to obtain the URL of the ad or post.
• Use the whatsAppMoReferralCtwaClickId predefined attribute to obtain the unique click ID.

For more information about these attributes, refer to the Predefined attributes section.

You can then use the information from these attributes as shown in the following examples:

• Based on the entry point, you can route the end user to the relevant dialog.
• If the entry point is an Instagram ad, Facebook ad, or Facebook post, you can identify the intent of the end user from the ad or post. You do not need to ask the end user the purpose for contacting your chatbot.
• Use the People profile element to save the attributes values in People.
• Use metrics to obtain analytics. Example: You can identify the number of end users who contacted your chatbot from a specific Facebook ad.
• Identify the number of clicks for the ad or post.

Configure the chatbot

The following example shows how to configure and branch the chatbot based on the WhatsApp referral information.

You have the following entry points to your WhatsApp chatbot:

• A QR code on your website
• A Facebook post for mobile phones with the page post ID 123
• A Facebook ad for laptops with the ad ID 456

In the chatbot, you want to route the conversation based on the ID of the entry point, that is, based on the value of the whatsAppMoReferralSourceId attribute.

Configure the chatbot as follows:

1. Create standard attributes to save the values of the WhatsApp referral attributes (predefined attributes). Set the Scope as Chatbot and the Type as Text. Example:

   WhatsApp referral attribute (predefined attribute)	Example of standard attribute
   whatsAppMoReferralSourceId	SourceID
   whatsAppMoReferralSourceType	SourceType
   whatsAppMoReferralSourceUrl	SourceUrl
   whatsAppMoReferralCtwaClickId	ClickId

2. In the dialog, add the Code element.

3. In the Code element, set the value of the predefined attributes to the standard attributes. Example: var a=attributeApi.get('whatsAppMoReferralSourceId');attributeApi.set('SourceID', a);var b=attributeApi.get('whatsAppMoReferralSourceType');attributeApi.set('SourceType', b);var c=attributeApi.get('whatsAppMoReferralSourceUrl');attributeApi.set('SourceUrl', c);var d=attributeApi.get('whatsAppMoReferralCtwaClickId');attributeApi.set('ClickId', d);

4. Use the Conditions element to route the conversation based on the entry point.

   • If the end user contacts your chatbot through the Facebook post for mobile phones, route the end user to the Mobile Phones dialog.
   • If the end user contacts your chatbot through the Facebook ad for laptops, route the end user to the Laptops dialog.
   • If the end user uses a different entry point, the chatbot does not know the intent of the end user. So, route the end user to the main menu where they can select an option to continue the conversation.
   

5. In the Mobile Phones dialog, pass the attribute value to People.

   

How it works

An end user clicks the Send Message WhatsApp call-to-action button in the Facebook post. The WhatsApp app opens to start a conversation with your chatbot. A predefined message, which refers to the Facebook post, is added automatically in the message box. The end user sends this predefined message to your chatbot.

The chatbot receives this message and the WhatsApp referral information. The WhatsApp referral information is saved in the predefined attributes.

• whatsAppMoReferralSourceId: 123
• whatsAppMoReferralSourceType: POST
• whatsAppMoReferralSourceUrl: https://fb.me/7OdfE45gk (opens in a new tab)
• whatsAppMoReferralCtwaClickId: 7890

The chatbot is configured to route the conversation based on the entry point. The end user has clicked the Facebook post. So, the chatbot routes the end user to the Mobile Phones dialog without going through the main menu. The end user does not lose the context of the conversation because they can go directly from the post about mobile phones to a conversation about mobile phones in your chatbot.

The chatbot passes the attribute value to People.

Analytics

If you have advanced analytics (Early access), you can use the following WhatsApp referral metrics in a custom dashboard.

• whatsAppMoReferralSourceId
• whatsAppMoReferralSourceType
• whatsAppMoReferralSourceUrl