How to add or edit metadata items

Metadata Items can be added in Global Settings or for individual Call Targets. Follow the instructions in this guide to learn how to add, edit, and manage Metadata Items for your Call Targets or your entire Organization.

Quick access:

  • Callback > Call Targets > Your Call Target > Metadata tab
  • Callback > Global Settings > Metadata tab

On the Metadata tab of the Call Target and Global Settings pages, the Add metadata item button adds new rows to the user interface with the following configuration options for a new metadata item.

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 Delete icon in the appropriate row.screenshot of the metadata tab

  • The Name field should contain a descriptive name of your choice for the metadata item.

    • A maximum of 1,024 characters can be used.

  • The Type selector 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 Dynamic DNIS Mapping in the Contact Center Settings article 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.

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 Present Metadata to field allows you to select whether Metadata Items (collected via voice or DTMF) will be played back to the agent, the customer, or both.
  • The Max Recording Length field 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 audio files.

Since the Present Metadata to (Customer) checkbox is selected, this item will be played back to the customer, as well.example of a metadata item configured to be presented to both the customer and agent

Persist Forever

The Persist Forever setting, when selected, instructs the Mindful Platform to maintain all records of metadata items received via voice of DTMF from customers. When the checkbox is deselected, the data is cleaned up after the call is completed. When you no longer wish to store historical data for a Metadata Item, click the Delete Historical Metadata button for a particular Metadata Item.

Note:
  • 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.
  • Persist Forever is only available for Audio and DTMF Metadata Items. You will not see this checkbox for SIP Header items.
  • Deleting historical metadata cannot be undone. Take caution to ensure that you have selected the correct metadata item and that you truly wish to delete its historical data before proceeding

Configuring SIP Header Items

The following options appear when Type is set to SIP Header.

  • The Default Value - Both Legs 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 (Agent Leg and Customer Leg). 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.
Important: When using SIP Header Metadata Items with User Data Sets, the Metadata Item Name must precisely match the KVP that will be received by the widget and the Key Name (Telephony Key) of the User Data Set. This requires casing to be consistent.

example metadata item with different default values

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.

Enhanced Reporting

For SIP Header Metadata Items, the Enhanced Reporting checkbox controls whether these items will be included in the payload of the Historical Reporting API. When included, Metadata Items received during callback registration will display as the final item in the payload returned by the API (an object named metadata). To learn more, see the API documentation.

Note: 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.
Important: If you are configuring a new metadata 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
Use the following steps to upload a custom audio file for a Metadata item.

Quick access: Callback > Media Sets > Your Media Set

  1. In the General Prompts tab, locate the Custom Metadata Media section.
  2. Click the row associated with the customer prompt that you would like to replace. The customer prompt will be named your_<metadata item name>. The row will expand to present additional fields.
  3. Repeat the previous step for the associated agent prompt. The agent prompt will be named agent_<metadata item name>.
  4. Upload your custom audio file by following the on-screen instructions.
  5. Click the Play button to preview your audio file after the upload is complete.
  6. Save and publish your changes.
Note: Custom metadata media prompts only become available to edit once Custom Prompt has been specified in the Prompt dropdown menu for a Metadata item.