> This page is for version Scripted.
> For other versions, use one of these documentation indexes:
> - Generative (default): https://developers.ada.cx/generative/llms.txt
> - Scripted: https://developers.ada.cx/scripted/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.ada.cx/_mcp/server.

# Let chatters interact with your bot using Sunshine Conversations Web Messenger

You can set up your Ada bot 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 example if you want to use more of Zendesk's features.

## Understand chatter experience on Sunshine Conversations Web Messenger\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm457217377790403368371766374]

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

* Chatters can use the same conversation window to exchange messages
  with both your bot and with agents, with seamless handoffs to Zendesk
  Messaging in between.

  You can also enable multi-conversation functionality, so chatters can create more than one conversation at a time, with Sunshine Conversations's [Conversation List](https://docs.smooch.io/guide/web-messenger/#conversation-list) feature.

* Chatters and agents can send files to each other. For information on
  how Sunshine Conversations validates files, see [File Validation](https://docs.smooch.io/guide/validating-files/#file-validation)
  at Sunshine Conversations docs.

* After the chatter 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](https://support.zendesk.com/hc/en-us/articles/4408824482586#topic_ux4_cqq_5pb),
  Zendesk automatically marks the ticket as "closed."

  Until the ticket is marked as "closed," any messages the chatter sends
  go to the agent, not the bot. The chatter has to wait until the ticket
  is closed to be able to send messages to your bot again.

* You can use Ada's multi-bot routing feature. For more information,
  see [Connect Zendesk social channels to multiple bots using Sunshine Conversations](/scripted/docs/integrate-ada-with-other-tools/use-ada-with-zendesk/connect-zendesk-social-channels-to-multiple-bots-using-sunshine-conversations).

### Understand how Ada features work in Sunshine Conversations Web Messenger\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4530232560150433685420495589]

There are some features that you may have built into your Ada bot that
won't translate to Sunshine Conversations Web Messenger.

> **Info**
>
> There are several blocks and features that work differently from Ada's
> default chat in Sunshine Conversations Web Messenger. For additional
> information, see [Feature compatibility](/scripted/docs/integrate-ada-with-other-tools/use-ada-with-social-media-channels#UUID-add4993d-32b7-84c3-56fc-c28cb1d301a9_section-idm43361126183228).

* **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 an
  [HTTP Request block](/scripted/docs/build-and-maintain-your-bot/work-with-blocks-and-apps/make-api-requests-using-the-http-request-block)
  to request data from Sunshine Conversations' API. For more
  information, see [Sunshine Conversations' API documentation](https://docs.smooch.io/rest/).

* **Chatter 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](https://docs.smooch.io/guide/web-messenger/#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](https://docs.smooch.io/guide/web-messenger/#display-style) at
  Sunshine Conversations' documentation.

* **File extensions**: Instead of using the list of accepted file
  extensions in the File Upload block's settings, Sunshine Conversations
  Web Messenger has its own list of extensions it won't accept. For more
  information, see [File Validation](https://docs.smooch.io/guide/validating-files/) at
  Sunshine Conversations' documentation.

## Set up Sunshine Conversations Web Messenger with your bot\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4591275250086433697177676992]

Setting up your bot to work with Sunshine Conversations Web Messenger
requires some work in your bot, 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.

### Before you begin\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4591275282675233697237124075]

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 in your Ada bot. For
  more information, see [Connect Sunshine Conversations with Ada](/scripted/docs/integrate-ada-with-other-tools/use-ada-with-other-chat-handoff-tools/configure-and-use-sunshine-conversations#UUID-7eb532ef-c172-286f-d881-27ac1d51b70a_id_360057424874_id_h_01FAE9RKNBKD57R8Z988FE7NPS).

Additionally, contact your Ada team to make sure your bot 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.

### Get your Zendesk API details and use them to create a new channel\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4542231908828833697256635609]

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](https://www.postman.com/downloads/), installed on your
computer. You may find it helpful to download the [API collection](https://docs.smooch.io/guide/postman-collection/) so you can
see those calls pre-formatted in your client program.

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`

   > **Note**
   >
   > This should be the same key you used to set up your Sunshine
   > Conversations integration. For more information, see [Connect Sunshine Conversations with Ada](/scripted/docs/integrate-ada-with-other-tools/use-ada-with-other-chat-handoff-tools/configure-and-use-sunshine-conversations#UUID-7eb532ef-c172-286f-d881-27ac1d51b70a_id_360057424874_id_h_01FAE9RKNBKD57R8Z988FE7NPS).

   * `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
     }
   }
   ```

### Embed your new integration on your website\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4591275183897633697637839603]

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

> **Tip**
>
> As with all website integrations, we recommend testing this code in a
> staging environment before making it available publicly. That way, if
> you want to troubleshoot or test out improvements, you can do so without
> impacting your chatter experience.

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:

   ```js
   <script>
     !function(o,p,s,e,c){
         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()
     }(window,document,"Smooch","ADD-INTEGRATION-ID-HERE","5");
   </script>
   ```

2. Use the following script to initialize your bot, 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:

   ```js
   Smooch.init({
     integrationId: 'ADD-INTEGRATION-ID-HERE',
     integrationOrder: [],
     notificationChannelPromptEnabled: false,
     canUserSeeConversationList: false
     }).then( function() {
       // Your code after init is complete
     }, function(err) {
       // Something went wrong during initialization
     }
   );
   ```

   > **Info**
   >
   > 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
   bot. 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 bot is loading but not responding to your messages, feel free to
contact your Ada team for assistance.

#### Customize your bot's appearance\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4596162271740833698964294288]

After making sure your bot 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](https://github.com/zendesk/sunshine-conversations-web#individual-functions)
documentation, but the most common ones you may be interested in are:

* `businessName` - The bot'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

  > **Note**
  >
  > This image only appears at the top of the chat window. It's not the
  > bot avatar, which you can change in your Ada settings. For more
  > information, see [Customize the chat window](/scripted/docs/build-and-maintain-your-bot/change-your-bot-s-look-and-feel/customize-the-chat-window).

* `customColors` - Branding colors that you can apply to your bot. 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 chatter's chat bubbles, and
    quick reply bubbles that they can select

  * `actionColor` - The color that highlights actions that chatters can
    take, like the outline of the field where the chatters can type in
    messages to the bot

All of the above customizations go into the [initializing code snippet](/scripted/docs/integrate-ada-with-other-tools/use-ada-with-zendesk/let-chatters-interact-with-your-bot-using-sunshine-conversations-web-messenger#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4591275183897633697637839603)
above. Here's an example of a completed snippet with all of the above
attributes populated:

```js
Smooch.init({
  // Default bot settings
  integrationId: 'ADD-INTEGRATION-ID-HERE',
  integrationOrder: [],
  notificationChannelPromptEnabled: false,
  canUserSeeConversationList: false,
  // Bot customizations
  businessName: 'My chatbot',
  businessIconUrl: 'https://media.smooch.io/5f19b4c836ced4000c3a7dc3/icons/8f539f6284ca2f79cda7b0bda0b98cc3.jpg',
  customColors: {
    brandColor: '944dff', // Purple
    conversationColor: '4ddbff', // Cyan
    actionColor: 'ff4da6', // Hot pink
  },
  }).then( function() {
    // Your code after init is complete
  }, function(err) {
    // Something went wrong during initialization
  }
);
```

> **Tip**
>
> The more attributes you have for your bot, the more difficult it can get
> to remember which is which. In the above sample, we have
> `// commented-out content`, where the script ignores everything between
> the double slashes and the end of the line. Using these comments can be
> really helpful for troubleshooting and maintaining your bot over time.

### Set up handoffs via the HTTP Request block\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4623586158470433700712413348]

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.

1. On the Ada dashboard, go to **Build** > **Answers**, and create or
   open an Answer you want to put a handoff into.

2. Click and drag an [HTTP Request block](/scripted/docs/build-and-maintain-your-bot/work-with-blocks-and-apps/make-api-requests-using-the-http-request-block)
   into the end of that Answer.

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](/scripted/docs/integrate-ada-with-other-tools/use-ada-with-zendesk/let-chatters-interact-with-your-bot-using-sunshine-conversations-web-messenger#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4542231908828833697256635609).
   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** ![](/_fern-files/_img/870c03074294e150ef7a4a24aac3d6015af4a9ef6897ae0a5983407873484ce5.webp) to
   add a row under the metadata attribute.

   This attribute tells Sunshine Conversations which was the first
   message in the chatter's most recent interaction with your bot. 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](https://docs.smooch.io/guide/switchboard/#metadata-sent-to-zendesk).
   For example, if you want to attach tags to the tickets you create
   through your bot:

   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_bot, automatic_handoff`).

9. Choose an Answer to display if there's an issue completing the API
   call.

10. Turn on the **Count as Handoff** toggle.

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

Here's an example of a completed HTTP Request block handoff:

![](/_fern-files/_img/360c3725b7574fc8aa86fa4a44186bc95c46ffa219b9434d659511db9a467a77.webp)

### Connect your bot with Zendesk\[#UUID-324a044a-4f30-05be-1b9d-82ab7a35eadc_section-idm4573960579355233700803053224]

Lastly, to allow your bot to start interacting with chatters, you have
to connect your bot with Zendesk. For more information, see [Connect your bot with Zendesk Admin Center](/scripted/docs/integrate-ada-with-other-tools/use-ada-with-zendesk/configure-and-use-ada-glass-for-zendesk-messaging#UUID-98fb0e96-9b92-a864-b73a-d631766a608b_section-idm43400010489800).

---

Have any questions? Contact your Ada team, or email us at [](<mailto:help@ada.support%20%E2%80%9CHelp Docs inquiry%E2%80%9D>).