Using Messaging Metadata with a Zendesk bot to send page data to a ticket

Messaging Metadata refers to information programmatically collected during an interaction between an end user and a Zendesk bot and then transferred to a ticket with the rest of the conversation. This is done by using custom ticket fields in the ticket to store the data and then using the metadata API with a Zendesk bot to transfer the data to the ticket fields.

In this tutorial you'll create a very basic travel itinerary page and use a Zendesk bot and Messaging Metadata to transfer page data to a Zendesk ticket. To do this, you'll create three custom ticket fields for the tickets. One ticket field will store data contained in the travel page but not displayed to the end user. The second ticket field will store data contained in the page and displayed to the end user to verify. The third ticket field will store data that the Zendesk bot gathers from the user during the interaction.

For more information on Messaging Metadata, see Using Messaging Metadata with the Zendesk Web Widget and SDKs.

Note: The version of Web Widget that lets you embed messaging functionality in your website is not the same as Web Widget (Classic). See Comparing the Zendesk Web Widgets for more information.

This tutorial uses JSFiddle, a free online code editor with live page previews. You can, however, use other preview code editors such as CodePen and JS Bin.

What you need

• If you don't already have a Zendesk Support account, register to start a free trial at https://www.zendesk.com/register/.

• A Zendesk admin has configured messaging Web Widget. See Creating a messaging Web Widget.

• A configured Zendesk bot. See Working with messaging bots for your web and mobile channels.

Note: This tutorial publishes a bot. We recommend you run this tutorial on a trial account, not your production Web Widget, to avoid any possible issues.

Creating the custom ticket fields

For this tutorial, you'll create three custom ticket fields for the ticket:

• Itinerary Number

• Confirmation Number

• Meal

Creating the itinerary number custom ticket field

The itinerary number is displayed on the HTML page and will be passed directly to the agent by the Zendesk bot. It will not be displayed in the bot for the end user to confirm.

1. In Admin Center, click Objects and rules in the sidebar, then select Tickets > Fields.

2. Click Add field.

3. Select Text, then for Display name, enter Itinerary Number.

4. Under Permissions, select Customers can edit.

5. For Title shown to customers, enter Itinerary Number.

6. Click Save.

Record the field id for this custom field as you'll need it for the API call.

Creating the confirmation number custom ticket field

The confirmation number is displayed on the HTML page and will be displayed in the Zendesk bot to confirm before passing it to the agent. Follow the same steps as above, except enter Confirmation Number for Display name and Title shown to customers.

Record the field id for this custom field as you'll need it for the API call.

Creating the meal custom ticket field

Create a meal ticket field for the Zendesk bot to query the end user.

1. In Admin Center, click Objects and rules in the sidebar, then select Tickets > Fields.

2. Click Add field.

3. Select Drop-down, then for Display name, enter Meal?.

4. Under Permissions, select Customers can edit.

5. For Field values, create a value for Yes and No (a yes and no tag will be added automatically).

   

6. Click Save.

Configuring the bot

Configure the Zendesk bot so that it asks the end user whether they want a meal before transferring them to an Agent. You'll create a clone of the default Answer Bot to do this.

1. In Admin Center, click Channels in the sidebar, then select Bots and automation > Bots.

2. If the Bots page opens with a choice of Conversation or Autoreply bot, click Manage bots under Conversation bot.

3. Hover over the default Answer Bot bot (usually the first in the list) and click the Options icon, then select Clone.

4. Hover over the cloned bot and click Settings.

5. Name the bot Booking, click Save, and then click Edit bot located under the Channels heading.

6. If Show me articles has a status of Ready to publish, hover over that line, click the Options icon, and select Make inactive.

7. Hover over Talk to a human and click Edit.

   You'll modify this flow for the Zendesk bot on the travel page.

8. Right click the last step (the Transfer step) and select Delete this step.

9. Click Add step and select Ask for details.

10. For Name, enter Confirmation.

11. For Fields, select the Confirmation Number text field under Custom fields.

12. Click Add step and select Ask for details.

13. For Name, enter Meal.

14. For Fields, select the Meal custom drop-down field under Custom fields.

15. Click Add step and select Transfer to agent.

16. For the Bot message, enter Thank-you. I'll transfer you to an agent now.

    Your flow should look like this.

    

17. Click Done.

18. Hover over Talk to a human and click the Options icon, then select Make Active.

19. Click Publish bot in the upper-right side of the page, select your Web Widget channel, and click Publish to selected channels.

Creating the HTML page

For your travel itinerary, you'll create a very simple HTML page that lists a intinerary number and confirmation number. You'll also add Web Widget with your Booking bot to the page.

1. In your web browser, go to https://jsfiddle.net/.

2. Copy and paste the following HTML code into the HTML editor located in the upper left UI panel of JSFiddle.

   <!DOCTYPE html>
   <html lang="en">
   
      <head>
         <title>Example itinerary</title>
      </head>
   
      <body>
         <p>Example itinerary</p>
   
         <label for="itinerary">ITINERARY NUMBER:</label>
         <label id="ITINERARY_FIELD_ID" name="itinerary_value">123456</label>
   
         <br>
   
         <label for="confirmation">CONFIRMATION NUMBER:</label>
         <label id="CONFIRMATION_FIELD_ID" name="itinerary_value">ABC123DEF456</label>
   
      </body>
   
   </html>

   Note: Replace ITINERARY_FIELD_ID and CONFIRMATION_FIELD_ID with the field id of your custom fields. See Creating the custom ticket fields.

3. In Admin Center, click Channels in the sidebar, then select Messaging and social > Messaging.

4. Click your Web Widget channel name and then click the Installation tab.

5. Click the Copy code icon on the lower-right side of the code block to copy the Web Widget code snippet.

6. In JSFiddle, paste the code snippet after the Example itinerary paragraph tag. Your HTML should look similar to this:

   <!DOCTYPE html>
   <html lang="en">
   
      <head>
         <title>Example itinerary</title>
      </head>
   
      <body>
         <p>Example itinerary</p>
      
         <!-- Start of Zendesk Widget script -->
           <script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key={key}"> </script>
         <!-- End of Zendesk Widget script -->
   
         <label for="itinerary">ITINERARY NUMBER:</label>
         <label id="ITINERARY_FIELD_ID" name="itinerary_value">123456</label>
   
         <br>
   
         <label for="confirmation">CONFIRMATION NUMBER:</label>
         <label id="CONFIRMATION_FIELD_ID" name="itinerary_value">ABC123DEF456</label>
   
      </body>
   
   </html>

Calling the metadata API

Copy and paste the following code into the JavaScript panel located in the lower left UI panel of JSFiddle. This code closes the web widget launcher upon page load and gets the value of the itinerary and confirmation fields.

zE('messenger', 'close');

var itin = document.getElementById('ITINERARY_FIELD_ID');
zE('messenger:set', 'conversationFields', [{ id: ITINERARY_FIELD_ID, value: itin.getInnerHTML()}]);

var conf = document.getElementById('CONFIRMATION_FIELD_ID');
zE('messenger:set', 'conversationFields', [{ id: CONFIRMATION_FIELD_ID, value: conf.getInnerHTML()}]);

Note: Replace ITINERARY_FIELD_ID and CONFIRMATION_FIELD_ID with the field id of your custom fields.

Try it out

You can now launch the messaging bot in the widget. In JSFiddle, click the Run button located in the upper left corner to run the code and render your sample page.

1. Click the widget launcher icon.

2. Enter agent to start the workflow.

   

Testing and debugging

If your custom fields appear in your agent ticket but contain no data, first check that Messaging Metadata is enabled for your instance.

1. In JSFiddle, right click in a blank area and select Inspect.

2. Click the Network tab and refresh your browser.

3. Search for console in the Name column.

4. Expand features and make sure conversationTicketMetadata is set to true.

   

You can also print out the itin and conf variables to make sure you are getting the data. For example:

var itin = document.getElementById('15196259758359');
console.log('itinerary', itin.getInnerHTML());
zE('messenger:set', 'conversationFields', [{ id: 15196259758359, value: itin.getInnerHTML()}]);

var conf = document.getElementById('15196261467159');
console.log('confirmation', conf.getInnerHTML());
zE('messenger:set', 'conversationFields', [{ id: 15196261467159, value: conf.getInnerHTML()}]);