Follow Up Boss — complete guide

Single reference for connecting Aventora Engagement Hub with Follow Up Boss (FUB): platform setup, tenant and user administration, embedded apps, agent workflows, activity sync back to FUB, tag automation, and integrator APIs.

Audience: Aventora admins/delegates, Follow Up Boss admins, real-estate agents, Aventora platform ops, integrators.

Related platform docs: API_SECURITY_MODEL.md (call-management API keys), BULK_CALL_CSV_GUIDE.md (CSV bulk from Admin — separate from FUB Smart List campaigns), AVENTORA_CRM.md (Aventora CRM / Twenty integration)

Hub implementation (engineers): Aventora-Assistant repo — docs/followupboss-integration.md, docs/fub-userguide.md (mirrors this document)

How the integration works
Who does what
Prerequisites
One-time platform setup (Aventora ops)
Tenant settings (Aventora Admin)
Per-user settings (Aventora Admin)
Register embedded apps in FUB
Two deployment tracks
Track A — Shared FUB brokerage
Track B — Separate FUB account per agent
Day-to-day operations
What syncs back to FUB
What not to use for per-user outreach
Troubleshooting
Quick checklists
Appendix: API & integrators

How the integration works

When FUB is enabled on a tenant, the Hub can:

Start outreach from FUB — agents use embedded apps (single contact or Smart List bulk), or automations/API start calls on the tenant’s behalf.
Sync activity back to FUB — when contact sync is on, the Hub resolves or creates FUB people and logs calls, SMS, WhatsApp, chat, and email activity on the matching person record.

FUB (embed / tag / API)  →  Aventora Hub  →  voice / SMS / email / chat
                                    ↓
                         FUB person record (calls, texts, notes)

Per-agent identity: Embedded apps run as the FUB user who opened the iframe. The Hub maps that user by phone number to an Aventora user and applies that user’s outreach phone and optional per-user FUB API key.

Tenant-level flows: Tag webhooks and API-only starts do not know which FUB agent is acting. Use embedded apps when each agent must have separate caller ID and CRM attribution.

Where settings live (three layers)

FUB configuration is layered. Each layer authenticates something different — none replaces another:

Layer	Where set	Authenticates	Key settings	Required?
Platform	Hub server `.env` (Aventora ops)	Aventora as a registered FUB system (`X-System` / `X-System-Key` headers on every FUB API call)	`FUB_SYSTEM`, `FUB_SYSTEM_KEY`	Yes — without `FUB_SYSTEM_KEY` no FUB feature works at all (no sync, no webhooks, connection test fails), regardless of account/user keys
Tenant	Aventora Admin → Account settings → CRM	The tenant’s data in FUB (HTTP Basic with `fub_api_key`)	Provider, `fub_api_key`, Sync contacts, `fub_start_call_tag`, `fub_embedded_app_secret`, `fub_campaign_embedded_app_secret`	Yes per tenant — provider + API key + Sync contacts
User	Aventora Admin → User account settings	The acting agent	Outreach phone, `fub_api_key`, `fub_embedded_app_secret`	Phone required for per-agent identity; API key required in Track B, optional in Track A

Who does what

Role	Responsibility
Aventora platform ops	One-time Hub deployment: register Aventora as a FUB system, set platform env vars
Aventora admin / delegate	Tenant CRM settings, per-user phones and API keys, connection test, embed URLs for agents
FUB admin	Registers embedded apps (Track A: once for the brokerage; Track B: each agent in their own FUB); optional tag webhook in FUB
Agent	Uses embedded apps while logged into FUB as themselves

Prerequisites

Before you start:

Aventora admin access for your tenant (examples below use fub-test)
Each agent (e.g. u1, u2) as a user on that tenant
Each agent’s outreach phone (mobile or direct line for caller ID and call bridging)
FUB access for each agent
Hub call management billing/credits configured for the tenant (required for bulk campaigns)

For per-user outreach, agents should start engagements from the embedded apps in FUB.

One-time platform setup (Aventora ops)

These steps are done once per Hub deployment, not per customer tenant.

This layer is not optional. Account- and user-level API keys identify whose data is accessed, but FUB also requires the calling system to identify itself on every API call. Without FUB_SYSTEM_KEY, the Hub builds no FUB sync configuration at all — contact sync silently stays off, tag webhooks are rejected, and the connection test fails with FUB_SYSTEM_KEY is not configured on the Hub server.

Register Aventora as a FUB system — follow FUB’s integration guide.
Set Hub environment variables (Engagement Hub .env):

Variable	Required	Purpose
`FUB_SYSTEM`	Yes (defaults to `Aventora`)	Registered system name; sent as `X-System` header on every FUB API call
`FUB_SYSTEM_KEY`	Yes	System key from FUB registration. Sent as `X-System-Key` on every FUB API call; verifies tag-webhook signatures (`FUB-Signature` HMAC); final fallback for the embed secret. All FUB features are disabled without it
`SERVER_URL`	For webhooks	Public Hub URL (e.g. `https://phone.aventora.ai`); used only for FUB webhook registration
`FUB_EMBEDDED_APP_SECRET`	No	Platform-wide embed iframe secret for the single-contact app when tenants share one Aventora FUB app. Falls back to `FUB_SYSTEM_KEY` if unset; per-tenant `fub_embedded_app_secret` overrides both
`FUB_CAMPAIGN_EMBEDDED_APP_SECRET`	No	Platform-wide embed secret for the campaign (Smart List) app. FUB issues a distinct secret per app registration — set when it differs from the single-contact secret
`INTERNAL_START_URL`	No	Loopback for internal `/start` (default `http://127.0.0.1:{PORT}`). Do not point this at `SERVER_URL`

Production note: If embed starts fail with Integration internal /start failed / Name or service not known, the Hub was likely using SERVER_URL for loopback. Use default loopback or set INTERNAL_START_URL=http://127.0.0.1:8010. Keep SERVER_URL for public webhooks only.

Tenant settings (Aventora Admin)

In Aventora Admin → Account settings → CRM, set CRM provider to Follow Up Boss.

Setting	What it does
FUB_API_KEY	API key from FUB Admin → API (HTTP Basic username). Owner/admin key recommended if using tag webhooks. Default for all agents unless overridden per user.
Sync contacts (`fub_sync_contacts`)	When on: Hub resolves/creates FUB contacts and logs calls, messages, and notes on completion. Required for activity sync and Smart List campaigns.
FUB_START_CALL_TAG	Optional. When this tag is added to a person in FUB, Hub starts an outbound engagement (requires FUB webhook — see Tag-triggered outreach).
FUB_EMBEDDED_APP_SECRET	Secret from your single-contact FUB embedded app registration. Leave blank if your org uses the platform-wide Aventora FUB app (`FUB_EMBEDDED_APP_SECRET` on Hub).
FUB_CAMPAIGN_EMBEDDED_APP_SECRET	Secret from your campaign (Smart List) FUB embedded app registration. FUB issues a different secret per app — set this when it differs from the single-contact secret.

After saving, use Test connection to validate the API key. The test requires FUB_SYSTEM_KEY on the Hub server.

Embedded app URLs (shown in admin; register these in FUB Admin → Embedded Apps):

App	URL (US)	URL (Canada)
Single contact	`https://phone.aventora.ai/integration/followupboss/embed`	`https://phone.aventora.ca/integration/followupboss/embed`
Smart List campaign	`https://phone.aventora.ai/integration/followupboss/campaign`	`https://phone.aventora.ca/integration/followupboss/campaign`

For Track B (separate FUB accounts), append the tenant slug:
…/embed?domain_name=fub-test and …/campaign?domain_name=fub-test.

Embed secret resolution order (candidates tried in order until the signature verifies):

App	Order
Single contact	account `fub_embedded_app_secret` → Hub `FUB_EMBEDDED_APP_SECRET` → Hub `FUB_SYSTEM_KEY`
Campaign	account `fub_campaign_embedded_app_secret` → account `fub_embedded_app_secret` → Hub `FUB_CAMPAIGN_EMBEDDED_APP_SECRET` → Hub `FUB_EMBEDDED_APP_SECRET` → Hub `FUB_SYSTEM_KEY`

Per-user settings (Aventora Admin)

Open User account settings for each agent who will use embedded apps.

Setting	When to set
default_broker_phone / display_number	Agent’s outreach phone. Must match the phone on that agent’s FUB user profile (the number FUB sends when they open the embed).
fub_api_key	Agent’s own FUB API key. Required in Track B; optional in Track A if agents share the brokerage key.
fub_embedded_app_secret	Only if that agent registered embedded apps with their own FUB app secrets (Track B hybrid setups).

Each agent must exist as a domain user on the tenant. If FUB does not send user.phone in embed context, the Hub cannot map the agent and falls back to account-level API key and default broker phone.

Register embedded apps in FUB

App name (example)	Purpose	URL
Aventora	Call or message one contact from a person record	Single-contact embed URL above
Aventora Campaign	Bulk outreach from a Smart List	Campaign embed URL above

Each app registration gets its own secret from FUB. When you save an embedded app, FUB shows you a secret key for that app — the two apps will have different secrets. Record both and store them in Aventora (tenant settings fub_embedded_app_secret and fub_campaign_embedded_app_secret, or the platform-wide Hub equivalents — your Aventora admin confirms which).

Agents see these apps in FUB after they are saved. The apps run in a sidebar iframe on the person record (single contact) or as a standalone panel (campaign). There is no FUB modal API — the Hub uses an inline form inside the iframe.

Two deployment tracks

Most teams fit one of these models:

Track	Best for
Track A — Shared FUB brokerage	One FUB account for the whole team; agents log in as themselves under that brokerage
Track B — Separate FUB account per agent	Each agent owns their own FUB subscription

Question	Track A	Track B
One FUB subscription for the team?	Yes	No — each agent has their own
Shared contact database?	Yes	No
Who installs embedded apps?	Brokerage FUB admin, once	Each agent in their own FUB
FUB API key in Aventora	One default + optional per user	Required per user
Link tenant to FUB	FUB brokerage `account.domain` = tenant slug (e.g. `fub-test`)	Embed URL always includes `?domain_name=fub-test`

You can mix ideas (e.g. shared brokerage with per-user API keys). Talk to your Aventora admin for hybrid setups.

Track A — Shared FUB brokerage

Use this when the whole team works under one Follow Up Boss brokerage and agents have their own logins inside that account.

A1 — Link the brokerage to Aventora

Step 1: Confirm the tenant name

Your Aventora tenant slug is fub-test. Use this name consistently in admin and with your Aventora team.

Step 2: Match FUB to Aventora

In Follow Up Boss (brokerage admin):

Open brokerage / account settings.
Set the brokerage domain (or equivalent identifier) to fub-test so it matches your Aventora tenant (accounts.domain_name).

If these names do not match, embedded apps may not connect to the right tenant.

Step 3: Turn on FUB on the tenant

In Aventora Admin → Account settings → CRM for fub-test:

Set CRM provider to Follow Up Boss.
Turn on Sync contacts.
Add the brokerage FUB API key (FUB Admin → API).
Save and run Test connection.

Step 4: Register embedded apps (once, brokerage FUB admin)

In FUB Admin → Embedded Apps, add Aventora and Aventora Campaign using the URLs from Tenant settings.

A2 — Set up each agent (u1 and u2)

Repeat for u1, then u2.

Step 5: Agent exists on Aventora

Each agent must be a user on tenant fub-test.

Step 6: Set each agent’s outreach phone

In Aventora Admin → User account settings:

Select u1 (then u2).
Set broker / outreach phone (default_broker_phone or display_number).
This number must match the phone on that agent’s FUB user profile.

u1 and u2 must use different phones for separate caller ID and attribution.

Step 7 (optional): Personal FUB API key per agent

Only if an agent uses their own FUB API key instead of the brokerage default:

In User account settings, add their FUB API key.
Save.

If skipped, both agents use the brokerage key; outreach is still separated by phone.

Step 8: Agents in FUB

In Follow Up Boss:

u1 and u2 each have their own FUB login under the same brokerage.
Profile phone matches Step 6.
They can open contacts and Smart Lists they are allowed to use.

A3 — Running outreach (Track A)

See Day-to-day operations below.

A4 — Verify (Track A)

Check	u1	u2
Opens Aventora on a test contact	☐	☐
Test call uses their phone / caller ID	☐	☐
Activity appears on the FUB person	☐	☐
Campaign from their Smart List runs under their identity	☐	☐

Track B — Separate FUB account per agent

Use this when u1 and u2 each have their own FUB subscription — there is no shared brokerage. They still share one Aventora tenant (fub-test) for calls and AI.

How this model works

System	What is shared	What is per agent
Aventora	One tenant (`fub-test`)	Phone, FUB API key, optional embed secret
FUB	Nothing — separate accounts	Contacts, Smart Lists, login, API key

Each agent’s embed apps must tell Aventora to route to tenant fub-test via ?domain_name=fub-test in the embed URLs, even though their FUB accounts are different.

B1 — Set up the Aventora tenant (once)

Step 1: Confirm tenant `fub-test`

Admin ensures tenant fub-test exists and FUB integration is enabled (Sync contacts on).

Step 2: Tenant CRM settings

In Aventora Admin → Account settings → CRM for fub-test:

CRM provider: Follow Up Boss.
Sync contacts: on.
Default brokerage FUB API key: optional placeholder — each agent’s own key (Step B5) does the real work.

You do not need to match a single FUB brokerage domain to fub-test in this track.

Step 3: Get embed URLs for agents

Use embed URLs that include the tenant:

https://phone.aventora.ai/integration/followupboss/embed?domain_name=fub-test
https://phone.aventora.ai/integration/followupboss/campaign?domain_name=fub-test

(Canada: replace host with phone.aventora.ca.)

Every agent pastes these same URLs into their own FUB Admin.

B2 — Set up each agent (u1 and u2)

Repeat for u1, then u2.

Step 4: Agent on Aventora

u1 (then u2) is a user on tenant fub-test.

Step 5: Connect the agent’s own FUB

In Aventora Admin → User account settings for u1:

Add u1’s FUB API key (from u1’s FUB → Admin → API). Required in this track.
Set u1’s outreach phone.
If u1 registered embedded apps with their own secrets, add the embed secret (admin will confirm).

Repeat for u2 with u2’s API key and phone.

Step 6: Install apps in the agent’s own FUB

u1 logs into their Follow Up Boss (not u2’s):

FUB Admin → Embedded Apps.
Add Aventora and Aventora Campaign — URLs from Step B3, including domain_name=fub-test.

u2 repeats in their own FUB account.

Step 7: Phone alignment

u1’s FUB profile phone = outreach phone in Aventora for u1. Same for u2.

B3 — Verify (Track B)

Check	u1	u2
Apps installed in their own FUB	☐	☐
Their own FUB API key in Aventora user settings	☐	☐
Test call from embed uses their phone	☐	☐
Sync appears in their FUB only	☐	☐
u1 does not see u2’s contacts in embed	☐	☐

Day-to-day operations

Ways to start outreach

Method	Per-agent identity	Best for
Embedded app — single contact	Yes	Agent calls/messages one person from their FUB record
Embedded app — campaign	Yes	Agent bulk-outreaches a Smart List
Tag on person	No (tenant-level)	Automation when a tag is added in FUB
Hub API	No	Middleware, custom integrations

Single contact (embedded app)

Agent logs into FUB as themselves.
Opens a person with a valid phone (or email for email channel).
Opens the Aventora embedded app in the sidebar.
Chooses call type, channel, and instruction → Start.

The Hub reads the contact phone from FUB, starts the engagement, and syncs activity back to that person under the agent’s identity.

Call types (embed): Informational, Appointment booking, Confirmational, Conversational.

Channels (single-contact embed): Phone, SMS, WhatsApp message, WhatsApp voice, Chat, Email.

Bulk Smart List campaign (embedded app)

Agent logs into FUB as themselves.
Opens Aventora Campaign (sidebar or pinned app). No open person record is required.
Picks a Smart List (created and managed in FUB as usual).
Sets channel, call type, and instruction → Start campaign.

The Hub paginates all people in the list, queues engagements with source_system=followupboss, and returns batch/queued/skipped counts.

Channels (campaign embed): Phone, SMS, Email only. People without a valid phone (or email for email channel) are skipped.

Requirements: Sync contacts on, valid fub_api_key (lists people via FUB API), Hub call-management API key on the account for billing/submit.

Note: FUB Smart List campaigns are started from the embedded app inside Follow Up Boss. CSV bulk upload from Aventora Admin is a separate flow — see BULK_CALL_CSV_GUIDE.md.

Tag-triggered outreach

For tenant-level automation (not per-agent):

Set FUB_START_CALL_TAG in account settings (e.g. Aventora Call).
Register a FUB webhook for peopleTagsCreated pointing to:
```
{SERVER_URL}/integration/followupboss/webhook/{domain_name}
```
Example: https://phone.aventora.ai/integration/followupboss/webhook/fub-test

Registration options:
- FUB Admin — add the webhook manually in FUB.
- Hub API — after saving settings, call the connection test with "register_fub_webhook": true (Aventora ops / integrators).
When the tag is added to a person, Hub fetches the person, reads the primary phone, and starts an outbound engagement.

Webhook requests are verified via the FUB-Signature header (HMAC-SHA256 of base64-encoded body using FUB_SYSTEM_KEY).

What syncs back to FUB

When Sync contacts is enabled (fub_sync_contacts=true):

At call start

Hub looks up the person by phone/email (GET /v1/people). If missing, creates the contact via POST /v1/events (preferred over creating people directly).

During and after the engagement

As transcript rows are recorded, the Hub syncs unsynced messages to FUB:

Hub channel	What appears in FUB
SMS, WhatsApp message (`sms`, `wmsg`)	Notes with channel-labeled subject and inbound/outbound direction
Chat, email	Notes with channel-labeled subject
Phone, WhatsApp voice (`phone`, `wvoice`)	Call log on completion (`POST /v1/calls`) with summary, outcome, and duration

Initial engagement.created events are not synced to FUB.

Call outcome mapping

Hub outcome	FUB call outcome
`no_answer`	No Answer
`voicemail`	Left Message
`busy`	Busy
`invalid_phone`, `bad_number`	Bad Number
`connected`, `delivered`, `completed`	Interested
`not_interested`	Not Interested

Other Hub outcomes may map to FUB-native outcome labels when they match FUB’s allowed values.

What not to use for per-user outreach

These flows run at tenant level, not as a specific FUB agent:

Starting calls by adding a configured tag in FUB (tag webhook)
API / middleware starts that do not include embed context or acting user
POST /integration/followupboss/start-from-person without per-user context

For u1 and u2 to keep separate identity, use the embedded apps while logged into FUB as themselves.

Troubleshooting

Problem	What to check
Embed says domain not found	Track A: FUB brokerage domain matches tenant slug. Track B: embed URL includes `?domain_name=your-tenant`.
Wrong caller ID or shared identity	Agent phone in Aventora user settings matches FUB profile; agents use embed while logged in as themselves.
Contacts or Smart Lists missing	Track B: that agent’s own FUB API key in user settings. Track A: agent has access in shared FUB.
Embed won’t open / unauthorized	Embed secret matches Aventora expectations. Single-contact app: `fub_embedded_app_secret` / `FUB_EMBEDDED_APP_SECRET`. Campaign app: `fub_campaign_embedded_app_secret` / `FUB_CAMPAIGN_EMBEDDED_APP_SECRET` — FUB issues a different secret per app, so check you stored the right one for the failing app.
Activity not in FUB	Sync contacts enabled; connection test passed; person has matching phone/email.
Campaign queues nothing	Smart List has people with valid phone (or email for email channel); sync contacts and API key set.
Tag webhook does not start calls	`FUB_START_CALL_TAG` set; webhook registered to correct `{SERVER_URL}/integration/followupboss/webhook/{domain_name}`; `FUB_SYSTEM_KEY` on Hub.
Embed start fails internally	Hub `INTERNAL_START_URL` or loopback — see One-time platform setup.
CRM connection test fails	Valid FUB API key; Hub has `FUB_SYSTEM_KEY`; save settings before test if using masked key in UI.

Quick checklists

Track A — shared brokerage (`fub-test` + u1 + u2)

☐ FUB brokerage domain = fub-test
☐ Tenant CRM: Follow Up Boss, Sync contacts on, brokerage API key
☐ Both embedded apps registered once in brokerage FUB
☐ u1 & u2 on Aventora with outreach phones matching FUB profiles
☐ (Optional) per-user FUB API keys
☐ Connection test passed
☐ Each agent tests single contact + campaign from embed as themselves

Track B — separate FUB accounts (`fub-test` + u1 + u2)

☐ Tenant fub-test on Aventora, Sync contacts on
☐ Embed URLs include ?domain_name=fub-test
☐ u1 & u2 on Aventora with own FUB API keys and phones
☐ Each agent installs both apps in their own FUB
☐ Phones match FUB profile ↔ Aventora user settings
☐ Connection test passed (per agent key if testing user-scoped API)
☐ Each agent tests single + bulk; CRM data stays in their own FUB

Optional tag automation

☐ FUB_START_CALL_TAG set in tenant CRM settings
☐ FUB webhook peopleTagsCreated → Hub webhook URL
☐ Test tag on a person with a valid primary phone

Appendix: API & integrators

Canonical reference: ENGAGEMENT_HUB_START_API.md — full /integration/start and /start documentation (phone, SMS, email with email_body_html, templates, lifecycle).

For middleware or custom automation (tenant-level, not per-agent embed context). Hub base URL examples: https://phone.aventora.ai (US), https://phone.aventora.ca (Canada). Authenticate with the account call-management API key — see API_SECURITY_MODEL.md.

Start from FUB person ID

POST /integration/followupboss/start-from-person
Authorization: Bearer {call_management_api_key}
Content-Type: application/json

{
  "domain_name": "fub-test",
  "person_id": "12345",
  "type": "informational",
  "instruction": "Optional call script",
  "channel": "phone"
}

Generic integration start

POST /integration/start
Authorization: Bearer {call_management_api_key}
Content-Type: application/json

{
  "phone_number": "+14165550000",
  "domain_name": "fub-test",
  "source_record_id": "12345",
  "source_org_id": "fub-test",
  "source_system": "followupboss",
  "type": "informational"
}

Connection test (includes optional webhook registration)

POST /account-settings/test-crm-connection
{
  "domain_name": "fub-test",
  "crm_sync_provider": "followup_boss",
  "fub_api_key": "...",
  "fub_sync_contacts": true,
  "register_fub_webhook": false
}

External references

Follow Up Boss API reference
Hub code map: Aventora-Assistant — services/crm_sync/fub_client.py, server/routers/integration_followupboss.py
Technical env/API appendix: Aventora-Assistant/docs/followupboss-integration.md

Table of contents​

How the integration works​

Where settings live (three layers)​

Who does what​

Prerequisites​

One-time platform setup (Aventora ops)​

Tenant settings (Aventora Admin)​

Per-user settings (Aventora Admin)​

Register embedded apps in FUB​

Two deployment tracks​

Track A — Shared FUB brokerage​

A1 — Link the brokerage to Aventora​

Step 1: Confirm the tenant name​

Step 2: Match FUB to Aventora​

Step 3: Turn on FUB on the tenant​

Step 4: Register embedded apps (once, brokerage FUB admin)​

A2 — Set up each agent (u1 and u2)​

Step 5: Agent exists on Aventora​

Step 6: Set each agent’s outreach phone​

Step 7 (optional): Personal FUB API key per agent​

Step 8: Agents in FUB​

A3 — Running outreach (Track A)​

A4 — Verify (Track A)​

Track B — Separate FUB account per agent​

How this model works​

B1 — Set up the Aventora tenant (once)​

Step 1: Confirm tenant fub-test​

Step 2: Tenant CRM settings​

Step 3: Get embed URLs for agents​

B2 — Set up each agent (u1 and u2)​

Step 4: Agent on Aventora​

Step 5: Connect the agent’s own FUB​

Step 6: Install apps in the agent’s own FUB​

Step 7: Phone alignment​

B3 — Verify (Track B)​

Day-to-day operations​

Ways to start outreach​

Single contact (embedded app)​

Bulk Smart List campaign (embedded app)​

Tag-triggered outreach​

What syncs back to FUB​

At call start​

During and after the engagement​

Call outcome mapping​

What not to use for per-user outreach​

Troubleshooting​

Quick checklists​

Track A — shared brokerage (fub-test + u1 + u2)​

Track B — separate FUB accounts (fub-test + u1 + u2)​

Optional tag automation​

Appendix: API & integrators​

See also​

Table of contents