> ## 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.
# Configuration
> Bind a Chert project, choose a phone line, configure auto-send, and map contact properties.
Configure a connected HubSpot account from the Chert console. Every
setting below is per HubSpot account; multiple Chert projects each
bound to a different HubSpot account run independently.
## Before You Begin
| Requirement | How to verify |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| The HubSpot account is connected | **Settings → Integrations** in the Chert console shows the account ID and a green **Connected** badge. |
| At least one phone line is healthy in the bound project | The project's Phone Lines page shows one or more lines with status `active`. |
| The project's CRM campaign has a message template | **Settings → Template** is non-empty. |
## Settings
Open **Settings → Integrations** in the Chert console and click the
connected HubSpot account. Each setting persists immediately on save.
| Setting | Default | Effect |
| -------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bound Chert project** | The project the install was launched from | All sends from this HubSpot account land in this project's lead pool. Re-pointing requires a disconnect and reconnect. |
| **Phone line** | Pool default | The phone line that sends from. Leave on **Pool default** to let Chert pick from the project's healthy lines on each send. |
| **Auto-create leads on workflow send** | On | When a workflow action fires for a contact whose phone is not in Chert yet, create a lead before sending. Off makes the workflow action no-op for unknown contacts. |
| **Auto-send on contact creation** | Off | When a contact is created in HubSpot, fire an iMessage immediately using the project's CRM template. |
| **Auto-send template override** | Empty | Optional template used by auto-send on contact creation only. When empty, falls back to the project's CRM template. |
| **Label** | HubSpot account ID | Display label shown on the admin dashboard. Cosmetic only. |
The bound project is locked after install on purpose — silently
re-pointing an active integration would move conversation history
between projects mid-flight. Disconnect and reinstall from the
destination project to move.
## Contact Phone Mapping
Chert reads two HubSpot contact properties when resolving a phone
number, in priority order.
| Order | Property | Notes |
| ----- | ------------- | ---------------------------------------------- |
| 1 | `phone` | The default HubSpot phone property. Preferred. |
| 2 | `mobilephone` | Used when `phone` is empty. |
Numbers are normalized to E.164 before matching. A contact whose
`phone` is `(415) 555-2671` matches a Chert lead whose number is
`+14155552671`.
There is no UI to remap these properties. If your account uses a
custom property for the primary phone, copy it into `phone` through a
HubSpot workflow before triggering a Chert send.
## Webhook URL
The OAuth public app declares its webhook URL once at the app level.
Customers do not configure a webhook URL — the install flow wires the
account up to the right URL automatically.
| Subscription | Endpoint | Purpose |
| ------------------ | ---------------------------------------------------- | -------------------------------------------------------------------- |
| `app.uninstalled` | `https://console.trychert.com/api/hubspot/uninstall` | Marks the tenant inactive when the customer uninstalls from HubSpot. |
| `contact.creation` | `https://console.trychert.com/api/hubspot/webhook` | Optional auto-send on new contact. |
Both endpoints verify the HubSpot Signature v3 header on every
request. See [Security](/hubspot/security) for the algorithm.
## Workflow Custom Action
The **Send iMessage via Chert** action accepts these inputs in
HubSpot's workflow editor.
| Input | Required | Notes |
| ----------- | -------- | ------------------------------------------------------------------------- |
| **Phone** | Yes | Map from the contact's `phone` or `mobilephone` property. |
| **Message** | Yes | Free text. HubSpot's token picker resolves contact tokens before sending. |
| **Name** | No | Persisted on the lead row when auto-creating. |
| **Company** | No | Persisted on the lead row when auto-creating. |
The action returns these output fields, available downstream in the
same workflow.
| Output | Type | Meaning |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `ok` | boolean | `true` if the send was accepted by Chert. |
| `lead_id` | string | The Chert lead ID, set even on dedup. |
| `message_id` | string | Stable Chert message ID for the send. |
| `duplicate` | boolean | `true` when this callback was deduped against an earlier execution. |
| `error` | string | Present only when `ok` is false. Human-readable; do not branch on it. |
| `code` | integer | Present only when `ok` is false. Numeric error code from the shared [Messaging API error scheme](/api/errors) — branch on this. |
| `message` | string | Present only when `ok` is false. Generic human-readable detail; provider names and raw errors are not leaked here. |
| `retryable` | boolean | Present only when `ok` is false. `true` when a backed-off retry is worthwhile. |
| `trace_id` | string | Present only when `ok` is false. Correlation id for support; the full failure detail is logged server-side under this id. |
The custom action **always** returns HTTP `200` — HubSpot retries non-200
responses, so logical failures are signalled in `outputFields` with
`ok: false` rather than via the HTTP status. Branch your workflow on
`outputFields.ok` (and `outputFields.code` for the failure class).
## Auto-Send on Contact Creation
When **Auto-send on contact creation** is on, every contact created in
the bound HubSpot account is checked against three conditions before
Chert fires a send.
| Condition | If false |
| ---------------------------------------------------------- | --------------------------------------- |
| The contact has a phone number on `phone` or `mobilephone` | Skip. Logged as `no_phone`. |
| **Auto-create leads** is on | Skip. Logged as `auto_create_disabled`. |
| The same `objectId` has not already triggered a send | Skip. Logged as `dedup`. |
The send uses the **Auto-send template override** if set, otherwise
the project's CRM template. The phone line resolves the same way as
manual sends — the per-account override first, then the project's
default phone line.
## See Also
* [Architecture](/hubspot/architecture) — how each setting flows through the runtime.
* [Limits](/hubspot/limits) — daily caps, the 10-minute minimum gap, dedup window.
* [Security](/hubspot/security) — what is logged, where credentials live.