Calling extensions SDK

cd demos/demo-minimal-js && npm i && npm start

cd demos/demo-react-ts && npm i && npm start

localStorage.setItem('LocalSettings:Calling:installDemoWidget', 'local');

localStorage.setItem('LocalSettings:Calling:installDemoWidget', 'app:js');

localStorage.setItem('LocalSettings:Calling:installDemoWidget', 'app');

npm i --save @hubspot/calling-extensions-sdk

yarn add @hubspot/calling-extensions-sdk

import CallingExtensions from "@hubspot/calling-extensions-sdk";

const options = {
  /** @property {boolean} debugMode - Whether to log various inbound/outbound debug messages to the console. If false, console.debug will be used instead of console.log */
  debugMode: boolean,
  // eventHandlers handle inbound messages
  eventHandlers: {
    onReady: () => {
      /* HubSpot is ready to receive messages. */
    },
    onDialNumber: event => {
      /* HubSpot sends a dial number from the contact */
    },
    onCreateEngagementSucceeded: event => {
      /* HubSpot has created an engagement for this call. */
    }
    onEngagementCreatedFailed: event => {
      /* HubSpot has failed to create an engagement for this call. */
    }
    onUpdateEngagementSucceeded: event => {
      /* HubSpot has updated an engagement for this call. */
    },
    onUpdateEngagementFailed: event => {
      /* HubSpot has failed to update an engagement for this call. */
    }
    onVisibilityChanged: event => {
      /* Call widget's visibility is changed. */
    }
  }
};

const extensions = new CallingExtensions(options);

{
   name: string /* The name of your calling app to display to users. */,
   url: string  /* The URL of your calling app, built with the Calling Extensions SDK */,
   width: number /* The iFrame's width */,
   height: number /* The iFrame's height */,
   isReady: boolean /* Whether the widget is ready for production (defaults to true) */,
   supportsCustomObjects : true /* Whether calls can be placed from a custom object */
}

# Example payload to add the call widget app settings
curl --request POST \
 --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \
 --header 'accept: application/json' \
 --header 'content-type: application/json' \
 --data '{"name":"demo widget","url":"https://mywidget.com/widget","height":600,"width":400,"isReady":false}'

# Note that this endpoint also supports PATCH, GET and DELETE

const myExtensionSettings = {
  isReady: true,
  name: 'My app name',
  url: 'My local/qa/prod URL',
};

localStorage.setItem(
  'LocalSettings:Calling:CallingExtensions',
  JSON.stringify(myExtensionSettings)
);

# Example payload to add the call widget app settings

curl --request PATCH \
 --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \
 --header 'accept: application/json' \
 --header 'content-type: application/json' \
 --data '{"isReady":true}'

const payload = {
  isLoggedIn: boolean,
  engagementId: number,
  isAvailable: boolean,
};

extensions.initialized(payload);

extensions.userAvailable();

extensions.userUnavailable();

// This message is only needed when user isn't logged in when initialized
extensions.userLoggedIn();

extensions.userLoggedOut();

const callInfo = {
  externalCallId: string,
  callStartTime: number,
  createEngagement: boolean,
  fromNumber: string,
  tonumber: string,
};
extensions.incomingCall(callInfo);

const callInfo = {
  phoneNumber: string /** @deprecated Use toNumber instead **/,
  callStartTime: number,
  createEngagement: true,
  toNumber: string,
  fromNumber: string,
  dialingContext: onDialEventPayload,
};
extensions.outgoingCall(callInfo);

const payload = {
  externalCallId: string,
};
extensions.callAnswered();

extensions.callTransferred({
  externalCallId: string
});

// After receiving the call ended event, the user can navigate away, can close the call widget.
extensions.callEnded({
  externalCallId: string,
  engagementId: number,
  callEndStatus: EndStatus,
});

// After receiving the call completed event, HubSpot will
//   1) insert the engagement into the timeline
//   2) set the default associations on the engagement
//   3) closes the widget unless `hideWidget` is set to false.
//   4) update the engagement with any engagement properties
const data = {
  engagementId: number,
  hideWidget: boolean,
  engagementProperties: { [key: string]: string },
  externalCallId: string,
}
extensions.callCompleted(data);

const payload = {
  externalCallId,
  engagementId,
};
extensions.publishToChannel(payload);

const payload = {
  externalCallId,
  engagementId,
};
extensions.finalizeEngagement(payload);

onNavigateToRecord {
    const {
      engagementId: number,
      objectCoordinates: object coordinates
    } = data;
      ...
}

// After receiving the sendError event, HubSpot will display an alert popup to the user with the error message provided.
const data = {
  message: string,
};
extensions.sendError(data);

// After receiving the resizeWidget event, HubSpot will use the provided height and width to resize the call widget.
const data = {
  height: number,
  width: number,
};
extensions.resizeWidget(data);

// Example snippet for handling onReady event
onReady() {
    extensions.initialized(payload);
}

onDialNumber(data) {
  const {
    phoneNumber: string,
    ownerId: number,
    subjectId: number,
    objectId: number,
    objectType: CONTACT | COMPANY,
    portalId: number,
    countryCode: string,
    calleeInfo {
        calleeId: number,
        calleeObjectTypeId: string,
    },
    startTimestamp: number,
    toPhoneNumberSrc: string,
   } = data;
    ...
}

/** @deprecated Use onCreateEngagementSucceeded instead **/
onEngagementCreated(data) {
    const {
      engagementId: number,
    } = data;
      ...
}

onCreateEngagementSucceeded: (event) => {};

onCreateEngagementFailed: (event) => {};

onNavigateToRecordFailed {
    const {
      engagementId: number,
      objectCoordinates: object coordinates
    } = data;
      ...
}

onPublishToChannelSucceeded{
    const {
      engagementId: number,
      externalCallId: string
    } = data;
      ...
}

onPublishToChannelFailed{
    const {
      engagementId: number,
      externalCallId: string
    } = data;
      ...
}

onFinalizeEngagementSucceeded{
    const {
      engagementId: number,
      externalCallId: string
    } = data;
      ...
}

onFinalizeEngagementFailed{
    const {
      engagementId: number,
      externalCallId: string
    } = data;
      ...
}

onCallerIdMatchSucceeded: (event) => {};

onCallerIDMatchFailed: (event) => {};

onVisibilityChanged(data) {
    const { isMinimized, isHidden } = data;
    ...
}

defaultEventHandler(event) {
   console.info("Event received. Do you need to handle it?", event);
}

outgoingCall({ createEngagement: true });

const callInfo = {
  phoneNumber: string, // optional unless call is initiated by the widget
  createEngagement: true // whether HubSpot should create an engagement for this call
  callStartTime: number // optional unless call is initiated by the widget
};
extensions.outgoingCall(callInfo);