Before You Begin
| Requirement | How to verify |
|---|---|
| You are a HubSpot Super Admin or have the App Marketplace Access permission | In HubSpot, open Settings → Users & Teams, find yourself, and confirm the permission. |
| You have an active Chert project | Open https://console.trychert.com and confirm the project you want to send from. |
| At least one healthy phone line is provisioned for the project | Chert support provisions phone lines during onboarding. |
Outbound HTTPS to console.trychert.com is reachable from HubSpot | This is the default for HubSpot-hosted webhooks and UI extensions. No allowlisting is required. |
Scopes Requested
When you click Install, HubSpot prompts you to approve the scopes below. Each scope is the minimum required to make a feature work.| Scope | Why Chert needs it |
|---|---|
oauth | Issue and refresh access tokens for your account. |
crm.objects.contacts.read | Read a contact’s phone, mobilephone, firstname, lastname, and company when you open the sidebar card or trigger a workflow. |
crm.objects.contacts.write | Create Communication engagements on the contact timeline when a reply arrives. |
crm.schemas.contacts.read | Resolve the contact object schema so reads work across portals with custom property layouts. |
automation | Register the Send iMessage via Chert workflow custom action and accept callbacks from it. |
Install the App
Open the Chert console
Sign in at
https://console.trychert.com and open the project you
want HubSpot to send from.Open Settings → Integrations
Click Settings in the top nav, then scroll to the
Integrations section.
Pick the HubSpot account and approve
HubSpot lists every account you have access to. Pick the account
you want to bind to this Chert project, review the scopes, and
click Connect app.
Verify the Install
Open a contact in HubSpot
Open any contact that has a phone number in the
phone or
mobilephone property.Locate the Chert iMessage card
The card appears in the right sidebar of the contact record. The
first load takes a moment while the card fetches conversation
history.
Send a test message
Type a short message in the conversation tab and click Send.
The bubble appears immediately in the card, and the same message
appears in the Chert console for the bound project within a few
seconds.
Reinstall and Re-authorize
Re-running the install flow against an account that already has Chert installed rotates the access and refresh tokens. The bound Chert project is preserved — a re-install never silently moves an account between projects. To move an account between projects, disconnect first, then run the install flow from the destination project.Uninstall
You can disconnect from either side; both end states are equivalent.| From | Result |
|---|---|
| Chert console (Settings → Integrations → Disconnect) | The HubSpot tenant is marked inactive in Chert. The sidebar card stops loading; workflow actions return an error. |
| HubSpot connected apps (Settings → Integrations → Connected Apps → Uninstall) | HubSpot fires an app.uninstalled webhook to Chert. Chert marks the tenant inactive. |
Troubleshoot Installation
| Symptom | Resolution |
|---|---|
| OAuth approval screen shows “App not found” | Confirm the install link is current. Old links from before a Chert client ID rotation no longer resolve. |
Callback returns an OAuth state error (code 2014, reason: state_mismatch / missing_state_cookie / invalid_state_cookie / missing_code_or_state) | The install state cookie expired (10-minute TTL), is missing, or was tampered with. Click Connect HubSpot again to restart the flow. The callback body carries a stable short reason slug plus a trace_id. |
| Sidebar card shows “unknown or inactive tenant” | The HubSpot account was disconnected. Reconnect from the Chert console. |
| Workflow action does not appear | The workflow custom action requires the automation scope. Re-install if the scope was not granted. |
See Also
- Configuration — bind a Chert project, pick a phone line, set up auto-send.
- Security — scope rationale, signature verification, token storage.
- Limits — rate limits, daily caps, retry semantics.