Documentation CRM Hercules

CRM integration

Hercules

Hercules integration overview
  • CategoryCRM
  • AuthBearer token

Overview

Hercules connects on /integrations in the dashboard. Click the Hercules card and the 'Connect Hercules' modal takes two fields: API Key (generated in Hercules, Settings, API Keys) and Workspace ID (found in Hercules, Settings, Workspace). The modal copy promises that once connected MessageMind will import your contacts, push new contacts back to Hercules, and keep both sides in sync. On save MessageMind calls the Hercules public API with the pasted key against a read-only contacts probe; a response that is not real JSON (typically because the base URL points at the Hercules web app, which is a static SPA that returns HTML or 405s on POST) is refused rather than quietly stored. Hercules is published upstream as beatrice-ai, so the server also accepts the X-Beatrice-Secret signature header on inbound webhook deliveries.

What MessageMind can do with it

  • Validate the Hercules API key and optional Workspace ID against a lightweight authenticated contacts probe before the connection is saved.
  • Bulk-import Hercules contacts into MessageMind through a confirm-and-poll job (confirm-import plus an import-status endpoint keyed by job id).
  • Receive signed webhook deliveries from Hercules (X-Beatrice-Secret or X-Hercules-Secret, HMAC-SHA256 of the raw body keyed by the per-integration secret) and upsert the matching MessageMind contact.
  • Push a MessageMind contact to Hercules as a new contact when it has never been synced before.

Requirements

  • A Hercules account that can issue an API key from Settings, API Keys.
  • The Workspace ID shown on Hercules, Settings, Workspace, when the account is scoped to a specific workspace.

How to connect

  1. In Hercules, open Settings, API Keys and generate a new API key. Treat the value like a password.
  2. In the same Settings area, open Workspace and copy the Workspace ID that scopes data to the right workspace.
  3. In the MessageMind dashboard, open /integrations and click the Hercules card. The 'Connect Hercules' modal opens.
  4. Paste the API Key (placeholder format her_live_xxxxxxxxxxxx) and the Workspace ID (placeholder format ws_xxxxxxxx) into the two fields and save.
  5. MessageMind calls the Hercules public API with the key against a read-only contacts endpoint and only enables the connection if the response is a real JSON reply from the API (not a page from the Hercules web app).
  6. Once enabled, start the Hercules contact import from the Contacts area; new Hercules contacts flow in afterwards through the signed webhook, and MessageMind contacts without a Hercules link can be pushed outbound.

Authentication and permissions

Mechanism
Hercules public API key sent as a bearer-style credential on every call, plus an optional Workspace ID header that scopes requests to a single workspace. Inbound webhook deliveries from Hercules carry an HMAC-SHA256 signature of the raw body on the X-Beatrice-Secret header (X-Hercules-Secret is also accepted), keyed by the per-integration webhook secret.
Credentials
Two fields on the connect card: API Key (tooltip: generated in Hercules, Settings, API Keys; treat this like a password and never share it) and Workspace ID (tooltip: found in Hercules, Settings, Workspace; used to scope data to the right workspace). Both are stored per tenant alongside a server-minted webhook token and secret.

Available data and actions

Reads

  • A read-only probe against the Hercules contacts endpoint at connect time, used solely to confirm that the key is valid and that the base URL resolves to the Hercules API rather than its web app.
  • Hercules contact records drained by the bulk import job, which MessageMind pages through and upserts as linked contacts.
  • Signed Hercules webhook deliveries for contact create and update events, resolved to the owning MessageMind account by the per-integration token in the webhook URL.

Writes

  • Create a Hercules contact for a MessageMind contact that has never been synced to Hercules before.
  • The connector does not implement updates to linked Hercules contacts, so a change made to a MessageMind contact after it is linked to Hercules is not pushed back; only never-synced contacts are sent outbound.

AI agent use cases

  • Bulk-load your Hercules contact book into MessageMind so the AI can greet existing customers by name.
  • Keep MessageMind in step with Hercules edits in near real time through the signed webhook, without a human re-exporting.
  • Push a new MessageMind contact to Hercules the first time it is created, so the ATS stays the source of truth for the record going forward.

Configuration

  • The inbound webhook URL carries a per-integration token minted by MessageMind. Pasting that URL into Hercules both routes deliveries to your account and authenticates the delivery alongside the HMAC header.
  • If the webhook secret is missing on the stored integration, MessageMind refuses to serve the webhook URL and asks you to reconnect so a fresh secret can be generated.
  • Outbound create fires only once per contact: a contact that already carries a Hercules link is never re-sent because this connector has no implemented contact-update operation.

Example workflows

Connect and first import

  1. You paste the API Key and Workspace ID into the 'Connect Hercules' modal.
  2. MessageMind calls the Hercules contacts endpoint with the key and only saves the connection if the response is real JSON from the API.
  3. You start the Hercules contact import from the Contacts area; MessageMind enqueues the job and exposes its progress through the import-status endpoint until it finishes.
  4. Each row is converted to a MessageMind contact and linked to the Hercules record so later edits land on the same contact.

Live upsert through the Hercules webhook

  1. Hercules posts a contact event to the MessageMind webhook URL carrying your integration token.
  2. MessageMind verifies the X-Beatrice-Secret (or X-Hercules-Secret) HMAC-SHA256 signature against the per-integration webhook secret, rejecting any delivery whose signature does not match the raw body.
  3. The event is resolved to your account by the token and the matching MessageMind contact is upserted; a delete event detaches the Hercules link while keeping the MessageMind contact and its conversation history.

Limitations

  • This connector has no implemented contact-update operation, so MessageMind only pushes contacts that have never been synced before; later edits to a linked contact stay local.
  • The connect probe is deliberately strict: an HTML or 405 response is treated as a misconfigured base URL (the public hostname beatrice-ai.onhercules.app is the static web app, not the API) and the connection is refused rather than silently stored.
  • The Workspace ID is only required when your Hercules account is scoped to a workspace; leaving it blank is allowed when the key already resolves to a single workspace.
  • A webhook delete removes the Hercules link from the matching MessageMind contact but never deletes the MessageMind contact itself.
  • The current connector handles contacts; it does not manage conveyancing matters, legal documents or solicitor allocation.

Troubleshooting

The connect form reports an invalid key.

Reissue the key from Hercules, Settings, API Keys and paste the fresh value. If your account is scoped to a workspace, also fill in the Workspace ID from Hercules, Settings, Workspace.

The key is accepted by Hercules but MessageMind refuses to save it.

The probe response was HTML rather than JSON, which usually means the base URL points at the Hercules web app (beatrice-ai.onhercules.app) instead of the Hercules API. Contact MessageMind support so the API base URL can be checked.

The webhook URL cannot be fetched for pasting into Hercules.

The stored integration is missing its webhook secret. Reconnect Hercules so a fresh token and secret are minted, then copy the new webhook URL into Hercules.

An edit made to a linked contact in MessageMind never reaches Hercules.

This connector only pushes contacts that have never been synced. The initial outbound create happens once; later edits stay in MessageMind because updating linked Hercules contacts is not implemented.

Disconnect and reconnect

  • In the MessageMind dashboard, open /integrations and select Hercules, then choose Disconnect. The stored API key, Workspace ID and webhook secret are removed from your tenant and Hercules webhook deliveries stop being accepted.
  • To reconnect, generate a fresh API key in Hercules, Settings, API Keys and paste it (with the Workspace ID when applicable) back into the connect form. Previously imported contacts stay in MessageMind.