GUIDESIntegrations

HubSpot

Learn how to integrate our Conversational AI platform with HubSpot CRM

Overview

Leveraging the HubSpot integration, your agent can interact with your CRM both to retrieve and write relevant information about contacts, interactions, or follow ups.

Demo video

Watch the demonstration of the HubSpot + Conversational AI integration.

HubSpot Integration Demo

How it works

Here is an example of how a Conversational AI agent can interact with your HubSpot CRM using tool calling. Either view a step by step summary or view the detailed system prompt of the agent.

1

Customer Identification

You can configure your agent to ask for an identification item such as email, and prompt it use a tool we called search_contact to search your CRM for that email to verify whether this customer exists.

2

Understand Call Intent

Configure the agent to ask about the caller’s intent. This can be adapted to meet your particular workflow.

3

Get previous interactions

While previous interactions can also be fetched and passed at the beginning of the conversation (see Personalization). In this case we are fetching them during the conversation with two tool calls:

  • The tool get_previous_calls will fetch the previous conversations, using the contact ID retrieved during identification.
  • The response does not include the content of those conversations, so we need to use another endpoint to fetch the content with those call IDs.
4

Ticket Creation

  • The agent can discuss the issue at hand, relating to previous interactions.
  • Use the create_ticket tool to create a ticket for a follow up item
  • Associate the ticket created to the CRM contact

This integration enhances agent efficiency by leveraging CRM interactions. All API calls require proper secret handling in the authorization headers.

Authentication Setup

Before configuring the tools, you must set up authentication with HubSpot.

Step 1: Generate HubsPot API Token

  1. Log into your HubSpot account
  2. Navigate to Account Management → Integrations → Private Apps
  3. Create a Private App
  4. Add the required scopes to the private app, to ensure it can interact with the required endpoints
crm.objects.contacts.read
crm.objects.contacts.write
crm.schemas.contacts.read
crm.schemas.contacts.write
tickets
  1. Save and get the Access token from the Auth section

Step 2: Create Authentication Secret

The HubSpot API requires Bearer authentication. You need to create a properly formatted secret:

  1. Create the secret value by adding “Bearer ” prefix:

    Bearer pat-eu1-12345678-abcdefgh-ijklmnop-qrstuvwx

  2. Save this as a secret in your agent’s secrets with name hubspot_key

Tool Configurations

This sample integration with HubSpot employs four webhook tools. Use the tabs below to review each tool’s configuration.

Name: search_contact
Description: Search for a contact with an email.
Method: POST
URL: https://api.hubapi.com/crm/v3/objects/contacts/search

Headers:

  • Content-Type: application/json
  • Authorization: (Secret: hubspot_key)

Body Parameters:

  • filtersGroups: An array containing:
    • An object containing:
      • filters: An array containing:
        • An object containing:
          • value: A string with description: Set to the email provided by the user. Email should be in format: "name@address.com"
          • propertyName: A string with description: Set to: "email"
          • operator: A string with description: Set to: "CONTAINS_TOKEN"

Tool JSON:

Here is the tool JSON that can be copied into the tool config:

1{
2  "id": "tool_01jxftmwvxfgersp4aw0xhyhea",
3  "type": "webhook",
4  "name": "search_contact",
5  "description": "search for a contact using phone",
6  "api_schema": {
7    "url": "https://api.hubapi.com/crm/v3/objects/contacts/search",
8    "method": "POST",
9    "path_params_schema": [],
10    "query_params_schema": [],
11    "request_body_schema": {
12      "id": "body",
13      "type": "object",
14      "description": "filters for searching contacts",
15      "required": false,
16      "properties": [
17        {
18          "id": "filterGroups",
19          "type": "array",
20          "description": "filters group",
21          "required": true,
22          "items": {
23            "type": "object",
24            "description": "filters",
25            "properties": [
26              {
27                "id": "filters",
28                "type": "array",
29                "description": "filters",
30                "required": true,
31                "items": {
32                  "type": "object",
33                  "description": "filters",
34                  "properties": [
35                    {
36                      "id": "value",
37                      "type": "string",
38                      "description": "Set to the email provided by the user. Email should be in format: \n\n\"oscar@gmail.com\"",
39                      "dynamic_variable": "",
40                      "constant_value": "",
41                      "required": true,
42                      "value_type": "llm_prompt"
43                    },
44                    {
45                      "id": "propertyName",
46                      "type": "string",
47                      "description": "Set to: \"email\"",
48                      "dynamic_variable": "",
49                      "constant_value": "",
50                      "required": true,
51                      "value_type": "llm_prompt"
52                    },
53                    {
54                      "id": "operator",
55                      "type": "string",
56                      "description": "Set to: \"CONTAINS_TOKEN\"",
57                      "dynamic_variable": "",
58                      "constant_value": "",
59                      "required": true,
60                      "value_type": "llm_prompt"
61                    }
62                  ]
63                }
64              }
65            ]
66          }
67        }
68      ]
69    },
70    "request_headers": [
71      {
72        "type": "value",
73        "name": "Content-Type",
74        "value": "application/json"
75      },
76      {
77        "type": "secret",
78        "name": "Authorization",
79        "secret_id": "xWPfWcvnJ6mr6cx2aeN8"
80      }
81    ]
82  },
83  "response_timeout_secs": 20,
84  "dynamic_variables": {
85    "dynamic_variable_placeholders": {}
86  }
87}
Ensure that you add your workspace’s HubSpot secret to the agent’s secrets.

Security Considerations

  • Use HTTPS endpoints for all webhook calls.
  • Store sensitive values as secrets using the ElevenLabs Secrets Manager.
  • Validate that all authorization headers follow the required format.

Conclusion

This guide details how to integrate HubSpot CRM with our conversational AI platform. By leveraging webhook tools, the integration empowers AI agents to act more effectively in usecases such as sales, customer management, or support.

For additional details on tool configuration or other integrations, refer to the Tools Overview.