> 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.

# Set up the 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.

Setup has three stages: install MessageBlue in HubSpot, connect your portal from MessageBlue, then confirm the channel appears in your Inbox. You do all three once per MessageBlue app.

**Both halves are required.** Installing the app in HubSpot does not by itself link it to your MessageBlue app, and connecting from MessageBlue cannot succeed until the app is installed. Stopping after Step 1 is the most common reason status stays *Not connected*.

## 1. Install MessageBlue in HubSpot

#### Sign in to the right portal

Sign in to the HubSpot portal your team actually works in. If you administer several portals, confirm which one you are in before installing — the portal you install into is the one you must authorize in Step 2.

#### Install the app

Either search for **MessageBlue** in the HubSpot Marketplace, or use the install link provided by your MessageBlue contact.

#### Review and authorize

Review the requested permissions — see [the scope list](/hubspot-messageblue-integration#permissions-messageblue-requests) for what each one is for — and click **Connect app** / **Authorize**.

#### Choose the inbox

When HubSpot asks which inbox to use, choose the **Conversations inbox your team monitors**. Picking a rarely-watched inbox is a quiet way to make working messages look like broken ones.

After install, MessageBlue appears in HubSpot under **Settings → Integrations → Connected Apps**, and becomes available as a channel in Conversations.

## 2. Connect HubSpot from MessageBlue

![MessageBlue Settings with five tabs and HubSpot CRM selected, showing an App ID field, a Status line, and Connect HubSpot and Refresh status buttons](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/message-blue.docs.buildwithfern.com/fb291003bf8030036072830b571879ef106fdff5f796c93f8ec1f2bcb7c12350/docs/assets/frontend/settings-hubspot-crm.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260916%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260916T201526Z&X-Amz-Expires=604800&X-Amz-Signature=47909ea915a278c87babf680d777de701f058a8aa9bc3743247986692d007193&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

#### Open Settings → HubSpot CRM

Sign in to the MessageBlue web app, open **Settings** from the left rail, and select the **HubSpot CRM** tab.

#### Check your App ID

The **App ID** shown is the MessageBlue app you are about to link. If you administer more than one app, confirm this is the right one — quote it if you contact support.

#### Click Connect HubSpot

The button opens HubSpot's authorization screen **in a new browser tab**. A toast confirms: *"Complete HubSpot authorization — after you finish in HubSpot, return here."*

#### Authorize the same portal as Step 1

Sign in to the portal you installed into and approve access. Let the flow finish — closing the tab early leaves the connection incomplete.

#### Return to MessageBlue

On success HubSpot shows a **✅ Connected to HubSpot!** page listing your **Portal ID** and **MessageBlue App ID**. Switch back to the MessageBlue tab — status refreshes on its own when the tab regains focus. **Refresh status** is there as a manual fallback.

Status should now read **Connected**, with your **Portal ID** and, once HubSpot has assigned one, the **channel account** and its phone number.

The same button becomes **Reconnect HubSpot** once you are connected. It is not a separate control — use it to move this app to a different portal, or to repair a connection after uninstalling in HubSpot.

## 3. Confirm the channel in your Inbox

#### Open Conversations → Inbox

In HubSpot, go to **Conversations → Inbox**.

#### Check MessageBlue is a connected channel

Confirm **MessageBlue** appears in that inbox's channel list.

#### Attach the phone number if prompted

If HubSpot asks you to connect a phone number or channel account for MessageBlue, complete it so Conversations knows which line to use. This should be the same MessageBlue number your Mac agent serves.

If MessageBlue never appears in the channel list, the channel is not enabled for your install — contact MessageBlue support rather than reinstalling repeatedly.

## Day to day

### A customer texts you

The message arrives on your MessageBlue number, appears in HubSpot Conversations under **MessageBlue**, and is marked **Incoming**. Reply in the thread as you would on any other channel; the customer receives it as an iMessage.

### You start the conversation

![New conversation card with a Recipient phone E.164 field, a First message textarea, and a Create conversation button, all disabled with the hint Connect HubSpot above before starting a conversation](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/message-blue.docs.buildwithfern.com/9e2d8556ff8959c201456a8e495e6e4204b890de77b69c465078f584092d43bd/docs/assets/frontend/settings-hubspot-new-conversation.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260916%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260916T201526Z&X-Amz-Expires=604800&X-Amz-Signature=5ae013a3c7357f7d2cbb57156d5ff11fd485205f8aa50b5425aa748beb517a99&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

#### Open Settings → HubSpot CRM → New conversation

The fields are disabled until HubSpot is connected — the hint below the button says so.

#### Enter the recipient and first message

**Recipient phone** in E.164, and the **First message** to send.

#### Click Create conversation

MessageBlue sends the iMessage and opens or continues the matching HubSpot thread. The confirmation tells you which happened: *"Conversation created in HubSpot"* for a new thread, *"Message sent on existing HubSpot thread"* for one that already existed.

Phone numbers must be entered in **E.164 format** — a leading `+`, the country code, then the national number, with no spaces, dashes or brackets. For example `+15550109988`. The app rejects anything else before it reaches the gateway.

## Switching portals or reconnecting

| Situation                          | What to do                                                                                      |
| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
| The wrong portal was connected     | **Settings → HubSpot CRM → Reconnect HubSpot**, then authorize the correct portal               |
| The app was uninstalled in HubSpot | Reinstall MessageBlue in HubSpot, then **Connect HubSpot** again in MessageBlue                 |
| You added a new MessageBlue app    | Connect HubSpot separately under that app's own Settings — connections do not carry across apps |

## Quick test

Once status reads **Connected**, prove all three directions in order — each one isolates a different failure:

#### Outbound from MessageBlue

Use **New conversation** to message your own phone. You should receive the iMessage, and a thread should appear in HubSpot.

#### Reply from HubSpot

Reply in that HubSpot thread. Your phone should receive it.

#### Inbound from the phone

Text the MessageBlue number from your phone. The HubSpot thread should update, marked **Incoming**.

If step 1 delivers the iMessage but HubSpot stays empty, wait a few seconds and refresh the Inbox, then check the MessageBlue channel is not filtered out of your view. If nothing arrives at the phone at all, the [agent is offline](/hubspot-messageblue-integration-troubleshooting) — that is a MessageBlue problem, not a HubSpot one.