Set up the HubSpot MessageBlue Integration | Message Blue

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

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 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 — Settings → HubSpot CRM. The App ID is shown for support; the status line and the button label both change once a portal is linked.

Open Settings → HubSpot CRM

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 — New conversation — sends the iMessage and opens or continues the matching HubSpot thread. The fields stay disabled until a portal is connected.

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 — that is a MessageBlue problem, not a HubSpot one.