Sunshine Conversations Web Messenger

Overview

You can set up your AI Agent to work through the Sunshine Conversations Web Messenger interface instead of Ada’s usual web interface. This approach can work differently from Ada’s usual behavior and has both benefits and limitations you should be aware of, but it can be a good alternative if you want to use more of Zendesk’s features.

Use cases

Sunshine Conversations Web Messenger enables the following scenarios:

• Leverage Zendesk’s ecosystem: Use Zendesk’s branding, persistence, and conversation features instead of Ada’s settings.
• Unified conversation experience: Enable seamless Handoffs between your AI Agent and human agents.
• Multi-conversation support: Allow end users to create multiple conversations at once.

Capabilities & configuration

The customer experience in Sunshine Conversations Web Messenger is very similar to Ada’s default web experience in a lot of ways. Here are some basics:

• Customers can use the same conversation window to exchange messages with both your AI Agent and with your human agents, with seamless handoffs to Zendesk Messaging in between.

  You can also enable multi-conversation functionality, so customers can create more than one conversation at a time, with Sunshine Conversations’s Conversation List feature.

• Customers and agents can send files to each other. For information on how Sunshine Conversations validates files, see File Validation at Sunshine Conversations docs.

• After the customer has been handed off to an agent, the chat window is reserved for their conversation with the agent. Only the agent can disengage the conversation by marking the ticket as “solved.” After this, depending on your organization’s trigger settings, Zendesk automatically marks the ticket as “closed.”

  Until the ticket is marked as “closed,” any messages the customer sends go to the human agent, not the AI Agent. The customer has to wait until the ticket is closed to be able to send messages to your AI Agent again.

• You can use Ada’s multi-bot routing feature. For more information, see Connect Zendesk social channels to multiple AI Agents using Sunshine Conversations.

AI Agent behavior with Web Messenger

There are some features that you may have built into your AI Agent that won’t translate to Sunshine Conversations Web Messenger.

• Metavariables: You can’t set metavariables in Sunshine Conversations Web Messenger. If your Answer flows require access to metadata, you can contact your Ada team for assistance, or use a Request block to request data from Sunshine Conversations’ API. For more information, see Sunshine Conversations’ API documentation.

• Customer persistence: Instead of using Ada’s settings, use Sunshine Conversations’ SDK settings to adjust how you want to retain users or conversations. For more information, see Browser storage at Sunshine Conversations’ documentation.

• Branding: Instead of using Ada’s settings, use Sunshine Conversations’ SDK settings to adjust how you want the chat window to appear. For more information, see Display Style at Sunshine Conversations’ documentation.

Quick start

Deploy your AI Agent with Sunshine Conversations Web Messenger in a few steps. For detailed instructions, see Implementation & usage.

Implementation & usage

Setting up your AI Agent to work with Sunshine Conversations Web Messenger requires some work with your AI Agent, in Sunshine Conversations, in Zendesk, and finally in your own website. If you have any trouble with any portion of these procedures, don’t hesitate to contact your Ada team for assistance.

Prerequisites

Before proceeding, do a quick check to see that you have the following:

• Access to Zendesk Agent Workspace

• A subscription to Zendesk Suite Professional, Enterprise, Enterprise Plus, or a standalone Sunshine Conversations license add-on

• Access to the Zendesk Conversations API through Zendesk Admin Center, so you can create API keys

• A completed Sunshine Conversations integration with your AI Agent. For more information, see Configure and use Sunshine Conversations.

Additionally, contact your Ada team to make sure your AI Agent is ready for the next steps. There are some features you may need Ada staff to enable on your behalf that you can’t proceed without.

Zendesk API setup and channel creation

After you’ve verified that you have everything you need, you can use the Sunshine Conversations API to create a new channel.

To use the API, you should have an API client program, like Postman, installed on your computer. You may find it helpful to download the API collection so you can see those calls pre-formatted in your client program.

To set up the Zendesk API and create a channel:

1. In Zendesk Agent Workspace, go to Apps and Integrations > APIs > Conversation APIs. On this page, find the following API attributes and copy them:

   • appID

   • key

   This should be the same key you used to set up your Sunshine Conversations integration. To generate an API key, see Conversations API authentication in Zendesk’s documentation.

   • secret

2. In your API client, set up your authentication. Depending on your setup, you can choose to use these settings for all of your Zendesk API calls, or just this one call.

   • Set the authentication type to Basic Auth.

   • For your Username, use the key from your API details.

   • For your Password, use the secret from your API details.

3. Make the following API call, replacing the appID placeholder with the value you got in your API details. In the API collection, it’s called Create Integration. With this call, you’re creating a new integration for your Sunshine Conversations account:

   POST https://api.smooch.io/v2/apps/{appID}/integrations
   {
     "type": "web",
     "displayName": "Channel Name",
     "canUserSeeConversationList": false,
     "canUserCreateMoreConversations": false
   }

4. Depending on the integrations you have set up, you might have multiple integrations come back in your response; each one will look like the below. Look for the integration that has the following two attributes:

   • "status": "active"

   • "type": "web"

   For that integration, copy the id attribute.

   {
     "integration": {
       "id": "645032477d43a37749e94ef6",
       "status": "active",
       "type": "web",
       "displayName": "Channel Name",
       "brandColor": "65758e",
       "conversationColor": "0099ff",
       "actionColor": "0099ff",
       "displayStyle": "button",
       "canUserCreateMoreConversations": false,
       "canUserSeeConversationList": false
     }
   }

Website embedding

Now that you have your integration ID, you can embed your AI Agent on your website. To do that, you’ll need to insert two scripts into your website.

1. In your website’s <head> tag, towards the end, insert the following script. Replace the ADD-INTEGRATION-ID-HERE portion at the end with the ID you got from Zendesk:

   1
   <script>
   2
     !function(o,p,s,e,c){
   3
         var i,a,h,u=[],d=[];function t(){var t="You must provide a supported major version.";try{if(!c)throw new Error(t);var e,n="https://cdn.smooch.io/",r="smooch";if((e="string"==typeof this.response?JSON.parse(this.response):this.response).url){var o=p.getElementsByTagName("script")[0],s=p.createElement("script");s.async=!0;var i=c.match(/([0-9]+)\.?([0-9]+)?\.?([0-9]+)?/),a=i&&i[1];if(i&&i[3])s.src=n+r+"."+c+".min.js";else{if(!(4<=a&&e["v"+a]))throw new Error(t);s.src=e["v"+a]}o.parentNode.insertBefore(s,o)}}catch(e){e.message===t&&console.error(e)}}o[s]={init:function(){i=arguments;var t={then:function(e){return d.push({type:"t",next:e}),t},catch:function(e){return d.push({type:"c",next:e}),t}};return t},on:function(){u.push(arguments)},render:function(){a=arguments},destroy:function(){h=arguments}},o.__onWebMessengerHostReady__=function(e){if(delete o.__onWebMessengerHostReady__,o[s]=e,i)for(var t=e.init.apply(e,i),n=0;n<d.length;n++){var r=d[n];t="t"===r.type?t.then(r.next):t.catch(r.next)}a&&e.render.apply(e,a),h&&e.destroy.apply(e,h);for(n=0;n<u.length;n++)e.on.apply(e,u[n])};var n=new XMLHttpRequest;n.addEventListener("load",t),n.open("GET","https://"+e+".webloader.smooch.io/",!0),n.responseType="json",n.send()
   4
     }(window,document,"Smooch","ADD-INTEGRATION-ID-HERE","5");
   5
   </script>

2. Use the following script to initialize your AI Agent, again replacing the ADD-INTEGRATION-ID-HERE portion at the beginning with your integration’s ID. You can use it in a different script, or you can put it in your website’s <body> tag, inside a <script> tag, to load every time your website does:

   1
   Smooch.init({
   2
     integrationId: 'ADD-INTEGRATION-ID-HERE',
   3
     integrationOrder: [],
   4
     notificationChannelPromptEnabled: false,
   5
     canUserSeeConversationList: false
   6
     }).then( function() {
   7
       // Your code after init is complete
   8
     }, function(err) {
   9
       // Something went wrong during initialization
   10
     }
   11
   );
   Make sure you don’t change the integrationOrder, notificationChannelPromptEnabled, or canUserSeeConversationList attribute values. These are required to disable Sunshine Conversations features that Ada doesn’t support.

3. With both of these pieces of code in your webpage, you can test your AI Agent. If it worked correctly, when you load your webpage, you should see the chat bubble appear on the page.

If you followed these instructions and are still having problems, or if your AI Agent is loading but not responding to your messages, feel free to contact your Ada team for assistance.

Appearance customization

After making sure your AI Agent is working, you can customize how it looks, by modifying the second code snippet above. You can see a full list of customizations you can make at the Smooch Web Messenger documentation, but the most common ones you may be interested in are:

• businessName - The AI Agent’s name that appears at the top of the chat window

• businessIconUrl - A link to the image you want to display at the top of the chat window

  This image only appears at the top of the chat window. It’s not the AI Agent avatar, which you can change in your Ada settings. For more information, see Customize the chat window.

• customColors - Branding colors that you can apply to your AI Agent. All of these values must be 3- or 6-character hexadecimal color codes, without the hex sign at the beginning

  • brandColor - The color of the chat button when the window is collapsed, and the header of the window when the window is open

  • conversationColor - The color of the customer’s chat bubbles, and quick reply bubbles that they can select

  • actionColor - The color that highlights actions that customers can take, like the outline of the field where the customers can type in messages to the AI Agent

All of the above customizations go into the initializing code snippet above. Here’s an example of a completed snippet with all of the above attributes populated:

1
Smooch.init({
2
  // Default bot settings
3
  integrationId: 'ADD-INTEGRATION-ID-HERE',
4
  integrationOrder: [],
5
  notificationChannelPromptEnabled: false,
6
  canUserSeeConversationList: false,
7
  // Bot customizations
8
  businessName: 'My AI Agent',
9
  businessIconUrl: 'https://media.smooch.io/5f19b4c836ced4000c3a7dc3/icons/8f539f6284ca2f79cda7b0bda0b98cc3.jpg',
10
  customColors: {
11
    brandColor: '944dff', // Purple
12
    conversationColor: '4ddbff', // Cyan
13
    actionColor: 'ff4da6', // Hot pink
14
  },
15
  }).then( function() {
16
    // Your code after init is complete
17
  }, function(err) {
18
    // Something went wrong during initialization
19
  }
20
);

Handoff configuration

Rather than the usual platform-specific handoff blocks used elsewhere in Ada, if you’re using Sunshine Conversations Web Messenger, you need to create handoffs using API calls.

To configure a handoff:

1. On the Ada dashboard, go to Config > AI AGENT > Handoffs, then create or select a handoff to edit. For more information, see Manage how your AI Agent hands customers off to live agents.

2. Click and drag a Request block into the end of the handoff content.

3. Create a POST call with a URL in this format:

   https://api.smooch.io/v2/apps/{appID}/conversations/{conversationID}/passControl
   1. Replace {appID} with the same appID you found when you were finding your Zendesk API key.
   2. Replace {conversationID} with the automatic sunshine_conversation_id variable.

4. Under Headers, add your authorization token.

   1. In the field on the left, enter Authorization.
   2. In the field on the right, enter Basic, then enter the automatic sunshine_basic_token variable.

5. Under Body Content, add a switchboardintegration attribute.

   1. In the field on the left, enter switchboardintegration, and in the dropdown list, select String as the data type.
   2. In the field on the right, enter next.
   • Alternatively, if you have a specific switchboard integration ID, you can enter that ID instead.

6. Under Body Content, create a metadata attribute, in which you can add additional information.

   In the field on the left, enter metadata, and in the dropdown list, select Dictionary as the data type. With this data type, there is on field on the right to add a single corresponding value; instead, you can nest other attributes within it.

7. Beside the metadata attribute, click Add to add a row under the metadata attribute.

   This attribute tells Sunshine Conversations which was the first message in the customer’s most recent interaction with your AI Agent. That way, the agent can see the whole conversation for context, instead of the default behavior of only the last 10 messages in the conversation.

   1. In the field on the left, enter first_message_id, and in the dropdown list, select String as the data type.
   2. In the field on the right, enter the sunshine_first_message_id variable.

8. Optionally, add additional metadata, using Zendesk’s metadata fields. For example, if you want to attach tags to the tickets you create through your AI Agent:

   1. In the field on the left, enter dataCapture.systemField.tags.
   2. In the field on the right, enter the tags you want to attach, separated by commas (e.g., ada_agent, automatic_handoff).

9. Edit the Error fallback dialog that displays if there’s an issue completing the API call.

10. Turn on the Count as Handoff toggle.

With this flow, you can hand customers off to Zendesk for escalations, and you’ll be able to see these handoffs in your analytics.

Here’s an example of a completed Request block handoff:

Zendesk connection

Lastly, to allow your AI Agent to start interacting with customers, you have to connect your AI Agent with Zendesk. For more information, see Connect your AI Agent with Zendesk Admin Center.