Before you begin
You'll need:
- A Project Blue account with at least one active line. If you don't have one yet, book a demo or get started.
- A HubSpot user with permission to install apps (App Marketplace Access or Super Admin).
The core integration — contact sync, activity logging, and workflow actions — works on every HubSpot tier, including Free. Two features have plan requirements on HubSpot's side: deal-based sending requires Sales Hub, and the shared iMessage inbox channel requires Service Hub Enterprise.
Step 1 — Install from the HubSpot Marketplace
There are two ways to start; both end in the same place.
From Project Blue: Log in to Project Blue, open the CRM connection screen, and choose the HubSpot card that matches your subscription. You'll be redirected to HubSpot to authorize.
From the HubSpot Marketplace: Open the Project Blue listing, click Install app, and choose the HubSpot account you want to connect.
Step 2 — Review and approve permissions
HubSpot will show the data Project Blue requests and why:
- Contacts (read & write) — match inbound texts and calls to contacts, and optionally auto-create a contact when someone new texts or calls you.
- Owners (read) — attribute logged messages and calls to the right rep.
- Companies (read) — log activity to the parent company record as well as the contact, so B2B teams see texts and calls on the company timeline.
- Deals (read, optional) — HubSpot grants this only to portals with Sales Hub; it enables sending to a deal's primary contact from deal-based workflows.
- Conversations custom channels (optional) — HubSpot grants this only to Service Hub Enterprise portals; it powers the iMessage channel in your shared inbox.
Click Connect app. You'll be redirected back to Project Blue and your portal is linked.
Step 3 — Finish setup in Project Blue
Back in Project Blue, confirm your line is assigned and (optionally) map any custom phone-number properties your team uses. Project Blue searches HubSpot's standard phone fields by default and can search up to five additional custom properties for contact matching.
Step 4 (optional) — Connect the iMessage inbox channel
Requires Service Hub Enterprise.
- In HubSpot, go to Settings → Inbox & Help Desk → Inbox.
- Select the inbox you want to use and click Connect a channel.
- Choose iMessage (by Project Blue). The connection completes automatically and returns you to HubSpot.
Use this settings path rather than the "connect your first channel" cards shown on an empty inbox — those cards don't reliably launch app channel connections.
Once connected, inbound iMessages and texts appear as conversations in your shared inbox, and replies sent from HubSpot are delivered through your Project Blue line.
Step 5 — Using the integration
- Activity logging: Outbound and inbound texts are logged as SMS Communications on the contact (and associated company). Calls made through Project Blue are logged as call engagements with duration, outcome, and recording link.
- Follow-up tasks: Inbound replies can create a high-priority follow-up task assigned to the contact owner.
- Workflow actions: In HubSpot workflows (Automations → Workflows), Project Blue adds Send iMessage (message text, optional media or voice-memo URL, marketing-line toggle) and Check iMessage Availability (outputs a boolean you can branch on). Both work in contact-based and deal-based workflows.
Troubleshooting
- A text didn't match a contact: check the phone number format on the contact and confirm any custom phone properties are mapped in Project Blue (Step 3).
- The inbox channel card does nothing: use the Settings → Inbox path in Step 4.
- Permissions changed after install: disconnect and reconnect the app from Project Blue's CRM connection screen to re-authorize with current scopes.
- Anything else: contact us at /contact.
