Sunco SDK Implementation Guide

For the handover to work you must first collect the users name and email address. This can be done with either a Pre Chat Form or Request User Details Form.

Step 1 - Update Chat Widget Configuration

Below is a complete example of all configurations relevant to SunCo:

  window.DG_CHAT_WIDGET_CONFIG = {
    "crmSDKPlatform": "sunco",
    "generalSettings": {
      "enableCrmUserAttachments": true,
      "closeChatAfterAgentInitiatedCsat": true
    },
    "csat": {
      "type": "thumbs",
      "commentsCharacterLimit": 128
    },
    "lang": {
      "userClosedChatMessageToAgent": "*** USER CLOSED CHAT. ***",
      "csatLang": {
        "ratingsText": ["Bad", "Good"]
      }
    }
  }

crmSDKPlatform - When set to sunco, the Sunco SDK script is injected into the customers page.

generalSettings -> enableCrmUserAttachments - Enables the user to upload attachments at any point after handing over to SunCo.

generalSettings -> closeChatAfterAgentInitiatedCsat - Closes chat after the user has submitted CSAT (if offered by agent).

csat -> type - Sets the CSAT type to thumbs, bringing the DigitalGenius CSAT inline with Zendesks.

csat -> commentsCharacterLimit - Sets the character limit to 128, bringing the DigitalGenius CSAT comments inline with Zendesks.

lang -> csatLang -> ratingsText - The text displayed when the thumbs up / down CSAT icons are hovered over.

lang -> userClosedChatMessageToAgent - A message sent to the agent on the users behalf when the user ends chat before the agent has requested CSAT.

Step 2 - Setup Connection with SunCo API

In the Zendesk admin center, navigate to Apps and Integrations -> APIs -> Conversations API.

Select 'Create API key' and give your key a name, then select 'Next'.

Copy the App ID, Key ID and Secret key values and copy them in to the DigitalGenius postman collection environment variables in the SunCo section (if you have the latest version of Postman you can use the filter at the top of the env variables modal to filter by sunco):

Put the App ID value in to the sunco_app_id field

Put the Key ID value in to the sunco_api_key_id field

Put the Secret key value in to the sunco_api_key_secret field

Go back to the Sunco admin and click on the Next button.

Step 3 - Create a module connection on the Dashboard

Go to modules and select Sunshine Conversations:

Click to create a new connection and populate all the required fields. You can get the App Id from Step 2:

Once submitted click on the Authenticate Sunshine Conversations button and follow the steps to authorize DigitalGenius with Sunshine Conversations:

Step 4 - Get Web Integration ID

In Postman, navigate to Genius Flow API collection -> Integrations -> Sunshine Conversations -> SunCo Setup

Execute the GET Get Integrations endpoint, find the integration with "type": "web", copy it's ID and store it somewhere safe.

Step 5 - Get Switchboard Integration ID

In Postman, navigate to Genius Flow API collection -> Integrations -> Sunshine Conversations -> SunCo Setup

Execute the GET List Switchboards endpoint, there should only be one switchboard so copy it's ID and paste it in the sunco_switchboard_id Postman environment variable.

Execute the GET Get Switchboard Integrations endpoint, find the integration with "integrationType": "zd:agentWorkspace",, copy it's ID and store it somewhere safe.

Step 6 - Flow Agent Handover

In flow, add a new chat activity at the point where handover is required.

Select 'Agent Handover' and populate the JSON input with the following fields:

{
  "crmPlatform": "sunco",
  "connectionId": "*******************",
  "appId": "*******************",
  "integrationId": "*******************",
  "switchboardIntegrationId": "*******************",
  "groupId": "*******************",
  "tags": "tag1,tag2,tag3",
  "shouldPassControl": true
}

crmPlatform - Set to sunco.

connectionId - The ID of the connection created in Step 2.

appId - The 'App ID' which was generated in step 3.

integrationId - The ID of the SunCo web integration copied in step 4.

switchboardIntegrationId - The ID of the SunCo zd:agentWorkspace switchboard integration copied in Step 5.

shouldPassControl (Optional) - Whether the frontend makes the passControl call, which allows us to add tags.

tags (Optional) - A string of comma separated tags.

groupId (Optional) - The ID of the Zendesk group tickets should be assigned to.

Step 7 - Configure Zendesk Bot

In the Zendesk admin center, navigate to AI -> AI agents and click on the Manage AI agents for messaginglink.

If you do not have a zd bot configured, click 'Create AI Agent' in the top right. Give the bot a name and proceed through the steps.

Edit your bot and select the 'Behavior' tab, ensure the bot starts with the answer 'Speak to a human'.

Next, we need to configure the 'Speak to a human' answer:

Delete all existing steps and add a 'Ask for details' step, give it a name and add the 'Name' and 'Email' fields.

After the 'Ask for details' step, add the 'Transfer to agent' step, any tags defined here are only added if shouldPassControl is false.

NOTE The required 'Bot message' is visible to the agent, but not the end user.

Save the flow and publish the bot.

Step 8 - Configure Zendesk CSAT

Chat can only support Zendesks legacy CSAT, which accepts a score of 1 or 2. (Good / Bad).

When setting up a new Zendesk environment, the new CSAT survey is enabled by default.

To revert to the legacy CSAT survey, navigate to Objects and rules -> Business rules -> Customer satisfaction.

In the top right, click the Actions button and select Turn off customer satisfaction.

Navigate to People -> End users and select the Satisfaction tab.

Check the Allow customers to rate tickets checkbox and hit Save.

Migration Guide to Chat Widget V3

Step 1 - Update Chat Widget Config

Add the following to your chat widget config:

  window.DG_CHAT_WIDGET_CONFIG = {
    crmSDKPlatform: 'sunco', // Required
    generalSettings: {
      enableCrmUserAttachments: true,
      closeChatAfterAgentInitiatedCsat: true,
    },
    csat: {
      type: 'thumbs', // Required
      commentsCharacterLimit: 128, // Required
    },
    lang: {
      userClosedChatMessageToAgent: '*** USER CLOSED CHAT. ***',
      csatLang: {
        ratingsText: ['Bad', 'Good'], // Required
      },
    },
  }

These options explained further in Step 1 of the Implementation Guide.

Step 2 - Get Web Integration ID

In Postman, navigate to Genius Flow API collection -> Integrations -> Sunshine Conversations -> SunCo Setup

Execute the GET Get Integrations endpoint. In the response, find the integration with "type": "web", copy it's ID and store it somewhere safe.

If you don't have credentials to make the request, you may need to create a new Conversation API key, detailed in Step 3 of the Implementation Guide.

Step 3 - Get Switchboard Integration ID

In Postman, navigate to Genius Flow API collection -> Integrations -> Sunshine Conversations -> SunCo Setup

Execute the GET List Switchboards endpoint, there should only be one switchboard so copy it's ID and paste it in the sunco_switchboard_id Postman environment variable.

Execute the GET Get Switchboard Integrations endpoint, find the integration with "integrationType": "zd:agentWorkspace",, copy it's ID and store it somewhere safe.

Step 4 - Update Agent Handover Object

In Flow, ensure the Agent Handover activity JSON object has the following properties:

{
  "crmPlatform": "sunco",
  "appId": "*******************",
  "integrationId": "*******************",
  "switchboardIntegrationId": "*******************",
  "connectionId": "*******************",
  "tags": "tag1,tag2,tag3",
  "groupId": "*******************"
}

crmPlatform - Set to sunco.

appId - The 'App ID' which can be found in the Zendesk admin center (Apps and Integrations -> APIs -> Conversations API).

integrationId - The ID of the SunCo web integration copied in step 2.

switchboardIntegrationId - The ID of the SunCo zd:agentWorkspace switchboard integration copied in Step 3.

connectionId - The ID of the DigitalGenius 'Sunshine Conversations' connection.

tags (Optional) - A string of comma separated tags.

groupId (Optional) - The ID of the Zendesk group tickets should be assigned to.

Step 5 - Disconnect DigitalGenius Bot

In the Zendesk admin center, navigate to Channels -> Bots -> Manage bots.

Under Marketplace bots, select 'Disconnect' next to the DigitalGenius bot, and again in the following popup.

This removes DigitalGenius from the switchboard and sets the default switchboard integration to zd:answerBot.

If the 'Disconnect' button on the DG bot is disabled, uninstall then reinstall it by following step 2 of the integration guide (the DG bot needs to be installed but not connected).

Step 6 - Configure Zendesk Bot

In the Zendesk admin center, navigate to Channels -> AI agents and automation -> Manage AI agents for messaging.

If you do not have an AI agent configured, click 'Create AI agent' in the top right. Give the AI agent a name and proceed through the steps.

Edit the AI agent and select the 'Behavior' tab, ensure the agent starts with the answer 'Speak to a human'.

Next, we need to configure the 'Speak to a human' answer:

Delete all existing steps and add a 'Ask for details' step, give it a name and add the 'Name' and 'Email' fields.

After the 'Ask for details' step, add the 'Transfer to agent' step, add any relevant tags.

NOTE The required 'Bot message' is visible to the agent, but not the end user.

Save the flow and publish the bot.

Step 7 - Remove CRM Object From Config

Now the migration is complete, you can safely remove the crm object from the chat widget config.