Title Heading {}style{font-family: Open Sans;};

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: 

An Admin account in Zendesk is required to complete the integration.

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:

    Accesing Zendesk Admin center
     
  2. Once in the Admin Center view, we have to open the "Apps and Integrations" section, and inside that, click on "Conversations API":

    Open 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".

    Zendesk Conversations API Installation-gif-1

  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:

    Enter_Subdomain.png 
  3. Grant the Certainly app permission to access your Zendesk account:

    Grant_permissions.png 
  4. You should now see that the bot is connected, as in the image below:

    blobid5.png 
  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":

    paste zendesk key and secret 
  6. You'll be presented with a dropdown list. Select Certainly to ensure your bot will be the first responder to incoming messages:

    SunCo_-_Set_Default_Integration.png

  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:
    Marketplace Bots


    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:

    Zendesk Conversations API Validation-gif-2

 

You've now integrated your Certainly bot with Zendesk Messaging. Congrats!


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:

    Accessing messaging in zendesk

  2. Click on the "Add Channel" and create a Web Widget Channel:
    Copy snippet

  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 wh_iconSunshine 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:

ticket tags

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.

mceclip3.png

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:

mceclip2.png

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:

Takeover.png

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))%

pass_control.jpg

We recommend saving the string as a Macro in Zendesk so all your agents can quickly select it and avoid typing it in.

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.