How a Company Admin connects Salesforce CRM to Ricavi: the connection flow, which objects and fields are needed, what Ricavi writes back, and the controls available to you.
Who sets this up: the Company Admin. Sellers and Selling Managers do not need to do anything. The CRM connection appears to them as a read-only card during onboarding showing the connected provider name.
How long it takes: around 5-10 minutes, most of which is field mapping.
One CRM at a time
Ricavi supports Salesforce, HubSpot and Microsoft Dynamics. Only one CRM can be active per organisation at any time. Switching providers means disconnecting the current CRM first.
Before you begin
You are signed in to Ricavi as a Company Admin.
You have Salesforce credentials with permission to authorise a third-party application, and to read and write the objects listed in section 3.
You know which objects you want Ricavi to sync. Contacts, Opportunities and Activities can each be included or left out.
You have decided which fields should be eligible for AI-suggested updates (the whitelist) and which should never be touched (the blacklist).
1. Connect the CRM
Go to Company Configuration in Ricavi. You can also do this during onboarding; the flow is identical.
Open Company Configuration and start the CRM connection.
Select Salesforce as your CRM provider.
Complete the OAuth 2.0 authorisation prompt and sign in with your Salesforce account.
Configure field mapping (see section 4).
Select which CRM objects to sync (see section 2).
Confirm. The connection status appears in the Company Configuration panel.
Once connected, the integration shows one of three states:
Status | What it means |
Active | The connection is healthy and syncing. |
Error | Something has failed. Open the sync log to see the specific errors. |
Disconnected | No CRM is connected. Agentic action types that need a CRM will not be shown to Sellers. |
2. Choose which objects to sync
Ricavi syncs with three core Salesforce objects. Each one is selected during setup.
Object | What Ricavi uses it for | Direction |
Contacts | Buyer identification, stakeholder mapping, meeting attendee matching, buying committee tracking, single-threaded risk detection | Read + Write |
Opportunities (Deals) | Deal health scoring, pipeline management, forecasting, pre-call preparation, post-call sync, agentic actions | Read + Write |
Activities (Tasks / Events) | Call logging, follow-up task creation, activity tracking for stalled deal detection, engagement monitoring | Read + Write |
Leaving one out
Skipping an object limits related features. Without Activities, for example, Ricavi cannot detect stalled deals, because that trigger relies on activity dates.
3. Fields Ricavi reads
These are the minimum fields Ricavi needs to deliver pre-call preparation, deal health scoring, pipeline views, forecasting and AI coaching context. Fields marked Recommended are optional, but leaving them out reduces the quality of the output.
3.1 Opportunity fields
Salesforce field | What it powers | Required |
Opportunity Name | Deal identification across dashboard, pipeline, Action Hub and briefings | Yes |
Account Name | Pre-call preparation (auto-populates the Account field), deal grouping | Yes |
Stage | Pipeline Kanban view, deal stage tracking, stagnant stage detection (30-day trigger) | Yes |
Amount (Deal Value) | Pipeline value totals, forecast calculations, action prioritisation by deal value | Yes |
Close Date | Close Date Passed trigger, Close Date at Risk alert (7-day window), forecast views | Yes |
Opportunity Owner | Rep assignment, manager pipeline filtering, team analytics | Yes |
Probability | Baseline for AI forecast comparison, forecast delta calculations | Recommended |
Next Step | Pre-call context, coaching chat awareness, action suggestions | Recommended |
Forecast Category | Seller forecast view (High / Medium / Low mapping), forecast delta reporting | Recommended |
3.2 Contact fields
Salesforce field | What it powers | Required |
Contact Name | Meeting attendee identification, stakeholder mapping, coaching context | Yes |
Meeting matching, follow-up email actions, attendee identification | Yes | |
Title / Role | Buying committee coverage scoring, EDM identification, stakeholder map | Yes |
Account (Lookup) | Contact-to-deal association, single-threaded risk detection | Yes |
Phone | Call script actions, stalled deal revival (Step 3) | Recommended |
3.3 Activity fields
Salesforce field | What it powers | Required |
Subject | Activity log display, meeting list rendering | Yes |
Activity Date | Stalled deal detection (14-day inactivity trigger), timeline tracking | Yes |
Status | Open vs completed task tracking, Action Hub log | Yes |
Related To (Opportunity) | Linking activities to deals for health scoring and stall detection | Yes |
Description / Comments | AI context for coaching, pre-call preparation enrichment | Recommended |
4. Configure field mapping
Field mapping tells Ricavi which Salesforce field corresponds to each Ricavi data point. You set this up during CRM setup and can revisit it at any time.
Setting | What it does |
Field mapping | Maps each Ricavi data point to the corresponding Salesforce field. |
Object selection | Chooses which CRM objects are synced: Contacts, Opportunities, Activities. |
Field whitelisting | Only whitelisted fields are eligible for AI-suggested updates. |
Field blacklisting | Blacklisted fields are never suggested for update, which gives you an extra layer of data governance. |
Sync log | A full history of sync events, including errors, for monitoring and troubleshooting. |
If a mapping is missing
Where no mapping exists for a given field, Ricavi saves the data as a note on the Opportunity record instead of discarding it. Nothing is lost, but it will not be reportable as structured data.
5. What Ricavi writes back
Ricavi writes to Salesforce under two conditions: post-call sync and agentic actions. No data is written automatically. Every write requires the Seller to review and approve it first.
5.1 Post-call sync
Data written | Salesforce target | Details |
Deal Stage Change |
| AI-suggested stage progression based on call content |
Next Steps |
| Extracted from call discussion, editable before sync |
Call Log | Activity (Task) | Call date, duration and participants, linked to the Opportunity |
Contact / Stakeholder Updates | Contact fields | New contacts, or updated roles identified during the call |
Methodology Field Responses | Opportunity (custom fields) | Captured from the transcript against the active methodology, e.g. MEDDPICC fields |
Call Recording, Transcript & AI Summary | Opportunity (attachment) | Attached to the linked Opportunity record |
When a call ends, Ricavi generates AI-suggested CRM updates. The Seller reviews, edits and approves each update before it is pushed.
5.2 Deal Health fields
Ricavi creates nine custom field sets on the Opportunity object, auto-populated from call transcripts, emails and meeting notes. Two summary fields are also written back:
Custom field | Type | Description |
Deal Health Score | Number (0–100) | Composite score from the nine-category model below |
Deal Health Status | Picklist | Green (80–100), Amber (60–79), Red (below 60) |
The nine categories that feed the score:
Category | Weight | Critical gate |
1. Problem Statement Quality | 15 pts | Yes |
2. Discovery Brief / Post-Meeting Notes | 15 pts | Yes |
3. Business Impact & Business Case Evidence | 20 pts | Yes |
4. Buying Committee Coverage | 15 pts | No |
5. Internal "Project" Exists | 10 pts | No |
6. Proposal Process Quality | 10 pts | No |
7. Commercial & Budget Alignment | 10 pts | No |
8. Procurement / Vendor Path Clarity | 5 pts | No |
9. Mutual Action Plan to Decision | 10 pts | No |
How scoring works
Each category is scored 0 = Missing, 1 = Partial, 2 = Complete and validated with the buyer.
If any of categories 1, 2 or 3 scores 0, the deal is marked Red regardless of its total score. This shows as "Critical Gate Failed".
5.3 Agentic actions
Action type | Salesforce write | Details |
Update Deal Stage |
| AI-recommended stage with a plain-language reason |
Update CRM Records | Opportunity / Contact fields | Log Call, Add Notes or Update Fields, with a preview |
Create Follow-Up Task | Task (Activity) | Task name, due date, priority, notes |
Send Follow-Up Email | Activity (logged to CRM) | Email sent via the connected email integration and logged in Salesforce |
Create / Update Contact | Contact | New contact creation or existing contact field updates |
Create / Update Company | Account | Account record creation or updates |
Create / Update Deal | Opportunity | Opportunity record creation or updates |
Add Stakeholder | Contact Role on Opportunity | New stakeholder added to the deal’s contact roles |
Safeguard
Company Admins can whitelist and blacklist specific CRM fields for AI-suggested updates. Only whitelisted fields are eligible for suggestion; blacklisted fields are never suggested.
Action types that require a CRM connection are hidden entirely when no CRM is connected.
6. Deal health triggers
Ricavi monitors the deal data it reads from Salesforce and raises alerts against the conditions below. All thresholds are configurable by the Company Admin.
Trigger | Condition | Default | What happens |
At Risk | Deal Health Score drops below 60 | n/a | Deal card turns Red, Morning Briefing alert, agentic actions raised in Seller and Manager Action Hubs |
Watch | Score drops from Green to Amber | n/a | Watch flag, listed under "Deals to Watch" in the Morning Briefing |
Stalled Deal | No activity on the deal | 14 days | Revival Plan generated (Email, LinkedIn, Call Script) |
Stagnant Stage | Stage unchanged | 30 days | Agentic action to progress the deal |
Close Date Passed | Close date has passed | n/a | Agentic action to update and re-forecast |
Close Date at Risk | Close date within X days and deal is Amber or Red | 7 days | Flagged in the Morning Briefing and on the Manager dashboard |
EDM Engagement Gap | No contact with the Economic Decision Maker | 21 days | Agentic action to re-engage the EDM |
Single-Threaded Risk | Only one contact on the deal | n/a | Risk flag plus agentic action to request introductions |
7. Governance and safeguards
No automated writes. Every CRM update requires explicit Seller approval.
Admin-controlled scope. The Company Admin controls field whitelisting and blacklisting, object sync selection, and which agentic action types are available per user or team.
Full audit trail. The sync log holds a complete history of sync events, including errors.
Cross-tenant oversight. The Super Admin monitors integration health and data audit trails across tenants.
8. Troubleshooting
Symptom | What to check |
Status shows Error | Open the sync log in Company Configuration. It lists the individual sync events and the errors against them. |
Agentic actions are missing for Sellers | Action types that require a CRM are not displayed when no CRM is connected. Confirm the integration status is Active. |
Data is landing as notes instead of fields | No mapping exists for that field. Add the mapping in field mapping configuration. |
A field is never suggested for update | Check whether it has been blacklisted, or simply not whitelisted. Only whitelisted fields are eligible. |
Stalled deals are not being detected | Stall detection relies on activity dates. Confirm Activities are included in the synced objects. |
Need to start again | The Company Admin can disconnect the CRM connection at any time from Company Configuration. |
Common questions
Question | Answer |
Can we run two CRMs at once? | No. One CRM is active per organisation at any time. |
Do Sellers need to connect anything? | No. CRM connection is the Company Admin's responsibility. Sellers see a read-only card showing the connected provider. |
Will Ricavi change our data without asking? | No. Every write, post-call sync and agentic actions alike, requires the Seller to review and approve it. |
Can Sellers edit what Ricavi suggests? | Yes. Suggested updates are editable before they are approved and pushed. |
Can we stop Ricavi touching sensitive fields? | Yes. Blacklist them. Blacklisted fields are never suggested for update. |
Can we change the health score thresholds? | Yes. All trigger thresholds are configurable by the Company Admin. |