Integrate your Certainly bot with Gorgias

In this article, we'll address how to set up the Certainly chat integration with Gorgias. You'll be able to deploy this integration on any website you own.

Below, you'll learn how to:

• Integrate your Certainly bot with Gorgias Live Chat
• Integrate your Certainly bot with Gorgias Email Support

Integrate your Certainly bot with Gorgias Live Chat

This integration allows your Certainly chatbot to seamlessly hand over a live conversation to Gorgias. Your agents can pick up the conversation from the Gorgias platform and chat with the visitor in real time to solve the claim.

Check out a video of the solution below: 

 

In this section, we explain how to set up the handover and deploy the integration on your site: 

• How to configure the handover to Gorgias Live Chat
• How to deploy the Live Chat integration on your website
• Custom Variables used by the extension
• Gorgias rules and macros

How to configure the handover to Gorgias Live Chat

Now we'll explore the recommended flow for handover to Gorgias Live Chat, as shown here:

1. First, the bot collects the visitor's name and email into the visitor_name and visitor_email CVars. If a user already exists, the bot retrieves the user ID and sets the gorgias_customer_id CVar. If no user exists, a new user is created.
    
2. The bot checks if the Gorgias chat integration is enabled, then uses the hours and time zone defined in the Gorgias settings to determine if the handover is taking place during business hours before checking agent availability.
    
3. To hand over to Gorgias Live Chat, the CVar gorgias must be set with the value start_chat in the Create chat request Module, then the conversation moves to Show Chat Queue.
    
4. In the Show Chat Queue Module, you'll set the CVar gorgias with an empty string value {{””}} so the extension won't try to initiate the Live Chat anymore. 
   
   While the visitor is waiting for an agent to pick up the chat, a countdown clock overlay is shown. During this time, the visitor has the option to cancel the request. You can set the wait time in the chat_queue_timeout CVar.
    
5. The main action occurs in the next Module, Synch Messages with Gorgias. Here, the bot checks if a message received from the user contains one of the following predefined chat events, which are hidden messages sent by the extension:
   • QUEUE_CANCELED: User selected "Cancel" while waiting for agent to pick up chat.
   • QUEUE_TIMEOUT: Timeout expired. By default, waiting time is 60 seconds.
   • CERTAINLY_HANDOVER: Sent by Gorgias agent to signal to bot that Live Chat is over. 
   If the message doesn't contain any of these chat events, the bot determines that it came from the user and sends it to the Gorgias agent by assigning the message to the visitor_message CVar.
    
6. The bot takes over the conversation after the agent sends the message CERTAINLY_TAKEOVER, either directly or via a rule.

How to deploy the Live Chat integration on your website

Finally, you'll need to deploy both Gorgias Chat and Certainly on your website. The instructions for this step depend on whether your website runs on Shopify:

• Shopify theme
• Other websites

Shopify theme

If your site is running on Shopify, please embed the snippet below into your theme.liquid file.

<!--Gorgias Chat Widget Start-->
<script id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=8611"></script>
<!--Gorgias Chat Widget End-->

<!--Certainly Widget Start-->
<script src="https://app.certainly.io/sdk/webchat.js"></script>
<script>
var certainly_settings = {
    id: "d56d3bcd-8d79-4311-a808-cc0ecc8dcf1a" // Chatbot Deployment ID found in Bot's settings
}

// The following passes Shopify user metadata to Certainly, if the user is behind login
{% if customer -%}
certainly_settings.cvars = {
    customer_name: "{{customer.name}}",
    customer_email: "{{customer.email}}",
    customer_id: "{{customer.id}}",
    customer_orders: "{% for order in customer.orders %}{{ order.id }}{% if forloop.last == false%},{% endif %}{% endfor %}"
}
{%- endif %}
initCertainlyWidget(certainly_settings);
</script>
<!--Certainly Widget End-->

<!--Gorgias extension for Certainly-->
<script src="https://scripts.certainly.io/extensions/gorgias/gorgias.js"></script>
<!--Gorgias extension for Certainly End-->

 

 
Other websites

If you are not running on Shopify, please embed the snippet below into your website.

<!--Gorgias Chat Widget Start-->
<script id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=8611"></script>
<!--Gorgias Chat Widget End-->

<!--Certainly Widget Start-->
<script src="https://app.certainly.io/sdk/webchat.js"></script>
<script>
var certainly_settings= {
  id: "d56d3bcd-8d79-4311-a808-cc0ecc8dcf1a", // Chatbot Deployment ID found in Bot's settings
  cvars: {
    // Customer Variables to pass to the bot
  }
});
initCertainlyWidget(certainly_settings);
</script>
<!--Certainly Widget End-->

<!--Gorgias extension for Certainly-->
<script src="https://scripts.certainly.io/extensions/gorgias/gorgias.js"></script>
<!--Gorgias extension for Certainly End-->

 
That's it! Your Certainly chatbot is now ready to hand visitors over to Gorgias agents. If you encounter any problems in the configuration, just reach out to our Customer Success team.

Custom Variables used by the extension

Custom Variable	Example	Description
{{visitor_name}}	John Doe	Appears as a user name in Gorgias Chat
{{visitor_email}}	john@email.com	Used to match the user record in Gorgias
{{gorgias}}	agent_availability	When assigned, extension returns hidden message AGENTS_ONLINE or AGENTS_OFFLINE
	start_chat	When assigned, initiates Gorgias Live Chat
{{chat_queue_timeout}}	90	Wait time in seconds before an agent takes over the conversation. 60 sec by default

 

Gorgias rules and macros

Below, we've collected some rules that may be helpful for integration with Certainly:

• Gorgias rule to set up the tags
• Gorgias rule to close the ticket due to cancellation or expiration
• Gorgias macro to hand over conversation to Certainly bot and close the ticket

Gorgias rule to set up the tags

This rule adds created_by_certainly and handed_over_by_certainly tags to the chat ticket:

Gorgias rule to close the ticket due to cancellation or expiration

The Gorgias chat ticket is created before the agent starts chatting with the user. If the user cancels the queue, the ticket remains open. This rule automatically closes the chat ticket after a user selects the Cancel button while waiting for an agent to join, or once the waiting time has expired, allowing agents to focus on other matters.

Gorgias macro to hand over conversation to Certainly bot and close the ticket

To hand a conversation back over to the Certainly chatbot, an agent needs to send the message CERTAINLY_TAKEOVER. The user won't see this message. When the bot receives the message, it knows that the live chat is over. The macro shown below automates this task.

Integrate your Certainly bot with Gorgias Email Support

This integration allows your bot to create an email conversation on behalf of the visitor as a ticket in the Gorgias platform. This way, your Certainly bot will always act as your first level of support, while human agents only intervene via email when needed.

Check out a video of the solution below:

 
In this section, we explain how to set up and test the handover:

• How to configure the handover to Gorgias Email Support
• How to test the handover to Gorgias Email Support

How to configure the handover to Gorgias Email Support

For this integration, the recommended bot configuration is as shown here:

1. On Gorgias, you'll do the following:
   1. Create a new agent with admin permissions and name it "Certainly Bot" or similar. This agent will be used by Certainly when forwarding tickets to your support agents.
   2. Generate a Gorgias API key for the chatbot agent. This API key will be used to authenticate Certainly Webhook requests to your Gorgias account.
       
2. In the Certainly Platform, you'll ensure your bot contains the flow shown above and has been saved and published via the Navigation bar.
    
3. Next, you must create an instance of each of the following Webhook Templates (WHTs), filling in the Authorization field with your Gorgias API Key and the "domain" field with the correct domain from your Gorgias account environment (e.g., “dev-certainly” from dev-certainly.gorgias.com/app).
   • Gorgias Transfer Ticket Create
   • Gorgias Transfer Ticket Update
   • Certainly Get Conversation History - Note: This Webhook instance will not require any additional Authorization or "domain" configuration.
   • Gorgias Transfer Update Ticket Conversation History
      
4. Then you'll navigate to your chatbot canvas and refresh the webpage. Otherwise, you won't be able to see the newly created Webhooks.
    
5. In the Gorgias Ticket Create Module, you will have multiple connections. The first one should be a set of Custom Variables needed for the first Ticket Creation. In the second connection, insert your Webhook instance Gorgias Transfer Ticket Create.
    
   It should look like this:
    
6. Insert your Webhook instance Gorgias Transfer Ticket Update inside the Gorgias Ticket Update and Sending Open Ticket Info Modules.
    
   It should look like this (you can also update tags and status on this step):
   
   and like this: 
    
7. After the chat reaches a point where the issue is either solved or must be handed over, update the ticket with the transcript so agents have a full understanding of the matter.
    
   To do so, add the Certainly Get Conversation History and Gorgias Transfer Update Ticket Conversation History Webhooks to the Sending Open Ticket Info and Gorgias Ticket Conversation History Update Modules.
    
   It should look like this:
    
   and like this:
    
   Note that the Certainly Get Conversation History and Gorgias Transfer Update Ticket Conversation History Webhooks are separated. It may take a moment to fetch the chat info, and we want them to happen in separate actions to allow time between them.
    
8. Save and publish your Certainly bot once more via the Navigation bar.

Now your bot will be ready to create and update email conversations when the user needs it! The final step is to test the handover.

How to test the handover to Gorgias Email Support

Once setup is complete, we suggest running a test to ensure everything works properly.

• When the user selects a topic, creating a ticket should look like this:
  Email, status (open/closed), tags, and text body are needed.

• When the question is answered and the user marks it as helpful, the ticket is updated:

• After prompting if they need any more help, regardless of the answer, the conversation gets updated as well:

• Finally, if the user needs to be handed over to a human agent, the ticket status gets updated to Open, and the tags are updated as well. The bot flow should be set up to ask for name and email to create an email conversation for the agent to get in contact:

Great work - now your bot is fully integrated with Gorgias!