Install

Connect Chert to your HubSpot account in under a minute. The install is fully OAuth-driven — there is no package to upload and no admin SQL to run on the HubSpot side.

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.

Chert does not request access to deals, companies, tickets, or any custom object.

Install the App

Open the Chert console

Open Settings → Integrations

Click Settings in the top nav, then scroll to the Integrations section.

Click Connect HubSpot

Chert redirects you to HubSpot’s OAuth approval screen.

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.

Return to Settings

HubSpot redirects back to the Chert console with the new install confirmed. The Integrations section now shows the bound HubSpot account ID, the granted scopes, and a Disconnect button.

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.

Confirm the workflow action is available

In HubSpot, open Workflows, create a contact-based workflow, and click the + to add an action. Send iMessage via Chert appears in the action picker under the Chert group.

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.

Disconnecting does not delete conversation history. Reconnecting the same account flips the tenant back to active and resumes sending.

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.

Salesforce

HubSpot

Slack

Before You Begin

Scopes Requested

Install the App

Verify the Install

Reinstall and Re-authorize

Uninstall

Troubleshoot Installation

See Also

​Before You Begin

​Scopes Requested

​Install the App

​Verify the Install

​Reinstall and Re-authorize

​Uninstall

​Troubleshoot Installation

​See Also

Before You Begin

Scopes Requested

Install the App

Verify the Install

Reinstall and Re-authorize

Uninstall

Troubleshoot Installation

See Also