HubSpot Custom CRM Card UI Extension Tutorial

This is an example on using HubSpot CRM custom card feature to extend the UI using Serverless functionality.

Use Case Example & Sample Output

Help sales rep to easily get access to additional data insights about deals on a specific record with the Serverless functionality. This use case can be for both B2C and B2B industries in which reps can get insights like annual revenue for a specific record, number of currently on going deals, number of closed deals...etc. This tutorial starts by using the default boilerplate that HubSpot provides so we can then customize it to fit the needs of this use case.

Tutorial Steps

1. Prerequisite - Setup Local Environment

1.1. Install Node.js which enables HubSpot’s local development tools.

1.2. Install any code editor like Visual Studio.

1.3. Install the HubSpot CLI by running npm install -g @hubspot/cli@next in the terminal.

1.4. In the terminal navigate to the directory where you'll be working.

1.5. Run the command hs init.

1.6. Press Enter to open the personal access key page in your browser.

1.7. Select the account that you want to deploy to, then click Continue with this account. You’ll then be redirected to the personal access key page of the account.

1.8. Make sure to select the sandbox option.

1.9. Click Show to reveal your key. Then click Copy to copy it to your clipboard.

1.10. Paste the copied key into terminal, then press Enter.

1.11. Enter a unique name for the account, which is only used when running CLI commands. Then, press Enter.

1.12. Set this as your default account then press Enter.

2. Create and Upload a Local Project

2.1. Make sure you are in the environment in which you ran the hs init command during the previous phase.

2.2. Create a folder like "MyProjects" and navigate to it in the terminal.

2.3. In the terminal run hs project create.

2.4. Enter a name for the project, then press Enter.

2.5. Set the location for the project: Leave it as it is, the default one so just press Enter.

2.6. Select to start the project from the Getting Started template.

2.7. In the terminal, run hs project upload.

2.8. Go to: HubSpot Account > Developer Tab > Private Apps. You'll the see app there.

2.9. Click on any Contact record and you'll see the custom CRM card on the right side.

3. Convert CRM card to Custom Tab Card

Update Card Configuration

3.1. Go to app.json file and include "version":2.

"extensions": {
    "crm": {
        "cards": [
            {
              "file": "./crm-card.json",
              "version": 2
            }
        ]
     }
   }

3.2. Go to crm-card.json file and replace the code with the following:

// crm-card.json
{
  "type": "crm-card",
  "version": 2,
  "data": {
    "title": "Loom CRM Card",
    "fetch": {
      "targetFunction": "crm-card",
      "objectTypes": [
        {
          "name": "contacts",
          "propertiesToSend": [], 
          "actions":[]
        }
      ]
    },
    "display": {
      "properties": []
    },
    "actions": {
      "baseUrls": []
    }
  }
}

Update CRM Card Function

3.3. Go to crm-card.js and replace the code with the followng:

// crm-card.js
const axios = require("axios");

exports.main = async (context = {}, sendResponse) => {

  try {
    const { data } = await axios.get("https://zenquotes.io/api/random");
    sendResponse({
      sections: [
        {
          "type": "text",
          "format": "markdown",
          "text": "[Inspirational quotes provided by ZenQuotes API](https://zenquotes.io)" 
        },
        {
          "type": "text",
          "format": "markdown",
          "text": `**Quote**: ${data[0].q}` 
        },
        {
          "type": "text",
          "format": "markdown",
          "text": `**Author**: ${data[0].a}`
        },
        {
          "type": "button",
          "text": "Get Inspired",
          "onClick": {
            "type": "SERVERLESS_ACTION_HOOK",
             "serverlessFunction": "crm-card"
          } 
        },
    ],
    });
  } catch (error) {
    throw new Error(`There was an error fetching the quote': ${error.message}`);
  }
};

3.4. Save all the changes -make sure to click on Save All- and run hs project upload.

3.5. Go back to the Contact record in your portal and click on the Custom tab.

4. Create a More Advanced Custom CRM Card

4.1. Go to app.json and add "crm.objects.deals.read" and "crm.objects.deals.write" in scopes (for this example we will mainly be focusing on the deal object but feel free to and any additional scopes). You can copy & paste the app.json file that exists in this repo.

"scopes": [
    "crm.objects.contacts.read",
    "crm.objects.contacts.write",
    "crm.objects.deals.read",
    "crm.objects.deals.write",
  ]

4.2. Go to crm-card.json and add hs_object_id in propertiesToSend under objectTypes. This would make the content of our CRM card dynamic: every time we click on a contact record the crm card will get its ID so we can use it later on in API requests to fetch deals for this coressponding contact. You can copy & paste the crm-card.json file that exists in this repo.

"objectTypes": [
        {
          "name": "contacts",
          "propertiesToSend": ["hs_object_id"],
          "actions":[]
        }
      ]

4.3. Grab the code from this crm-card.js in this repo and paste it in your crm-card.js. Basically this code gets the number of closed deals of a specific contact, calculates the amount of closed deals, gets the number of ongoing deals and displays them on the card. In addition it has a label that changes dynamically based on the closed deals amount. For example if this amount is above a specific value then it shows that this is a High Value Customer label and displays the VIP image.

4.4. Go to: HubSpot Account > Developer Tab > Private Apps and click on View access token to get the token of this private app.

4.5. Paste the token in the code where it says "INSERT TOKEN HERE".

4.6. Save all the changes -make sure to click on Save All- and run hs project upload.

kif01/HubSpot-UI-Extension-Demo