Set up a CRM Configuration for HubSpot

This is the first step of integrating HubSpot with CXone Agent for Microsoft Teams.

This page explains how to set up a CRM configuration for HubSpot. This is done in CXone. The configuration connects HubSpot to CXone Agent for Microsoft Teams. It allows the two to share data through data memorialization and dynamic data mapping.

Complete each of these tasks in the order given.

Create a New CRM Configuration in CXone

Required permissions: Configurations Create

Provide CXone with the information it needs to connect to HubSpot.

If the HubSpot user account that created the CRM configuration is deleted or disabled, the CRM configuration will also be deleted. Prevent this by creating a user account in HubSpot specifically for CXone configuration. This is the system user. It is recommended to give the system user administrator privileges. If you do not want to give the system user administrator privileges, you must give it:

  • Read access to all HubSpot entity records and entity fields.

  • Read/Write access to all HubSpot entity records that will be accessed or updated in the workflows you've configured, including Search workflows, Create workflows, and data memorialization.

  1. In CXone, click the app selector and select Agent Integrations icon: an orange gear with three arrows inside..
  2. Click New CRM Configuration.
  3. Select HubSpot from the Integration Type drop-down.
    The Create New Integration page in Agent Integrations, with fields for Integration Type, Configuration Name, and Description.
  4. Enter a name for the integration in Configuration Name. You can write a Description.
  5. Click Authenticate.
  6. In the Authentication pop-up window, select one of the authenticated accounts listed, if you have them. If you need to create a new authentication, click New authentication and configure the fields that appear:
    1. To change the name of the authentication, edit Your authentication name.
    2. To enable yourself to manage the settings for this integration inside HubSpot, enter your Developer API key. To find it, open your HubSpot developer account and navigate to the Applications dashboard. Click Get HubSpot API key at the top. In the pop-up window that appears, click Show key. Copy and paste the key into the Developer API key field.
    3. Enter your Private app access token. To find it, open HubSpot and navigate to the private app Box with arrow indicating navigation to external site. you created for CXone Agent for Microsoft Teams. On the details page of that app, click Show token. Copy and paste the token into the Private app access token field.
    4. Click Create. If a window from HubSpot appears asking to allow NICE to connect to your HubSpot account, click Allow.
  7. Click Next.
  8. In the external_screenpop_domain_hs field, enter your HubSpot subdomain. To find it, open your instance of HubSpot and copy and paste the URL from the address bar in your browser. You only need the URL up until .com. For example: https://ven12345.hubspot.com.
  9. In the account_id field, enter your Hub ID. It must be the Hub ID for an administrator account.
  10. Click Finish. A message telling you the authentication is active appears in the bottom right corner.
  11. Click Save in the top right corner of Agent Integrations.

Create Data Memorialization Mappings

Required permissions: Configurations Edit; Data Memorialization Create

Data memorialization mappings allow for data from CXone Agent for Microsoft Teams to be popped into HubSpot records. In these mappings, you select the CXone data field to map to each HubSpot record field. For example, if you map the Customer Name CXone data field to the Name HubSpot record field, Name displays the value from Customer Name. Only text is mapped; attachments, images, and notes cannot be mapped. Currently, you can set up data mappings for standard CRM entity types.

For voice interactions, data memorialization happens when the call ends and the agent completes ACWClosed State that allows an agent to complete work requirements after finishing an interaction time, if configured. For digitalClosed Any channel, contact, or skill associated with Digital Experience. interactions, it happens when the agent transfers the interaction or unassigns it from themselves.

  1. If you haven't already, open a CRM configuration for HubSpot. In CXone, click the app selector and select Agent Integrations icon: an orange gear with three arrows inside.. Select a CRM configuration from the list.
  2. Click the Data Memorialization tab.
  3. Click New Data Mapping.
  4. Enter a Name for the mapping. You can optionally enter a Description.

  5. In the Select Entity Type drop-down, select the HubSpot record type you want to create field mappings for.

    The Data Mapping tab on the Configurations page in CXone, with fields for Name, Description, and Select Entity Type, as well as a + Add Entity button.
  6. Click Add Entity.

  7. In the External CRM Field drop-down that appears, select the HubSpot record field you want to receive data from CXone Agent for Microsoft Teams.

    If you want to map the full transcript of an interaction, select a record field with proper formatting and a large enough character limit. If the field doesn't meet these requirements, only part or none of the transcript is displayed, depending on the CRM.

    The Data Mapping tab, showing a box for a Case entity type and an Account entity type. Each has fields for External CRM, Select Channel, and CXone data field.

  8. In the Select Channel drop-down, select the type of CXone data you want to map to the HubSpot record field you selected.

    Field Value

    Details
    Digital Contact Enables you to select a Digital Experience data field to map.
    Script Variable

    Enables you to input a script variable for a data field. Select this option if you want to map a data field other than the preset Digital Experience and ACD data fields. The script variable should be in lowercase to match the ASSIGN action in the Studio script for the skill.

    If you select this option to use for voice interactions, you must enable screen popsClosed A configurable pop-up window with information about the contact. It appears on an agent's screen after a certain event, usually when the agent connects to a contact. for the skillClosed Used to automate delivery of interactions based on agent skills, abilities, and knowledge and the ASSIGN action in the Studio script:

    • Go to ACD > Contact Settings > ACD Skills and select the voice skill. In the Details tab, click Edit. Then select the checkbox for Use Screen Pops.

    • Open the Studio script for the voice skill. In the ASSIGN action's input properties, set the ScreenPop property to True.
    Voice Call Contact Enables you to select an ACD data field to map.

  9. In the CXone Data drop-down, select the CXone data field you want to map to the HubSpot record field you selected.

    If you selected Script Variable in the Select Channel drop-down, enter the script variable in the CXone Data field. You must enter it in lowercase, even if you used camel case in the script to define the variable.

    Mapping to any other CXone data field requires using a script variable.

    Digital Contact (Digital Experience) Data Fields

    Agent ID

    The user's CXone employee ID.
    Agent Name The agent's name in CXone.
    Channel Name The type of digital channel, such as chat, email, or Facebook Messenger.
    Channel Type The type of digital channel, such as chat, email, or Facebook Messenger.
    Contact ID The contact's unique ID number from CXone.
    Customer Name The contact's name from the customer card.
    Direction The interaction's direction: inbound, outbound, or internal.
    Disposition Name The dispositionClosed Result assigned by the agent or system at the end of a voice (disposition) or digital (status) interaction. the agent selected in the Outcomes window.
    Disposition Notes The notes the agent added in the Outcomes window.
    End Time The date and time the interaction was closed.
    Event Type The type of interaction: voice, digital, voicemail, or work item.
    Final State If the interaction has ended: true or false.
    From The contact's name from the customer card.
    Interaction ID The interaction's unique ID number from CXone.
    Media Type The type of media: voice, digital, voicemail, or work item.
    Skill ID The skill's unique ID number from CXone.
    Skill Name The skill's name in CXone.
    Start Time The date and time the interaction began.
    Status The statusClosed Result assigned by the agent or system at the end of a voice (disposition) or digital (status) interaction. the agent selected in the Outcomes window.
    To The agent who handled the interaction.
    Transcription Text The transcript of the digital interaction.
    Transcript URL The URL where the digital transcription is located.

    Voice call Contact (ACD) Data Fields

    Agent ID

    The user's CXone employee ID.
    Agent Name The agent's name in CXone.
    ANI The contact's phone number.
    Contact ID The contact's unique ID number from CXone.
    Contact Type The type of interaction: voice or digital.
    Direction The interaction's direction: inbound, outbound, or internal.
    Disposition Name The dispositionClosed Result assigned by the agent or system at the end of a voice (disposition) or digital (status) interaction. the agent selected in the Outcomes window.
    Disposition Notes The notes the agent added in the Outcomes window.
    DNIS The agent's phone number.
    End Time The date and time the interaction was closed.
    Final State If the interaction has ended: true or false.
    Interaction ID The interaction's unique ID number from CXone.
    Master Contact ID The master or parent ID number for the contact.
    Media Type The type of media: voice, digital, voicemail, or work item.
    Recording URL The URL where the recording is located.
    Skill ID The skill's unique ID number from CXone.
    Skill Name The skill's name in CXone.
    Start Time The date and time the interaction began.
    Status The statusClosed Result assigned by the agent or system at the end of a voice (disposition) or digital (status) interaction. the agent selected in the Outcomes window.
    To The agent who handled the interaction.
    Tags The tags applied to the interaction.

  10. To add more data fields, click Add Field.
  11. To configure mappings for another HubSpot record type, select a different record type from the Select Entity Type drop-down and click Add Entity.
  12. Click Save at the top of the page. The active data mapping appears in the Data Memorialization tab.

Create Dynamic Data Mapping Mappings

Required permissions: Configurations Edit; Dynamic Data Create

Dynamic data mappings allow you to choose which HubSpot record fields appear in CXone Agent for Microsoft Teams. You can set up dynamic data mappings for standard HubSpot record types retrieved by search workflows. You can also set them up for custom records created by custom create workflows. You can add up to five fields per record type.

In the Current Interaction and Related Interactions sections, records with four fields are displayed.
  1. If you haven't already, open a CRM configuration for HubSpot. In CXone, click the app selector and select Agent Integrations icon: an orange gear with three arrows inside.. Select a CRM configuration from the list.
  2. Click the Dynamic Data tab.
  3. Click New Data Mapping.
  4. Enter a Name for the mapping. You can optionally enter a Description.

  5. In the Select Entity Type drop-down, select the HubSpot record type with the fields you want to display in CXone Agent for Microsoft Teams.

    The Dynamic Data tab in CXone. Shows fields for Name, Description, and Select Entity Type.
  6. Click Add Entity.

  7. In the External CRM Field drop-down that appears, select the HubSpot record field you want to display to agents.

    Under each entity you selected, there are drop-downs for External CRM Field, where you select the CRM record field you want to display to agents.
  8. To add more HubSpot record fields, click Add Field. You can add up to five fields per record type.
  9. Click Save at the top of the page. The active dynamic data mapping appears in the Dynamic Data tab.

The next step of integrating HubSpot with CXone Agent for Microsoft Teams is to modify your Studio script.