> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.messageblue.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.messageblue.ai/_mcp/server.

# HubSpot MessageBlue Integration

Private beta

**The MessageBlue HubSpot integration** is in private beta and is not enabled on every account yet. Ask your MessageBlue administrator or support team for access.

MessageBlue connects your iMessage numbers to **HubSpot Conversations** as a custom channel. Customers text your MessageBlue number, the conversation lands in your HubSpot Inbox, and your team replies from HubSpot exactly as they would on email or live chat — the reply is delivered as an iMessage.

You do **not** need HubSpot developer keys, API secrets, or MessageBlue server credentials. Everything is done in the MessageBlue app and in your HubSpot account.

#### [Set it up](/hubspot-messageblue-integration-setup)

Install the app, connect your portal, and confirm the channel in your Inbox.

#### [Something not working?](/hubspot-messageblue-integration-troubleshooting)

Every status message, what it means, and the fix.

## What you get

| In HubSpot                               | What happens                                                                |
| ---------------------------------------- | --------------------------------------------------------------------------- |
| A customer texts your MessageBlue number | A new or existing thread appears in your HubSpot Inbox, marked **Incoming** |
| You reply in HubSpot Conversations       | The reply is delivered to the customer as an iMessage                       |
| You start a chat from MessageBlue        | The iMessage is sent and a HubSpot thread is created or continued           |

Because both directions flow through the same thread, HubSpot stays the single place your team works — nobody has to watch a second inbox.

## One app, one portal

A MessageBlue app links to **exactly one** HubSpot portal, and a portal links to one app. If you run several MessageBlue apps, connect each one separately from its own **Settings → HubSpot CRM** tab.

Once connected, tokens refresh automatically. You do not reconnect per message, per day, or per thread — only if you uninstall the app in HubSpot or deliberately switch portals.

## Before you begin

#### A MessageBlue app you administer

You need access to that app's [Settings](/settings), where the connection is made.

#### A live MessageBlue number

At least one iMessage-enabled number online through the [MessageBlue Mac agent](/concepts#numbers-devices-and-the-mac-agent). This is the number customers text and the line HubSpot uses for the channel.

#### A HubSpot account with Conversations access

You need permission in HubSpot both to **install apps** and to use **Conversations / Inbox** on the portal you intend to connect.

Your **Mac agent must be online** for messages to move in either direction. A connected portal with an offline agent produces the most confusing symptom in this integration: HubSpot accepts your reply and shows it in the thread, but nothing reaches the customer's phone. Check the green **Online** indicator on your [dashboard](/dashboard#phone-numbers) first.

## What you do **not** need to do

* You do not paste a HubSpot **Client ID** or **Client Secret** into MessageBlue.
* You do not generate a webhook signing secret for HubSpot — unlike [Zapier](/zapier-messageblue-integration-setup#1-get-your-credentials), there is no secret to copy.
* You do not reconnect for every message. One **Connect** is enough.
* You do not configure MessageBlue server URLs. That is handled for you.

## Permissions MessageBlue requests

When you authorize, HubSpot asks you to approve these scopes:

| Scope                                 | Why it is needed                                              |
| ------------------------------------- | ------------------------------------------------------------- |
| `conversations.custom_channels.read`  | Read the messages and threads on the MessageBlue channel      |
| `conversations.custom_channels.write` | Publish inbound iMessages into HubSpot, and send your replies |
| `conversations.read`                  | Find the Conversations inbox to attach the channel to         |
| `crm.objects.contacts.read`           | Match an incoming phone number to an existing contact         |
| `crm.objects.contacts.write`          | Create a contact when a number is not yet in your CRM         |

MessageBlue uses these only to sync iMessage conversations for the app you connected. To revoke, uninstall MessageBlue in HubSpot, or connect a different portal from MessageBlue Settings.

## How it relates to the rest of MessageBlue

HubSpot is one of several routes into your messages, and they compose rather than compete:

| Route                                         | Best for                                                           |
| --------------------------------------------- | ------------------------------------------------------------------ |
| **HubSpot**                                   | Your team replying from the CRM they already live in               |
| **[Zapier](/zapier-messageblue-integration)** | Connecting to other SaaS tools with no code                        |
| **[Webhooks + API](/settings#webhooks)**      | Your own server, full control over payloads and retries            |
| **[AI Agent](/ai-agent-studio)**              | Replying automatically in natural language from your own knowledge |

If the [AI agent](/ai-agent-studio) is deployed on the same app, it answers customers automatically **while** conversations sync to HubSpot. That is often what you want — the agent handles the first response and your team sees the whole thread — but it does mean a human replying in HubSpot may be the *second* reply the customer receives. Decide which one owns the conversation before you go live.

Ready? Continue to [setting up HubSpot](/hubspot-messageblue-integration-setup).