How to work with user data and metadata
The ability to attach and retain custom user data can be one of the most powerful features of the Mindful ecosystem. Several methods of collecting and passing user data (or metadata) are available, such as collecting input via DTMF from customers and speaking it to agents, or receiving metadata via SIP headers and passing it along to a SIP endpoint in your contact center.
Overview
This FAQ guide covers the following topics to help you become familiar with user data in Mindful.
- Collect user data via pre-defined User Data Sets
- Collect information from customers via Metadata items
- Pass parameters in API requests
- Preserve call context automatically via Datastore
Collect User Data via Pre-Defined User Data Sets
User Data Sets allow you to define a set of key value pairs (KVPs) that can be sent by a Scheduler widget to the Callback system.
A User Data Set allows Mindful to receive data, but you must still configure a Metadata Item for your Call Target in order to pass the data to the contact center. For more information on configuring Metadata items, see the Metadata section of the Call Targets page article.
Quick Access: Scheduler > User Data Sets
- Click Add New User Data Set to open the Create Scheduler User Data page.
Name (required): Enter a name to identify the User Data Set.
Description: Enter a description to define the purpose of the User Data Set.
Click Add New Key to add the first key representing a user data KVP.
In the window that appears, enter a Key Name for the KVP. This name must precisely match the KVP that will be received by the widget.
Enter a value in the Default Value field, if applicable. This value will be assigned to the KVP if no value is received.
If you wish to replace any value that is submitted for this KVP with the specified default value, select the Replace Value from widget with Default Value checkbox.
Click Save to save the User Data Key, then repeat steps 4 - 6 for all remaining keys you wish to define for the set.
After creating a User Data Set, use the following steps to apply it to a Widget.
Quick Access: Scheduler > Widgets
- Click the Edit icon in the row corresponding to a particular widget.
- Use the User Data Set dropdown menu to select a set to apply.
- Save your changes.
Collect Information from Customers via Metadata Items
Quick access:
- Callback > Call Targets > Metadata tab
- Callback > Global Settings > Metadata tab
Metadata Items configured on the Global Settings page will apply to all calls made throughout the Organization. These items will apply in addition to any Metadata Items configured for individual Call Targets.
On the Call Target and Global Settings pages, the Add metadata button adds new rows with the following configuration options for a new metadata item.
- Name: This field should contain a descriptive name of your choice for the metadata item.
A maximum of 1,024 characters can be used.
Present Metadata to: Select Agent, Customer, or both. When Agent is selected, agents will hear the audio recording for Audio items, or a playback of the digits entered for DTMF items. When Customer is selected, the customer will hear these items played back when they receive the callback.
- Type: The dropdown menu allows you to choose how the metadata information will be collected.
Select Audio to collect information from customers via voice. The recorded audio will be played back to agents prior to connecting the call.
Select DTMF to collect information via DTMF pulses. The collected digits will be spoken to agents via voice prompts before the call is connected.
Select SIP Header to collect data via SIP user-to-user, diversion header, or custom X-header information from a web widget (see the Dynamic DNIS Mapping section of Contact Center Settings for more information). The custom headers will be generated and passed when the outbound call is placed. Custom SIP and X headers require SIP connectivity to the Callback system.
Only one Metadata Item can be presented to customers. However, any or all items (other than SIP headers) can be played to agents.
If you play an item back to customers, the Customer Callback Greeting With Metadata prompt will play when they receive the callback. If you are playing back anything other than the customer's name, make sure to update this greeting prompt to be relevant to the information you are playing back. You can find this prompt in the Metadata Prompts section within the General Prompts tab when editing a Media Set.
To edit an existing metadata item, update any of the fields in the associated row, then save and publish the changes. To remove an existing item, click the Remove button in the appropriate row.
Configuring Audio or DTMF Items
The remaining fields depend upon the type of Metadata Item selected. The following additional options appear when Type is set to Audio or DTMF.
The Max Recording Length field (called Max Length for DTMF) sets the maximum number of seconds of audio input that can be gathered for an item, or the maximum number of pulses for DTMF.
- The Terminator value represents the special digit or character, such as #, that will end the interaction.
We recommend using a single character, but a maximum of 1,024 characters can be used.
The Prompt dropdown menu allows you to select a default pair of voice prompts or use custom audio files instead. Two voice prompts are used for each Metadata item: one to gather input from the customer, and another to provide that input to the agent. Audio files do not apply to SIP Metadata items.
Example
In the following example, we have created a Metadata item named "vehicle mileage" which collects DTMF input from customers and only accepts up to seven digits. This example uses a custom voice prompt, which could say something like "please enter the current mileage of your vehicle."
Since this is a DTMF Metadata Item, the agent will hear another custom voice prompt, something like "the customer's current mileage is..." and will then hear the digits played back via standard number-only audio files. In this example, we've chosen not to play this item back to the customer
Configuring SIP Header Items
The following options appear when Type is set to SIP Header.
The Default Value field sets a default value to be assigned to the Metadata Item if no values are specified in SIP headers sent from your contact center to Mindful Callback.
You can use the Configure separate Agent and Customer leg default values checkbox to separate the Default Value field into two fields. The first will set a default value for calls sent to the contact center, and the second will set a default for calls sent to customers. You can use this approach when you need to send Metadata values to your contact center that do not need to be present when dialing customers.
Passing UUI Data in SIP Headers
It is possible to automatically attach UUI data in the Refer-To header of SIP REFER messages using a SIP Metadata Item:
First, you must enable Use SIP REFER for Choose Holds on the same Call Target (SIP section). If your telephony environment cannot accept SIP Re-INVITEs, then you can enable Use SIP REFER for Choose Holds to instruct Callback to use REFER when passing a choose-hold call back to the contact center.
Next, you'll need to configure a Metadata Item specifically named "UUI" or "User-to-user".
Lastly, enable Append UUI to Refer-To Header on the same Call Target (SIP section) to pass UUI data in Refer-To headers.
Metadata Persistence
The Persist Forever checkbox (shown for Audio or DTMF items) allows you to mark a specific metadata item to store its data after a call is finalized. When the checkbox is deselected, the data is cleaned up after the call is completed.
When configuring an Audio or DTMF Metadata Item, you can select Custom Prompt from the Prompt dropdown menu to use your own audio file to prompt customers for their input and provide that input to agents.
If you are configuring a new item and you would like to upload new custom audio for that item, remember to save your changes on the Metadata tab before switching to the Media Sets page to upload the file.
Quick access: Callback > Media Sets > Your Media Set > General Prompts tab & Speech Prompts tab
From your Media Set, within the General Prompts tab, locate the Custom Metadata Media section.
- Click the row associated with the customer prompt that you would like to replace.
The customer prompt will be named customer_<metadata item name>. For example, if the Metadata Item is named "SecretQuestion", the customer prompt will be named "Customer_SecretQuestion". The row will expand to present additional fields.
Repeat the previous step for the associated agent prompt. The agent prompt will be named agent_<metadata item name>.
Upload your custom audio file by following the on-screen instructions.
Click the Play button to preview your audio file after the upload is complete.
Repeat this process in the Speech Prompts tab if you utilize the Customer Speech Recognition feature.
Save and publish your changes.
Custom metadata media prompts only become available to edit once Custom Prompt has been specified in the Prompt dropdown menu for a Metadata Item.
The Enhanced Reporting checkbox (shown for SIP Header items) will include collected metadata in responses from the Historical Data API endpoints, contained in an object called metadata.
If you would like to remove historical metadata, first deselect the Persist forever checkbox, then click Delete Historical Metadata.
Historical metadata can only be removed on the Call Target page. This option is not available on the Global Settings page because the data is associated with individual Call Targets.
Using Custom Audio Files
When configuring an Audio or DTMF Metadata Item, you can select Custom Prompt from the Prompt dropdown menu to use your own audio file to prompt customers for their input and provide that input to agents.
If you are configuring a new item and you would like to upload new custom audio for that item, remember to save your changes on the Metadata tab before switching to the Media Sets page to upload the file.
Quick access: Callback > Media Sets > Your Media Set > General Prompts tab & Speech Prompts tab
From your Media Set, within the General Prompts tab, locate the Custom Metadata Media section.
- Click the row associated with the customer prompt that you would like to replace.
The customer prompt will be named customer_<metadata item name>. For example, if the Metadata Item is named "SecretQuestion", the customer prompt will be named "Customer_SecretQuestion". The row will expand to present additional fields.
Repeat the previous step for the associated agent prompt. The agent prompt will be named agent_<metadata item name>.
Upload your custom audio file by following the on-screen instructions.
Click the Play button to preview your audio file after the upload is complete.
Repeat this process in the Speech Prompts tab if you utilize the Customer Speech Recognition feature.
Save and publish your changes.
Custom metadata media prompts only become available to edit once Custom Prompt has been specified in the Prompt dropdown menu for a Metadata Item.
Pass Parameters in API Requests
Attach JSON-Formatted User Data
When invoking the Scheduler API directly from your own application, you can pass the user_data parameter with your callback request to attach json-formatted custom user data. The Callback system will keep this data attached to the callback as it is passed to your contact center.
Attach the Channel Parameter for Reporting
Similar to user data, you can pass the channel parameter along with callback requests to attach an identifier for reporting purposes. For example, you might pass "channel": web when invoking the API from your website, or "channel": mobile when invoking the API from your mobile application. You can then filter this information by using exported Call Detail reports outside of the Callback system.
Learn More About the API
For more information on API parameters and the API Endpoints modal window in Callback, see our API documentation.
Preserve Call Context Automatically via Datastore
Mindful Datastore is integrated into the Mindful platform, and it provides the ability to maintain call context at critical points in an interaction. Mindful Datastore acts as an independent repository for callback user data that can be accessed by other Mindful applications or your own ACD scripts. The Mindful Datastore integration covers one use case at this time:
Use Case: Preserve Context for All Callbacks
To create and update Datastore records when a callback is registered, rescheduled, or retried, you will need to configure a few settings on the Call Target page.
Quick access: Callback > Call Targets > General tab > General
On the Call Target page, when Enable Mindful Datastore Integration is selected, the Data Set Template dropdown menu becomes available. The Data Set Template dropdown menu allows you to select one of the Data Set Templates configured on the Datastore page. Any updates to callback data for the associated Call Target will use the selected Data Set Template.
