> 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 Troubleshooting 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. ## What the status line is telling you The **Status** field on [Settings → HubSpot CRM](/settings#hubspot-crm) has three states, and they fail for completely different reasons. Read it before changing anything. | Status | Meaning | What to do | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | **HubSpot service is not configured on the backend yet.** | Nothing to do with your portal — the MessageBlue backend has no HubSpot service configured, so **Connect HubSpot** is disabled | Contact MessageBlue support. No amount of reinstalling in HubSpot will change this | | **Not connected. Connect once to link this app to HubSpot.** | MessageBlue is ready; this app simply has no portal linked yet | Follow [set up HubSpot](/hubspot-messageblue-integration-setup) | | **Connected** *(with a Portal ID)* | The app is linked to that portal and tokens are refreshing | Nothing — verify with the [quick test](/hubspot-messageblue-integration-setup#quick-test) | The first row is the one people misdiagnose. A **disabled Connect HubSpot button** always means the backend is not configured — it never means your HubSpot permissions are wrong. ## Authorization pages HubSpot's own tab shows the outcome of the OAuth flow directly: | Page | Cause | Fix | | --------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **✅ Connected to HubSpot!** | Success. Lists your Portal ID and MessageBlue App ID | Return to MessageBlue — status refreshes when the tab regains focus | | **❌ Authorization Failed** | HubSpot rejected the request, usually a declined consent or an account without install rights | Retry as a user who can install apps on that portal | | **❌ No Authorization Code** | The flow was interrupted before HubSpot issued a code — most often the tab was closed early | Start again from **Connect HubSpot** and let it finish | | **❌ Connection Failed** | HubSpot approved, but the token exchange or install record failed | Retry once; if it persists, contact support with your App ID and the time it happened | ## Symptoms #### Status still says Not connected after authorizing In order of likelihood: 1. **The flow did not finish.** Reopen **Connect HubSpot** and complete it without closing the tab. 2. **You authorized a different portal** from the one you installed into. Use **Reconnect HubSpot** and pick the right portal. 3. **The page has stale state.** Status refreshes when the MessageBlue tab regains focus — click **Refresh status** to force it. #### Connected, but no threads appear in HubSpot Work outwards from MessageBlue: 1. **Is the Mac agent online?** No agent, no messages in either direction. Check the **Online** indicator on your [dashboard](/dashboard#phone-numbers). 2. **Is MessageBlue a channel on the inbox you are watching?** Confirm it in **Conversations → Inbox** settings, and check your inbox filters are not hiding it. 3. **Send a known-good test** with **New conversation** — that proves the MessageBlue half independently of anything inbound. #### A HubSpot reply never reaches the phone Two causes, both easy to miss: * **The Mac agent is offline.** HubSpot will still accept and display your reply, so the thread looks healthy while nothing is delivered. * **You replied on the wrong channel.** A contact with email or SMS history will happily accept a reply on those channels instead. Confirm the thread you are typing into is the **MessageBlue** one. #### Messages reach the wrong contact, or split across duplicates HubSpot matches threads to contacts by phone number, so formatting decides identity. Use full [E.164](/hubspot-messageblue-integration-setup#day-to-day) everywhere — `+15551234567`, not `(555) 123-4567`. If the same person already exists in your CRM under several number formats, merge those contacts in HubSpot; otherwise the thread attaches to whichever record matched first. #### The thread shows an unknown visitor or an odd name Expected on a first contact from an unrecognised number. MessageBlue passes the phone number; HubSpot matches or creates the contact from it, so the name fills in once a CRM record exists and matches. #### Create conversation is greyed out The **New conversation** fields stay disabled until a portal is connected — the hint under the button says so. Connect first. If the button is active but the send fails, the error toast carries the reason. #### It worked, then stopped after someone changed HubSpot Uninstalling the MessageBlue app in HubSpot removes the install record while MessageBlue still shows the old connection. Reinstall in HubSpot, then **Reconnect HubSpot** in MessageBlue. ## Frequently asked questions #### Do I need a HubSpot Client ID or Client Secret? No. MessageBlue holds the app credentials. You never paste a HubSpot secret into MessageBlue — if a guide tells you to, it is not this integration. #### Do I have to reconnect periodically? No. Tokens refresh automatically once connected. You reconnect only to change portals or after uninstalling the app in HubSpot. #### Can one MessageBlue app connect to two HubSpot portals? No — the mapping is one app to one portal. Connecting a second portal replaces the first. Use a separate MessageBlue app per portal. #### Can I use HubSpot and Zapier at the same time? Yes. They are independent, and both can be active on the same app. See [how the routes compare](/hubspot-messageblue-integration#how-it-relates-to-the-rest-of-messageblue). #### Does the AI agent still reply if HubSpot is connected? Yes. If the agent is deployed it answers as normal, and the exchange still syncs to HubSpot. If a teammate also replies in HubSpot, the customer gets two messages — decide who owns the conversation. #### What phone number format should I use? E.164 with the country code — `+15551234567`. Anything else risks attaching to the wrong contact. #### How do I disconnect? Uninstall the MessageBlue app in HubSpot, and/or connect a different portal from MessageBlue Settings. ## Getting help #### [MessageBlue support](/support) For connection problems, channel setup, and anything on the MessageBlue side. #### [HubSpot help](https://knowledge.hubspot.com) For Conversations, Inbox configuration, and HubSpot account permissions. When contacting MessageBlue support, include: * Your **MessageBlue App ID** — from [Settings → HubSpot CRM](/settings#hubspot-crm) or [API & secrets](/settings#api-and-secrets) * Your **HubSpot Portal ID** — shown on the success page, or in your HubSpot account settings * Which direction failed: **Connect**, **inbound**, or **HubSpot reply** * Roughly when it happened, with the timezone