How to register leads in HubSpot

Index:

1. How Lead Registration Works
2. Requirements
3. Setting up your bot to register the lead
4. Saving user responses into a variable
5. Defining the contact
6. HTTP request action to the HubSpot API
7. Final Considerations
8. Lead registration in HubSpot
9. Validating lead registration
10. Contact properties
11. Custom properties
12. Existing properties in HubSpot

 

HubSpot is an extremely comprehensive CRM tool that integrates marketing and sales teams as a whole. Working with a bot integrated with HubSpot can greatly enhance company sales results.

 

How Lead Registration Works

Every user who interacts with the bot has an associated contact variable that can be used to save important information gathered during the conversational flow. Once this information is available in this variable, it's possible to create and/or update the lead (contact) in HubSpot.

In the current version of the integration, it's possible to register leads in one or more distinct HubSpot accounts (which is an improvement from the previous version that only allowed integration with a single account) from one or more bots. The step-by-step process to define this will be better explained in the integration setup section.

 

Requirements

Before attempting to register a lead in HubSpot, it's necessary that the HubSpot integration plugin has already been installed in your bot.

If you haven't done this yet, learn How to install the HubSpot integration app

 

Setting up your bot to register the lead

As previously discussed, customer information saved in the Blip contact will be used to register the lead in HubSpot. Therefore, it's necessary to ensure that all information (that you wish to integrate with HubSpot) from your customer is properly asked and saved throughout the conversation flow, to subsequently save it in the contact.

 

 

Another important point to keep in mind is that upon registering each contact in HubSpot, it will have a property called hubSpotContactId in its extras. This property holds vital information about the contact in HubSpot. Therefore, never delete this property.

 

Saving user responses into a variable

Whenever there is a possibility of user response and there is a desire to save this data in HubSpot, it's necessary to first save the user's input into a variable. One way to do this is:

• In the block where you want to save the user's response, click on "User Input":

• Next, enable the option "Save response to variable" and give any name to the variable, as explained below:

This way, this variable can be used later in defining the contact. If it's necessary to process the user's response (for any reason), you may need to set up a Script Execution action and save the response to the desired variable. These steps can be consulted here.

 

Defining the contact

After saving all desired information into variables, simply create a contact definition action so that this data is saved in the customer's contact. There are two possible ways to do this process (choose only one).

• Defining contact locally

The first option is to create a contact definition action (under Output Actions) in each of the blocks (i.e., locally) where the user provides the desired information, saving only that specific information.

For example, if there's a block asking for an email, you would create a contact definition in output actions to save the email, as shown below:

And so on for other blocks requesting desired user information.

• Defining contact globally

The second option is to define the contact globally, so you only need to create the action in your bot's global actions, not in each specific block anymore.

 

Follow these steps:

 

Access settings;

In global actions, create the output action: define contact;

Save all desired information (already defined in their respective variables) at once;

This way, this contact-saving action will be executed globally.

More information about the contact definition action can be found at this link.

 

HTTP request action to the HubSpot API

In this step, it's necessary to configure the request that will actually send the lead data to HubSpot. To do this, you need to define an HTTP request action (under global actions) in the bot's builder. Navigate to the following path:

• Configuration >> Global Actions >> Add Output Action >> HTTP Request

Click on the HTTP Request action and fill in the necessary information for it to execute successfully. Below is the configuration specifying the parameter name and its corresponding value:

• Method: POST
• URL: https://hubspot.cs.blip.ai/api/HubSpot/v2/lead/management
• Headers: Click on "add header" and add the following headers. botId refers to the Key field. Its value is explained below:

botId: <The router ID if the integration was installed on it> or <the bot ID where this configuration is being made if there's no router>.

 

This information can be found on the home page of your bot/router as shown in the image below:

Important: To ensure lead registration works, the HubSpot integration must be installed on the current bot or router (if your bots are connected to a router).

 

In the first case, use the child bot ID. In the second case, use the router ID (this is recommended: install the plugin and integrations through the router and use the router ID in child bots for requests to the HubSpot API).

 

Body: Click on the body option and set it with the value shown below, then press ctrl + s to save:

 

{
    "contact" : {{contact.serialized}},
    "integrations" : [
        "Integration 1",
        "Integration 2",
    ]
}

Important:  The integrations property is the only one that can be changed in the body shown above. It will define to which HubSpot accounts the lead record should occur. To do this, simply specify one by one the name of the integration that corresponds to each of the HubSpot accounts you want to integrate (remember that the integration names provided must match the integrations registered in the bot where the plugin was installed). To check the available integration names, just access the HubSpot Integration plugin.

Always write the integration names exactly as shown in the Plugin, between double quotes (“”) and separate each integration name by comma (as shown in the example above).

 

If you want the lead record to occur for all integrations (HubSpot accounts) currently available in the bot in question, simply define the integrations property as empty, as shown below:

 

{
    "contact" : {{contact.serialized}},
    "integrations" : []
}

 

An example of the HTTP request action body to register the lead in the accounts named by

Integration 1 and Integration 2 are:

 

 

• Variable for Response Status: <Any desired name>, but we recommend leadStatus.
• Variable for Response Body: <Any desired name>, but we recommend leadResponse.

This way, your configuration will be as displayed in the figure below (only differing in the botId value):

 

• For more information on the HTTP Request action, see this link.

 

Final Considerations

Therefore, for your bot to be able to register the lead, it is necessary to:

• Save the desired information throughout the conversational flow.
• Set up the contact definition action.
• Define an HTTP Request action that will send the contact information to HubSpot.

Note that if you have chosen to configure the contact definition globally, the following order of global actions must be maintained: first, set up the Contact Definition action, and then define the HTTP Request action, as shown below (under Configuration >> Global Actions):

If you have chosen local contact definition, in global actions there will only be the HTTP Request action in output actions, since the contact definition is being done locally in the blocks.

 

Lead registration in HubSpot

 

Below are some guidelines on the operation and validation of lead registration on the HubSpot side .

 

Validating lead registration

Once all the settings described above have been correctly implemented, when users interact with the bot, the lead registration should be successfully created in HubSpot in the contacts section, as demonstrated below:

 

Contact properties

The default properties of the Blip contact, namely: name, email, city, phone, and gender, already exist in HubSpot. Therefore, a direct mapping of these existing properties will be carried out.

 

Custom properties

The custom (extra) properties of the Blip Contact that do not yet exist in HubSpot will be automatically created as new contact properties.

Important: All custom (extra) properties of the Blip Contact are understood to be text (string). Thus, properties created in HubSpot for the first time via the Blip Contact extras will be created as string type.

 

To verify these properties in HubSpot, along with all others, follow these steps:

 

Click on the desired contact and then Actions > View all properties.

 

 

Next, select Contact Information and locate the desired property.

 

Existing properties in HubSpot

If a contact property already exists in HubSpot and you want to populate this property with information obtained from your bot's conversational flow, you first need to know the internal name of this property in HubSpot. To do this:

 

Click on settings (gear icon) and then select properties.

 

When you click on the desired property, a new screen will appear where you can click on the </> symbol to display the internal name of the property, as shown below.

 

This internal name of the property must be copied and used in the contact definition (in the extras property) if necessary, as exemplified below:

 

 

Important: As mentioned earlier, all Blip contact extras are understood as text (string). Therefore, to use a property already created in HubSpot, it must be of type string, otherwise, this property will not be populated during integration. Example: If a field named age already exists in HubSpot, it needs to be of type string for Blip to successfully populate its value.

In other words, existing properties in HubSpot need to be of type text (string), even if the field expects to receive a number or another type that is not explicitly text (string).

 

 

For more information, visit the discussion on the subject at our community or videos on our channel. 😃