Caller id match (#156)

* Add events for caller id matching * Add caller id match payload * Add debugMessageType argument to logging * Add incomingCall event handler to README * Log last sync event
HubSpot · Nov 14, 2023 · 928f8e2 · 928f8e2
1 parent f69179c
commit 928f8e2
Show file tree

Hide file tree

Showing 5 changed files with 158 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -137,6 +137,12 @@ const options = {
     },
     onUpdateEngagementFailed: event => {
       /* HubSpot has failed to update an engagement for this call. */
+    },
+    onCallerIdMatchSucceeded: event => {
+      /* HubSpot has fetched caller id matches for this call. */
+    },
+    onCallerIdMatchFailed: event => {
+      /* HubSpot has failed to fetch caller id matches for this call. */
     }
     onVisibilityChanged: event => {
       /* Call widget's visibility is changed. */
@@ -217,6 +223,24 @@ extensions.outgoingCall(callInfo);
 </p>
 </details>
 
+<details>
+ <summary>incomingCall</summary>
+ <p>
+
+```ts
+// Sends a message to notify HubSpot that an outgoing call has started.
+
+const callInfo = {
+  fromNumber: string, // Required: The caller's number
+  toNumber: string, // Required: The recipient's number
+  createEngagement: boolean, // Whether HubSpot should create an engagement for this call
+};
+extensions.incomingCall(callInfo);
+```
+
+</p>
+</details>
+
 <details>
  <summary>callAnswered</summary>
  <p>
@@ -408,6 +432,58 @@ onDialNumber(data) {
 </p>
 </details>
 
+<details>
+ <summary>onCallerIdMatchSucceeded</summary>
+ <p>
+
+```js
+  // Message indicating that HubSpot has updated an engagement
+  onCallerIdMatchSucceeded(data) {
+    const {
+      callerIdMatches: (ContactIdMatch | CompanyIdMatch)[];
+    } = data;
+      ...
+  }
+
+  type ObjectCoordinate = {
+    portalId: number;
+    objectTypeId: string;
+    objectId: number;
+  }
+
+  type ContactIdMatch = {
+    callerIdType: 'CONTACT';
+    objectCoordinates: ObjectCoordinate;
+    firstName: string;
+    lastName: string;
+    email: string;
+  }
+
+  type CompanyIdMatch = {
+    callerIdType: 'COMPANY';
+    objectCoordinates: ObjectCoordinate;
+    name: string;
+  }
+```
+</p>
+</details>
+
+<details>
+ <summary>onCallerIdMatchFailed</summary>
+ <p>
+
+```js
+  // Message indicating that HubSpot has failed to update an engagement
+  onCallerIdMatchFailed(data) {
+    const {
+      error: { message: string }
+    } = data;
+      ...
+  }
+```
+</p>
+</details>
+
 <details>
  <summary>onVisibilityChanged</summary>
  <p>

diff --git a/demos/demo-minimal-js/index.js b/demos/demo-minimal-js/index.js
@@ -3,10 +3,12 @@ import { errorType, callEndStatus } from "../../src/Constants";
 // import CallingExtensions, { Constants } from "@hubspot/calling-extensions-sdk";
 // const { errorType, callEndStatus } = Constants;
 
-const state = {
+export const state = {
   engagementId: 0,
-  phoneNumber: "+1234",
+  toNumber: "+1234",
+  fromNumber: "+123456",
   userAvailable: false,
+  incomingContactName: "",
 };
 
 const sizeInfo = {
@@ -53,7 +55,7 @@ const cti = new CallingExtensions({
     },
     onDialNumber: (data, rawEvent) => {
       const { phoneNumber } = data;
-      state.phoneNumber = phoneNumber;
+      state.toNumber = phoneNumber;
     },
     onEngagementCreated: (data, rawEvent) => {
       const { engagementId } = data;
@@ -75,6 +77,32 @@ const cti = new CallingExtensions({
       state.engagementId = engagementId;
     },
     onUpdateEngagementFailed: (data, rawEvent) => {},
+    onCallerIdMatchSucceeded: (data, rawEvent) => {
+      const { callerIdMatches } = data;
+      if (callerIdMatches.length) {
+        const firstCallerIdMatch = callerIdMatches[0];
+        if (firstCallerIdMatch.callerIdType === "CONTACT") {
+          state.incomingContactName = `${firstCallerIdMatch.firstName} ${firstCallerIdMatch.lastName}`;
+        } else if (firstCallerIdMatch.callerIdType === "COMPANY") {
+          state.incomingContactName = firstCallerIdMatch.name;
+        }
+        cti.logDebugMessage({
+          message: `Incoming call from ${state.incomingContactName} ${state.fromNumber}`,
+          type: `${callerIdMatches.length} Caller ID Matches`,
+        });
+        return;
+      }
+      cti.logDebugMessage({
+        message: `Incoming call from ${state.fromNumber}`,
+        type: "No Caller ID Matches",
+      });
+    },
+    onCallerIdMatchFailed: (data, rawEvent) => {
+      cti.logDebugMessage({
+        message: `Incoming call from ${state.fromNumber}`,
+        type: "Caller ID Match Failed",
+      });
+    },
   },
 });
 
@@ -131,9 +159,9 @@ export function userUnavailable() {
 export function incomingCall() {
   window.setTimeout(() => {
     cti.incomingCall({
-      createEngagement: "true",
-      fromNumber: "+123",
-      toNumber: state.phoneNumber,
+      createEngagement: true,
+      fromNumber: state.fromNumber,
+      toNumber: state.toNumber,
     });
   }, 500);
   disableButtons([OUTGOING_CALL, INCOMING_CALL, USER_UNAVAILABLE]);
@@ -143,8 +171,8 @@ export function incomingCall() {
 export function outgoingCall() {
   window.setTimeout(() => {
     cti.outgoingCall({
-      createEngagement: "true",
-      phoneNumber: state.phoneNumber,
+      createEngagement: true,
+      phoneNumber: state.toNumber,
     });
   }, 500);
   disableButtons([OUTGOING_CALL, INCOMING_CALL, USER_UNAVAILABLE]);

diff --git a/src/CallingExtensions.js b/src/CallingExtensions.js
@@ -1,7 +1,9 @@
 "use es6";
 
 import IFrameManager from "./IFrameManager";
-import { messageType, errorType } from "./Constants";
+import { messageType, debugMessageType, errorType, VERSION } from "./Constants";
+
+const prefix = `[calling-extensions-sdk@${VERSION}]`;
 
 /**
  * @typedef {Object} EventHandlers
@@ -129,6 +131,10 @@ class CallingExtensions {
     this.iFrameManager.sendMessage(message);
   }
 
+  logDebugMessage({ message, type = debugMessageType }) {
+    this.iFrameManager.logDebugMessage(prefix, type, message);
+  }
+
   onMessageHandler(event) {
     const { type, data } = event;
     const { eventHandlers } = this.options;
@@ -174,14 +180,24 @@ class CallingExtensions {
         handler = onCreateEngagementFailed;
         break;
       }
+      case messageType.UPDATE_ENGAGEMENT_SUCCEEDED: {
+        const { onUpdateEngagementSucceeded } = eventHandlers;
+        handler = onUpdateEngagementSucceeded;
+        break;
+      }
       case messageType.UPDATE_ENGAGEMENT_FAILED: {
         const { onUpdateEngagementFailed } = eventHandlers;
         handler = onUpdateEngagementFailed;
         break;
       }
-      case messageType.UPDATE_ENGAGEMENT_SUCCEEDED: {
-        const { onUpdateEngagementSucceeded } = eventHandlers;
-        handler = onUpdateEngagementSucceeded;
+      case messageType.CALLER_ID_MATCH_SUCCEEDED: {
+        const { onCallerIdMatchSucceeded } = eventHandlers;
+        handler = onCallerIdMatchSucceeded;
+        break;
+      }
+      case messageType.CALLER_ID_MATCH_FAILED: {
+        const { onCallerIdMatchFailed } = eventHandlers;
+        handler = onCallerIdMatchFailed;
         break;
       }
       default: {

diff --git a/src/Constants.js b/src/Constants.js
@@ -3,6 +3,12 @@
 const { version } = require("../package.json");
 export const VERSION = version;
 
+export const debugMessageType = {
+  FROM_HUBSPOT: "From HubSpot",
+  TO_HUBSPOT: "To HubSpot",
+  GENERIC_MESSAGE: "Generic Message",
+};
+
 export const messageType = {
   CALL_ANSWERED: "CALL_ANSWERED",
   CALL_COMPLETED: "CALL_COMPLETED",
@@ -34,6 +40,8 @@ export const messageType = {
   USER_UNAVAILABLE: "USER_UNAVAILABLE",
   UPDATE_ENGAGEMENT_FAILED: "UPDATE_ENGAGEMENT_FAILED",
   UPDATE_ENGAGEMENT_SUCCEEDED: "UPDATE_ENGAGEMENT_SUCCEEDED",
+  CALLER_ID_MATCH_SUCCEEDED: "CALLER_ID_MATCH_SUCCEEDED",
+  CALLER_ID_MATCH_FAILED: "CALLER_ID_MATCH_FAILED",
   VISIBILITY_CHANGED: "VISIBILITY_CHANGED",
 };
 
@@ -89,3 +97,11 @@ export const callEndStatus = {
   INTERNAL_BUSY,
   INTERNAL_NO_ANSWER,
 };
+
+export const CONTACT = "CONTACT";
+export const COMPANY = "COMPANY";
+
+export const callerIdTypes = {
+  CONTACT,
+  COMPANY,
+};
diff --git a/src/IFrameManager.js b/src/IFrameManager.js
@@ -1,6 +1,6 @@
 "use es6";
 
-import { messageType, VERSION } from "./Constants";
+import { messageType, debugMessageType, VERSION } from "./Constants";
 
 const prefix = `[calling-extensions-sdk@${VERSION}]`;
 /*
@@ -77,9 +77,7 @@ class IFrameManager {
   }
 
   static createIFrame(iFrameOptions, onLoadCallback) {
-    const {
-      src, width, height, hostElementSelector,
-    } = iFrameOptions;
+    const { src, width, height, hostElementSelector } = iFrameOptions;
 
     if (!src || !width || !height || !hostElementSelector) {
       throw new Error(
@@ -152,7 +150,11 @@ class IFrameManager {
     const { type } = message;
     if (type !== messageType.SYNC && !this.isReady) {
       // Do not send a message unless the iFrame is ready to receive.
-      console.warn(prefix, "iFrame not initialized to send a message within HubSpot", message);
+      console.warn(
+        prefix,
+        "iFrame not initialized to send a message within HubSpot",
+        message,
+      );
       return;
     }
 
@@ -170,7 +172,7 @@ class IFrameManager {
       messageId,
     });
 
-    this.logDebugMessage(prefix, "To HubSpot", type, message);
+    this.logDebugMessage(prefix, debugMessageType.TO_HUBSPOT, type, message);
     this.destinationWindow.postMessage(newMessage, this.destinationHost);
   }
 
@@ -191,6 +193,7 @@ class IFrameManager {
 
         const { hostUrl } = event.data;
         this.destinationHost = hostUrl || this.destinationHost;
+        this.logDebugMessage(prefix, debugMessageType.FROM_HUBSPOT, type, data);
         this.sendMessage(message);
         this.onReady();
       }
@@ -214,7 +217,7 @@ class IFrameManager {
       return;
     }
 
-    this.logDebugMessage(prefix, "From HubSpot", type, { data });
+    this.logDebugMessage(prefix, debugMessageType.FROM_HUBSPOT, type, data);
     if (this.instanceRegexp.test(messageId)) {
       // This is a response to some message generated by HubSpot
       const callBack = this.callbacks[messageId];