chat-core-zendesk: add support for ticketFields (#51)

Adds support for the new ticketFields param on the ZendeskHandoff
returned from the Chat API. This allows fields specified in the bot
config to autopopulate in arbitrary custom Zendesk fields.

TEST=manual,auto

Ran test site locally, using a bot with a field's ID set in the
ticketFields. Initiated a support session, saw the field populated
with the specified value.

Wrote a unit test validating that the parameters are used and
formatted correctly, saw it pass.

packages/chat-core-aws-connect/THIRD-PARTY-NOTICES

@@ -195,7 +195,7 @@ The following NPM packages may be included in this product:
  - @types/istanbul-lib-report@3.0.3
  - @types/istanbul-reports@3.0.4
  - @types/jsdom@20.0.1
- - @types/node@22.5.4
+ - @types/node@22.5.5
  - @types/stack-utils@2.0.3
  - @types/tough-cookie@4.0.5
  - @types/yargs-parser@21.0.3

packages/chat-core-zendesk/README.md

@@ -2,7 +2,7 @@
 
 A library used for integrating Yext Chat with the Zendesk agent platform.
 
-This is an internal package as of now. 
+This is an internal package as of now.
 
 - 100% **TypeScript**, with detailed request and response models
 - Currently only supports browser-based chat sessions

packages/chat-core-zendesk/src/infra/ChatCoreZendeskImpl.ts

@@ -89,8 +89,23 @@ export class ChatCoreZendeskImpl {
    * with the conversation summary as the initial message.
    */
   private async setupSession(messageRsp: MessageResponse) {
+    const ticketFields: Record<string, unknown> = {};
+    try {
+      if (messageRsp.integrationDetails?.zendeskHandoff?.ticketFields) {
+        const rawFields = JSON.parse(
+          messageRsp.integrationDetails?.zendeskHandoff?.ticketFields
+        );
+        for (const key in rawFields) {
+          ticketFields[`zen:ticket_field:${key}`] = rawFields[key];
+        }
+      }
+    } catch (e) {
+      console.error("Error parsing metadata", e);
+    }
+
     let convo: Conversation = await Smooch.createConversation({
       metadata: {
+        ...ticketFields,
         "zen:ticket:tags": "yext-chat-agent-handoff",
         // this indicates to the internal zendesk bot webhook that the conversation is from the Chat SDK
         [MetadataChatSDKKey]: true,
@@ -99,7 +114,7 @@ export class ChatCoreZendeskImpl {
 
     // On first conversation creation of a new user, the id is TEMPORARY_CONVERSATION.
     // We need to re-fetch the current conversation to get the actual id.
-    if (convo.id === 'TEMPORARY_CONVERSATION') {
+    if (convo.id === "TEMPORARY_CONVERSATION") {
       const currentConversation = Smooch.getDisplayedConversation();
       if (!currentConversation) {
         throw new Error("No conversation found");
@@ -109,8 +124,10 @@ export class ChatCoreZendeskImpl {
     this.conversationId = convo.id;
     Smooch.loadConversation(convo.id);
     Smooch.sendMessage(
-      `SUMMARY: ${messageRsp.notes.conversationSummary}` ??
-        "User requested agent assistance",
+      `SUMMARY: ${
+        messageRsp.notes.conversationSummary ??
+        "User requested agent assistance"
+      }`,
       this.conversationId
     );
   }
@@ -123,14 +140,15 @@ export class ChatCoreZendeskImpl {
           return;
         }
         let msg: string = message.text;
-        
+
         // If the message is of type CSAT, indicating the agent has resolved the ticket, then omit this message.
         // Instead, send a message to inform user and reset the session
         // @ts-ignore - metadata is not in the Smooch types but it's in the actual data
         if (message["metadata"]?.type === "csat") {
           this.resetSession();
           this.eventListeners["close"]?.forEach((cb) => cb(data));
-          msg = "The agent has resolved the ticket. Further assistance will now be provided by the bot.";
+          msg =
+            "The agent has resolved the ticket. Further assistance will now be provided by the bot.";
         }
 
         // If the message is from a bot, indicating the agent has deleted the ticket, then reset the session

packages/chat-core-zendesk/tests/ChatCoreZendesk.test.ts

@@ -13,9 +13,11 @@ function mockMessageResponse(): MessageResponse {
       text: "text",
     },
     integrationDetails: {
-      zendeskHandoff: {},
+      zendeskHandoff: {
+        ticketFields: '{"field1": "value1", "field2": "value2"}',
+      },
     },
-  }
+  };
 }
 
 const mockConfig: ChatCoreZendeskConfig = {
@@ -222,3 +224,17 @@ it("clears session on resetSession", async () => {
   chatCoreZendesk.resetSession();
   expect(chatCoreZendesk.getSession()).toBeUndefined();
 });
+
+it("sets ticket fields on handoff", async () => {
+  const createConversationSpy = jest.spyOn(SmoochLib, "createConversation");
+  const chatCoreZendesk = provideChatCoreZendesk(mockConfig);
+  await chatCoreZendesk.init(mockMessageResponse());
+  expect(createConversationSpy).toBeCalledWith({
+    metadata: {
+      "zen:ticket_field:field1": "value1",
+      "zen:ticket_field:field2": "value2",
+      "zen:ticket:tags": "yext-chat-agent-handoff",
+      YEXT_CHAT_SDK: true,
+    },
+  });
+});

packages/chat-core/docs/chat-core.zendeskhandoff.md

@@ -11,3 +11,10 @@ Configurations for Zendesk handoff.
 ```typescript
 export interface ZendeskHandoff 
 ```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [ticketFields?](./chat-core.zendeskhandoff.ticketfields.md) |  | string | _(Optional)_ A serialized JSON string of ticket fields to be automatically set when initiating Zendesk handoff. |
+

packages/chat-core/docs/chat-core.zendeskhandoff.ticketfields.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/chat-core](./chat-core.md) &gt; [ZendeskHandoff](./chat-core.zendeskhandoff.md) &gt; [ticketFields](./chat-core.zendeskhandoff.ticketfields.md)
+
+## ZendeskHandoff.ticketFields property
+
+A serialized JSON string of ticket fields to be automatically set when initiating Zendesk handoff.
+
+**Signature:**
+
+```typescript
+ticketFields?: string;
+```

packages/chat-core/etc/chat-core.api.md

@@ -197,6 +197,7 @@ export interface TokenStreamEvent {
 
 // @public
 export interface ZendeskHandoff {
+    ticketFields?: string;
 }
 
 // (No @packageDocumentation comment for this package)

packages/chat-core/src/models/integrations/Zendesk.ts

@@ -3,5 +3,10 @@
  *
  * @public
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface ZendeskHandoff {}
+export interface ZendeskHandoff {
+  /**
+   * A serialized JSON string of ticket fields to be automatically set
+   * when initiating Zendesk handoff.
+   */
+  ticketFields?: string;
+}

test-sites/test-browser-esm/README.md

@@ -18,4 +18,5 @@ This will serve the index.html page on http://localhost:5050. Opening that up sh
 ### Chat Core Integrations
 
 #### Zendesk
-To test Zendesk integration, ensures that the bot is configured with Zendesk handoff goal and provided appropriate credentials. In the `.env` file, provide the value for `TEST_ZENDESK_INTEGRATION_ID`. The test site should switch to use ChatCoreZendesk instance if it detects a zendesk-specific handoff step.
+
+To test Zendesk integration, ensures that the bot is configured with Zendesk handoff goal and provided appropriate credentials. In the `.env` file, provide the value for `TEST_ZENDESK_INTEGRATION_ID`. The test site should switch to use ChatCoreZendesk instance if it detects a zendesk-specific handoff step.