Integrate your Certainly bot with Zendesk Messaging (Previously Sunshine Conversations)

This article will focus on connecting your Certainly bot to your own Zendesk Messaging account.

Zendesk Messaging will allow your bot to communicate with customers across all popular messaging apps. Learn more in the Zendesk Messaging documentation.

Below, we'll walk you through the following: 

• Obtaining Conversation API credentials on the Zendesk platform
• Connecting your bot to Zendesk Messaging
• Validating that Certainly is Connected to Zendesk Messaging
• Embedding the Zendesk Messaging widget
• Enabling Human Agent Takeover
• Return control to you Certainly bot

Obtaining Conversation API credentials on the Zendesk platform

1. Log in to your Zendesk account and open the "Zendesk Products" menu located in the top right corner of your screen. Once in the Zendesk Products menu, open your Zendesk Admin Center view by clicking the "Admin Center" link:
   
   
    
2. Once in the Admin Center view, we have to open the "Apps and Integrations" section, and inside that, click on "Conversations API":
   
   
   
   If the "Conversations API" Section is not visible under Apps, it means that you do not currently own a paid license to Zendesk, a paid license is required in order to create a Conversations API endpoint
    
3. Inside the "Conversations API" section click on the button labeled "Create API key":
   
   
   
   
4. A pop-up will appear in which you will have to indicate a name that identifies your API Key's name. Follow the prompts and make sure that you copy your API Secret Key in a safe place, as we will be needing it later.

Connecting your bot to Zendesk Messaging

1. Once on the Certainly Platform, open up the bot you wish to connect to Zendesk Messaging, then navigate to Bot Settings > Channels. In the Sunshine Conversations section, click on "Connect".
   
   
   
   
2. You’ll then be asked to enter your Zendesk subdomain, select "Sign in" and enter the credentials of your Zendesk bot account when prompted:
   
    
3. Grant the Certainly app permission to access your Zendesk account:
   
    
4. You should now see that the bot is connected, as in the image below:
   
    
5. Next, you'll want to ensure that your Certainly bot is the default integration, meaning it will respond to incoming messages first.
   
   To do so, copy and paste your previously created Conversation API Key ID and Secret into the relevant fields in the Switchboard configuration section, then select "Enable Switchboard":
   
    
6. You'll be presented with a dropdown list. Select Certainly to ensure your bot will be the first responder to incoming messages:
   
   
   
   
7. Once the switchboard has been configured. We can check that the integration has been made correctly by navigating back to your Zendesk Admin Center. On the left-hand menu, under channels, click on "Bots".
   
   
8. A Certainly bot icon should appear on your Zendesk account:
   
   
   
   You've now integrated your Certainly bot with Zendesk Messaging. Congrats!

Once the Switchboard integration is established, it is not possible to edit the settings or use other tokens (ID and Secret) unless the Switchboard is removed and added again. 

Validating that Certainly is Connected to Zendesk Messaging

1. Head over to your Messaging settings within your Zendesk subdomain's Admin Center. If you have not done it already, configure a Web Widget channel.
2. Open your Web Widget Channel settings, and make sure Certainly is set to be the first line of response under the "Response" tab.
3. Click on "Test it now" to open a preview of the Messaging Web Widget. Your Certainly bot should successfully pick up conversations:
   
   

 

Embedding the Zendesk Messaging widget

1. To add the Zendesk Messaging widget to your site, first navigate to the "Messaging" section, under Channels, in the left-hand menu for your Zendesk Admin Center:
   
   
   
   
2. Click on the "Add Channel" and create a Web Widget Channel:
   
   
   
3. Paste the code snippet you just copied inside the HTML for your website, just before the closing </body> tag.
   
   

Enabling Human Agent Takeover

Your bot is now handling all of the incoming chats in any of the channels you have enabled in your Zendesk Messaging settings. This section shows how to pass control of a conversation to your Zendesk agents at any given point during a conversation.

To do this, you'll need to create an instance of our Sunshine Conversations Pass Control Webhook. You can use it straight away without configuring anything, but if you do want to configure it, instructions are provided in the Webhook description.

When passing ticket field data to Zendesk, make sure to avoid using empty variables. Apply the default('') Jinja filter, as shown in the example above, to prevent any issues with the webhook. Failure to do so may result in the conversation not being transferred to a human agent.

One example is being able to pass a string of comma-separated tags, like in the below image:

{
  "switchboardIntegration": "zd-agentWorkspace",
    "metadata": {
       "dataCapture.systemField.tags": "created,solved",
       "dataCapture.ticketField.900009347206": "{{ order_number|default('') }}",
  }
}

When the Webhook is fired, it will add tags to your tickets:

Passing full chat history with the bot

By default, Zendesk passes the last 10 messages from the chatbot when creating a conversation ticket. To have a full chat history, you need to specify from what message you want it. It is easily achieved in 2 steps: 

First, you need to record the message ID of the first message in the Start module by having a connection like this:

Here is Jinja code for this

{{ sc.conversation.last_message.id }}

Then you need to add the "first_message_id" field under metadata in the handover Webhook like the following:

{
  "switchboardIntegration": "zd-agentWorkspace",
  "metadata": {
     "dataCapture.systemField.tags": "created,solved",
     "first_message_id": "{{ first_message_id|default('') }}",
     "dataCapture.systemField.requester.name":  "{{ visitor_name |trim |safe }}",
     "dataCapture.systemField.requester.email": "{{ visitor_email |trim |safe }}"
  }
}

Once you've saved your Webhook, you can now insert it into your handover flow in the bot canvas.

Insert Webhook into handover flow

The below image shows a simple flow you can implement when a user requests human support.

In the Connections tab of the Module after a user has clicked "Yes" to confirm they want to speak with an agent, simply add your newly created Webhook. Then, "Go to" a subsequent Module where you ask the user to wait until a human agent joins the conversation.

You can see this illustrated below:

Save and publish, and your bot will now be able to hand over to a human agent in Zendesk Support!

Return control to your Certainly bot

Bot Takeover is when your human agent wants to give a conversation back to your chatbot. In this section, we'll share an overview of how to hand a conversation from one of your Zendesk agents back to a bot.

For a bot to take over the conversation from your human agent, you will need to create a connection in the Bot Takeover section which is found in Bot Settings, located in the right sidebar menu.

Go to “Bot Takeover”. Here you will have to add a connection that exactly matches with "PassControlEvent" and define the destination Module in "Go to". Be aware that "PassControlEvent" is case-sensitive.

Please see the image below as a reference:

Once you have the connection set up, click Save & Publish. For your Zendesk agents to successfully hand over a conversation back to the bot, they'll have to enter the following string in the messaging field:

%((switchboard:passControl:bot))%

Please be aware that every time you make a change related to takeover functionality, you'll need to publish the bot in order for the changes to propagate live.