HubSpot
The HubSpot example solution showcases how to connect a Teneo solution with the HubSpot REST API. The example flows in the solution demonstrate how tickets can be retrieved as well as how to create, update or delete and filter tickets on HubSpot.
Solution contents
HubSpot integration
The solution contains a HubSpot backend integration containing methods for authentication, retrieval of tickets, owners as well as for creating, updating, filtering and deleting tickets. Since the source code of the integration is embedded in the solution, it can be easily extended or used as a starting point for new methods.
Example flows
For each core method in the HubSpot integration, the solution contains a corresponding example flow:
- User asks to retrieve tickets assigned to someone
- User asks to create a new HubSpot ticket
- User asks to delete a ticket
- User asks to update an existing field of ticket
- User asks to filter the tickets
- Bot asks an user to login into HubSpot
- User asks to logout from HubSpot
Authentication flow
HubSpot provides a support for OAuth authentication and API token based authentication methods that allow a Teneo bot to interact with HubSpot on the user's behalf. Which authentication method to use depends on factors like use case and channel. This example solution contains flow to demonstrate API token based authentication approach.
Getting started
Prerequisites
These instructions assume you have a HubSpot admin account. Alternatively, you can signup for a free user account here. These instructions assume you have downloaded and imported the HubSpot solution. See instructions below.
Create a HubSpot connected app
It's time to create a developer instance on HubSpot developer portal in order to perform & experience some CRUD operations by using HubSpot Teneo bot
- Using your administrator account, log in to your HubSpot developer portal.
- For first time login users, click on Confirm email address link sent to your registered email id.
- Click on settings icon located at the top most right corner of HubSpot portal.
- On your left side menu panel, click on Integrations menu and click on API Key menu.
- Click on Create key button once and your new API key will be generated and displayed on screen right immediately
- Click on Copy button and API key (located under 'Active API key' section) and this should be copied and secured immediately as this requires for you to login to HubSpot Teneo bot to perform various operations. Your HubSpot instance setup is completed now
Add credentials to your solution
The solution contains a global variable HubSpot_sAPIKey in which the API key we have collected should be stored. We’re interested in our instance API key. People may try to use their HubSpot API key accordingly. The value of the global variable should be a type of String like this:
| Variable Name | Example value | Description |
|---|---|---|
| HubSpot_sAPIKey | 'XXXXf95-20XX-XXX5-9XX8-XX9XXaXXX' | HubSpot user account API key. |
To update the global variables, proceed as follows:
- In a text editor, update each of above global variables by pasting in the values you have collected in the steps above.
- In you HubSpot solution, click the 'Solution' tab and select 'Globals' in the purple navigation bar.
- Select the 'Variables' tab at the top, select the variable called HubSpot_sAPIKey.
- In the panel on the right, click 'Edit'. You can now update the value of the variable by pasting the updated string values.
- When done, click 'Save All' in the top left corner.
Test in Try Out
Your solution is now ready. You can test this in Try Out by asking Can I retrieve tickets assigned to someone. The Teneo bot would then start asking you to input for follow up questions and then answer should provide the tickets, which are assigned to a user on HubSpot portal.
Example conversations
User: I want to login
Bot: Hi there! I'm a HubSpot Connector virtual assistant from Artificial Solutions.
Bot: Please enter an API key provided by HubSpot.
User: XXXXf95-20XX-XXX5-9XX8-XX9XXaXXX
Bot: Hi there!, Your login has been successful!
User: I want to create a new ticket
Bot: Please enter the subject of ticket.
User: My 1st ticket
Bot: Please choose one of the following priorities. Low, Medium, High
User: High
Bot: Please enter the ticket owner email id. Example : test@domain.com
User: teneo@example.com
Bot: New ticket 3660456 has been created on your HubSpot instance successfully.
User: Can I retrieve tickets assigned to someone
Bot: Please enter the ticket owner email id. Example : test@domain.com
User: teneo@example.com
Bot: Below are list of tickets assigned to test owner. 3660456, 3660478
User: Can I filter the tickets
Bot: Please choose one of the following filter criteria. Unassigned tickets, All high priority tickets
User: All high priority tickets
Bot: Below are list of tickets available for a chosen filter. 3660456, 3660478, 3660483
User: I want to update a ticket
Bot: Please enter an existing ticket id.
User: 3660456
Bot: Please choose one of the following ticket fields. Subject, Priority
User: Priority
Bot: Please choose one of the following priorities. Low, Medium, High
User: Medium
Bot: Priority field has been updated on ticket 3660456 successfully!
User: Can I delete a ticket?
Bot: Please enter an existing ticket id
User: 3660456
Bot: HubSpot ticket 3660456 has been deleted successfully!
User: I want to logout
Bot: Your logout has been successful!
More on authentication
HubSpot offers multiple authentication methods including OAuth authentication and API token key based authentication by using API key that developers can use to allow their users to authenticate with HubSpot. Which authentication flow to use depends on the type of application and the use case.
This HubSpot solution contains a flow called Bot asks an user to login into HubSpot. This flow is responsible to set a value of global variable called HubSpot_bHasUserLoggedIn which is included at the beginning of each other flows that checks the user's authentication to access the flows. This flow checks if the global variables HubSpot_sAPIKey contains a value which is needed to perform API requests. If the HubSpot_bHasUserLoggedIn variable is 'false', this flow answers an user authentication failure message.
By default, the HubSpot solution Bot asks an user to login into HubSpot flow uses the stored credential from global variable to authenticate the user. This flow uses HubSpot's API key based authentication mechanism, which provides instructions in the getting started section on this page explain how to prepare your solution using this authentication approach.
This authentication uses stored credential from global variable HubSpot_sAPIKey to prepare an authentication with HubSpot and used on URL query params of HubSpot integration for the various REST requests and checks an access against HubSpot instance URL stored on HubSpot_sInstanceEndPointUrl and return a successful authentication.
The solution uses the stored credential approach by default, mostly because it is easiest and quickest to get started. However, because this authentication flow passes the user’s credential back and forth it is advised to use this authentication method for development purposes only. Additionally, using stored credentials means that all objects created by the bot are created by the same user. Therefore, it might be preferred to implement an authentication flow that enables Teneo to interact with HubSpot on the user's behalf.
However, this authentication flow can still be used in production grade only when a frontend connector or a channel connector supplies necessary user credentials instead of hardcoding them in Teneo in a more secured way by using any industrial standard encryption techniques.
The authentication flow for the API Key based authentication in combination with Teneo roughly looks like this:
For more details on HubSpot and API Key based authentication, see: Digging Deeper into API token in HubSpot
Download
- Download the solution here.
- Import the solution into Teneo. For more details see: How to import solutions.