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 capture the end user's response and direct the flow based on the response.
In the Attribute element, the product_name attribute captures and saves the end user's message. In the Conditions element, the chatbot checks whether the value of the attribute meets specific criteria, and directs the flow accordingly.
The end user's message is 'I want to know about the features in Answers.' The product_name attribute captures and saves this message. 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.
- Scope: Can be one of the following:
- Local: The attribute is specific to a dialog.
- Global: The attribute can be used across multiple dialogs within the chatbot.
- 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 feature is applicable only for outbound attributes.
Data Types for Standard Attributes
Each standard attribute must be of a predefined data type. To avoid errors, use the correct data type. Example: To save contact information from a contact card, use the Contacts data type.
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.
Standard attributes can have one of the following data types.
- Text
- 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
- 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.
Note
You cannot use custom attribute types as the data type for standard attributes.
The following table shows the inbound messages supported by each channel.
|
|
Message |
Video |
Location |
Image |
Document |
Contact |
Audio |
|
Apple Messages for Business |
✓ |
|
|
|
|
|
|
|
Google's Business Messages |
✓ |
|
|
|
|
|
|
|
Instagram Messaging |
✓ |
|
|
|
|
|
|
|
LINE |
✓ |
|
|
|
|
|
|
|
Live Chat |
✓ |
|
|
|
|
|
|
|
Messenger |
✓ |
|
|
|
|
|
|
|
RCS |
✓ |
✓ |
✓ |
✓ |
✓ |
|
✓ |
|
SMS |
✓ |
|
|
|
|
|
|
|
Telegram |
✓ |
✓ |
|
✓ |
✓ |
|
✓ |
|
Viber Business Messages |
✓ |
|
|
|
|
|
|
|
Viber Bots |
✓ |
|
|
|
|
|
|
|
|
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
✓ |
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. |
| 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:
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. It is not dependent on the end user. So, even if the same end user initiates the session, the uniqueSessionId is different for each of their sessions. 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. |
| Google's Business Messages | |
| displayName | The display name that is set by end users to identify themselves in the app for a channel. |
| gbmEntryLocation | Stores the location of the end user when they initiate the conversation. For each session, Answers obtains this information from Google. Use this information to guide end users with location-related queries. Example: The chatbot can use the location information to identify the service center that is nearest to the end user. |
| gbmNearPlaceID | Identifies and stores the nearest location based on the location in the end user's inquiry. Use this attribute to set up specific dialog routing depending on the location. Example: If the end user wants the location of a service center in Zagreb, the attribute saves the location of a service center that is nearest to Zagreb. |
| 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 Global. This attribute is applicable only for channels that use MSISDN as the destination. |
| 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 Global. |
| whatsAppMoReferralSourceId |
A Text attribute that stores the unique ID of the Facebook ad or 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 a Facebook ad or post, but used a different entry point. 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:
For more information, refer to the Get WhatsApp Referral Information section. |
| whatsAppMoReferralSourceUrl |
A Text attribute that stores the URL of the Facebook ad or post, which directed the end user to the chatbot. Example: https://fb.me/7OdfE45gk. If this attribute is empty, it indicates that the end user did not contact the chatbot through a Facebook ad or post, but used a different entry point. 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 a Facebook ad or post that 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 a Facebook ad or post, 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 Facebook ad or post. 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 (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 Attribute 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 |
|
|
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:
- On the Infobip web interface, go to Answers > Chatbots and navigate to your chatbot.
- Go to the Attributes tab > Attributes section.
- Click Add attribute.
- 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.
- Scope: Choose whether the attribute is Local or Global.
- Available to agents: Deselect this field to hide attribute values from agents when the chat is transferred from the chatbot to an agent in Conversations.
- Sensitive data: Select this field if you want to display attribute values as hashed values in Answers and Conversations.
- Use the check mark ✓ to save the attribute or the x mark to remove the attribute.
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,
- Create a new attribute.
- In the Code element, save the value of the predefined attribute in the new attribute.
- 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.
- 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.
- In the dialog, add the Code element.
- 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) - Use the standard attribute in the Conditions element.
Get WhatsApp Referral Information
Overview
In your Facebook ads and posts, you can use the WhatsApp call-to-action feature. When an end user clicks the ad or post, 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 a Facebook ad, a Facebook post, or a different entry point.
- Use the whatsAppMoReferralSourceId predefined attribute to obtain the unique ID of the Facebook ad or post.
- Use the whatsAppMoReferralSourceUrl predefined attribute to obtain the URL of the Facebook 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 a Facebook ad or 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 Facebook 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:
Important
You must save the values of the WhatsApp referral attributes in standard attributes before the end user sends replies to the first message from the chatbot.
- Create standard attributes to save the values of the WhatsApp referral attributes (predefined attributes). Set the Scope as Global and the Type as Text.
Example:WhatsApp referral attribute (predefined attribute) Example of standard attribute whatsAppMoReferralSourceId SourceID whatsAppMoReferralSourceType SourceType whatsAppMoReferralSourceUrl SourceUrl whatsAppMoReferralCtwaClickId ClickId - In the dialog, add the Code element.
- 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);
- 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.
- 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
- 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
