> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychert.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Install
> Connect your HubSpot account to Chert through the OAuth install flow.
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
Sign in at `https://console.trychert.com` and open the project you
want HubSpot to send from.
Click **Settings** in the top nav, then scroll to the
**Integrations** section.
Chert redirects you to HubSpot's OAuth approval screen.
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**.
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 any contact that has a phone number in the `phone` or
`mobilephone` property.
The card appears in the right sidebar of the contact record. The
first load takes a moment while the card fetches conversation
history.
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.
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. |
## See Also
* [Configuration](/hubspot/configuration) — bind a Chert project, pick a phone line, set up auto-send.
* [Security](/hubspot/security) — scope rationale, signature verification, token storage.
* [Limits](/hubspot/limits) — rate limits, daily caps, retry semantics.