Configuration

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 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 — 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.

​Before You Begin

​Settings

​Contact Phone Mapping

​Webhook URL

​Workflow Custom Action

​Auto-Send on Contact Creation

​See Also

Before You Begin

Settings

Contact Phone Mapping

Webhook URL

Workflow Custom Action

Auto-Send on Contact Creation

See Also