Skip to main content

Aventora CRM ↔ Engagement Hub

Connect Aventora CRM with the Engagement Hub so your team can start phone, SMS, and email engagements from a Person record and see results — status, history, and transcripts — on that same record.

Related: CRM integration webhooks, CRM complete guide

What you get​

  • Engage By Aventora on any Person with a phone number or email — choose channel, mode, and instruction in a modal.
  • Aventora section on the Person record — list of engagements with expandable history and transcript.
  • Workflows — Send Email (Engagement Hub) and Aventora Engagement / Bulk Engagement steps start Hub outreach. Engagement steps pick a cockpit action type from a dropdown and show a prefilled, editable instruction. Email uses informational channel + Hub Outbound Email sender.
  • Automatic sync — when a call or message completes (or pauses, resumes, or cancels), the Hub sends updates back to CRM.
  • One active engagement per person — prevents duplicate outreach until the current engagement finishes or is cancelled.

Hub-originated calls (inbound or outbound) can also create or update CRM contacts and mirror engagement status when CRM sync is enabled for your domain.

How it works​

Person in CRM  →  Engage By Aventora  →  Engagement Hub starts call/SMS/email
       ↑                                        |
       |                                        | status updates (webhook)
       └──── Aventora section on Person  ←─────┘
  1. A user opens a Person and chooses Engage By Aventora (command menu or Aventora section).
  2. CRM calls the Hub to start the engagement and stores an engagement record linked to that person.
  3. The Hub runs the engagement and posts updates to CRM when status changes.
  4. The Person Aventora section shows progress, outcome, history, and transcript.

Configuration overview​

Settings are split between the CRM server, each CRM workspace, and the Engagement Hub.

CRM server​

VariablePurpose
AVENTORA_BASE_URLHub root URL (no trailing slash). CRM uses this to start engagements.
AVENTORA_WEBHOOK_SECRETOptional. Must match the Hub webhook secret if you use one.
APP_SECRETRequired when the workspace API key is stored encrypted.

CRM workspace (Settings → Applications → Aventora)​

VariablePurpose
AVENTORA_ASSIGNED_DOMAINHub domain name for this workspace
AVENTORA_API_KEYHub API key (Bearer token) for call management

You can also configure default channel, mode, instruction, roles allowed to start engagements, and whether Aventora is enabled for the workspace.

Engagement Hub​

VariablePurpose
TWENTY_WEBHOOK_URLCRM webhook URL, e.g. https://your-crm-host/rest/aventora/webhook
TWENTY_WEBHOOK_SECRETOptional; must match AVENTORA_WEBHOOK_SECRET on the CRM server

See CRM integration webhooks for retry and debounce settings.

Per-account webhook URL and secret can be set on the Hub account instead of environment variables when preferred.

Starting an engagement​

  1. Log in to Aventora CRM and open a Person with at least one phone number or email.
  2. Open the record menu and choose Engage By Aventora, or use Start new engagement in the Aventora section.
  3. Confirm channel (phone, SMS, or email), mode, instruction, and contact if the person has multiple numbers or addresses.
  4. On success you see a confirmation; the engagement appears in the Aventora section with status such as accepted or in progress.

Common errors

MessageWhat to check
Aventora integration is not configuredWorkspace application variables and AVENTORA_BASE_URL
Person has no phone or emailAdd contact details on the Person
Person already has an active engagementComplete or cancel the existing engagement first
Unauthorized from HubAPI key and domain match between CRM and Hub

Viewing results on the Person​

Open the Aventora section on the Person record. Each engagement shows status, outcome, summary, and timestamps. Expand an row for full history (events such as pause/resume) and transcript (conversation messages).

Use Complete or Cancel on an active engagement to clear the one-active-engagement rule and start a new one.

If Hub cannot find an engagement (for example it was removed on the Hub side), CRM may show it as Broken.

Webhook sync and troubleshooting​

Updates are pushed from Hub to CRM when engagements start, pause, resume, cancel, or complete.

If CRM never receives updates:

  1. Confirm TWENTY_WEBHOOK_URL is set on the Hub and points to the CRM server host and port (same base URL users use for CRM, path /rest/aventora/webhook).
  2. Confirm Hub can reach that URL from its network (not localhost if Hub runs in Docker on another host).
  3. If you use a webhook secret, set the same value as AVENTORA_WEBHOOK_SECRET on the CRM server.
  4. Check Hub and CRM logs around the time of a test engagement.

Failed webhook deliveries are retried automatically for server errors; client errors (4xx) are not retried. See CRM integration webhooks.

Person visibility (PERSON_WALL)​

When PERSON_WALL is enabled, users only see Person records they created (or that match their scope), plus system contacts depending on configuration.

Hub-created contacts can be attributed to the initiating workspace member when provisioning and ownership context are configured. Contacts created without a member may appear as system/Aventora records.

Ask your administrator about PERSON_WALL settings if users cannot see contacts they expect.

Deployment​

Run Aventora CRM from the aventora-crm repository with the Aventora Docker image (aventora-twenty:latest), not the public upstream CRM image.

Deployment guides are available to customers under agreement. Contact sales@aventora.ai.

Changelog​

DateChange
2026-08-17Aventora Engagement workflow steps use a cockpit action type dropdown and a multiline instruction field prefilled from the selected action.
2026-07-31CRM workflows can start Hub engagements and send informational email via Send Email (Engagement Hub) / Start Engagement steps.