Agent-initiated conversations (ZSC)

Agent-initiated conversations from Zendesk Support to Zendesk Sunshine Conversations (ZSC)

πŸ“˜

This is an advanced use-case specific to Zendesk Support and Zendesk Sunshine Conversations (ZSC) when you want to start an in-app support conversation starting from the agent (i.e. a proactive message).

Client authentication using email address

For this use-case, you need to ensure that the ZSC client is authenticated use the user's email address.

This is a rough example for the ZSC web client, but the same concept would apply to ZSC mobile SDK. This ensures that ZSC has initialized this user on this device.

Note lines 6 to 9 and line 18.

<html lang="en">
<head>
    <title>TEST BOT</title>
    <meta charset="utf-8"/>
    <script>
        var integrationId = "xxx";
        var externalId = "[email protected]";
        // https://docs.smooch.io/guide/jwt/
        var jwt = "generate this token server side";

        !function(e,n,t,r){
            function o(){try{var e;if((e="string"==typeof this.response?JSON.parse(this.response):this.response).url){var t=n.getElementsByTagName("script")[0],r=n.createElement("script");r.async=!0,r.src=e.url,t.parentNode.insertBefore(r,t)}}catch(e){}}var s,p,a,i=[],c=[];e[t]={init:function(){s=arguments;var e={then:function(n){return c.push({type:"t",next:n}),e},catch:function(n){return c.push({type:"c",next:n}),e}};return e},on:function(){i.push(arguments)},render:function(){p=arguments},destroy:function(){a=arguments}},e.__onWebMessengerHostReady__=function(n){if(delete e.__onWebMessengerHostReady__,e[t]=n,s)for(var r=n.init.apply(n,s),o=0;o<c.length;o++){var u=c[o];r="t"===u.type?r.then(u.next):r.catch(u.next)}p&&n.render.apply(n,p),a&&n.destroy.apply(n,a);for(o=0;o<i.length;o++)n.on.apply(n,i[o])};var u=new XMLHttpRequest;u.addEventListener("load",o),u.open("GET","https://"+r+".webloader.smooch.io/",!0),u.responseType="json",u.send()
        }(window,document,"Smooch",integrationId);
    </script>
</head>
<body>
    <script>
        Smooch.init({ integrationId: integrationId, userId: externalId, jwt: jwt });
    </script>
</body>
</html>

Add the unhandled ticket flow

πŸ“˜

You do not need to modify the contents of this file, but it may be useful to understand the pattern for other use-cases. This flow will link the user:

Zendesk Sunshine Conversations <-> Meya <-> Zendesk Support

Paste this BFML flow file exactly as written in your flow folder.

triggers:
  - type: meya.zendesk.support.trigger.ticket.unhandled

steps:
  # Try to find the ZDS Meya user link
  - user_try_lookup: (@ flow.requester.id | string )
    integration: integration.zendesk.support
  - flow_set: user_id
  - if: (@ flow.user_id )
    then: next
    else:
      jump: sunco_find_by_email

  # Try to find the SunCo Meya user link
  - type: user_try_reverse_lookup
    user_id: (@ flow.user_id )
    integration: integration.zendesk.sunshine_conversations
  - flow_set: sunco_app_user_id
  - if: (@ flow.sunco_app_user_id )
    then:
      jump: sunco_user_ready
    else: next

  # Try to find the SunCo user via ZDS email (require a result)
  - (sunco_find_by_email)
  - type: meya.zendesk.sunshine_conversations.component.app_user.get
    integration: integration.zendesk.sunshine_conversations
    external_id: (@ flow.requester.email )
  - flow_set:
      sunco_app_user_id: (@ flow.result.user_id or flow.result._id )

  # Identify the SunCo Meya user
  - user_identify: (@ flow.sunco_app_user_id )
    integration: integration.zendesk.sunshine_conversations
  - flow_set: user_id

  # Link the Meya user to ZDS
  - user_link: (@ flow.requester.id | string )
    user_id: (@ flow.user_id )
    integration: integration.zendesk.support

  # Try to find the SunCo Meya thread link
  - (sunco_user_ready)
  - thread_try_lookup: (@ flow.sunco_app_user_id )
    integration: integration.zendesk.sunshine_conversations
  - if: (@ flow.result )
    then: next
    else:
      jump: sunco_thread_link

  # Use the existing SunCo Meya thread
  - flow_set: thread_id
  - jump: sunco_thread_ready

  # Link the new Meya thread to SunCo
  - (sunco_thread_link)
  - flow_set:
      thread_id: (@ thread.id )
  - thread_link: (@ flow.sunco_app_user_id )
    thread_id: (@ flow.thread_id )
    integration: integration.zendesk.sunshine_conversations

  # Set the new thread primary user
  - thread_set:
      primary_user_id: (@ flow.user_id )
    thread_id: (@ flow.thread_id )

  # Link the Meya thread to ZDS
  - (sunco_thread_ready)
  - thread_link: (@ flow.ticket.id | string )
    thread_id: (@ flow.thread_id )
    integration: integration.zendesk.support

  # Redo ZDS RX
  - type: meya.zendesk.support.component.ticket.rx
    integration: integration.zendesk.support
    thread_id: (@ flow.thread_id )
    ticket: (@ flow.ticket )
    current_user: (@ flow.current_user )

Update your Zendesk Support integration settings

You need to enable the support for β€œunhandled” tickets. Those are Zendesk Support tickets that are not linked to any users in Meya (yet). See this example code.

You can specify alternate value for ticket.tags other than sunco_send in order to trigger the unhandled flow based on your agent workflow.

type: meya.zendesk.support.integration
subdomain: (@ vault.zendesk.support.subdomain )
bot_agent_email: (@ vault.zendesk.support.bot_agent_email )
bot_agent_api_token: (@ vault.zendesk.support.bot_agent_api_token )
target_password: (@ vault.zendesk.support.target_password )
markdown: true
extract_html_links: false
unlink_ticket_status: [closed, solved]
include_text_with_media: true
filter:
  rx_unhandled_ticket: >
    ticket.tags:sunco_send
    AND ticket.status:(new OR open OR pending)
    AND current_user.role:(NOT end-user)

Creating an agent-initiated ticket

  1. Create/select the user you want to initiate a conversation with using their email address.
  2. Click the + New Ticket button.
  3. Important: add the sunco_send tag. (If you don't add the tag then the Meya integration will ignore the ticket webhook.)
  4. Specify a Subject. (This is ignored in ZSC.)
  5. Type a message.
1467