Salesforce technical integration guide

This guide describes what Revial does inside your Salesforce org, so you can approve, configure and later audit the integration. For connecting step by step see Connecting Revial to Salesforce; for every field read and written see What Revial syncs with Salesforce.

1. What you are approvingCopy Anchor Link

Revial connects as an OAuth client over the Salesforce REST API v60.0 and SOQL. Authorisation is OAuth 2.0 authorisation code with PKCE (S256), completed by one of your users in a browser.

Because access is delegated, object permissions, field-level security, sharing rules and record ownership all apply unchanged. Records the connecting user cannot see do not reach Revial.

2. What your admin has to doCopy Anchor Link

For most orgs nothing — a licensed user clicks Connect with Salesforce, signs in and allows access. Admin involvement is needed when:

There is no package to install, no metadata to deploy and no Apex.

3. Authentication and token modelCopy Anchor Link

Login host. Only Salesforce-operated domains are accepted (salesforce.com, force.com, salesforce.mil, cloudforce.com, sfcrmapps.cn); anything else is rejected rather than defaulted. The host chosen at connect time is stored and used for every refresh, so a sandbox connection keeps working after its first token expiry. Use the sandbox's own host — the generic test.salesforce.com is accepted, but can land a signed-in user on a different org. The returned instance URL must be HTTPS on *.salesforce.com or *.force.com.

Token storage. One connection per Revial organisation and provider. Access and refresh tokens are encrypted at rest (AES-256-GCM). Revial also stores the instance URL, the connecting user's ID, email and name from userinfo, the login host and per-connection settings.

Refresh. Up to three attempts with a short backoff. On invalid_grant or a 401 the connection is marked as needing re-authentication and an organisation admin gets an in-app notification — Revial stops rather than retrying against your org. If Salesforce returns a new refresh token (rotation), it is stored and the old one is discarded.

Who may connect on the Revial side. An organisation owner or admin on a plan with the CRM integration. The flow is rate-limited and protected by a single-use state and PKCE verifier held server-side, valid for five minutes. While a Salesforce connection is connected, a second one is refused; a connection in an error state is refreshed in place and keeps its settings.

4. The connecting user and required permissionsCopy Anchor Link

Everything happens as the one connecting user. We recommend a dedicated, licensed integration user — it survives staff turnover and keeps record ownership predictable. A standard sales profile normally grants what is needed.

The table is a default, not a minimum. Withhold Task create and summaries stop being filed; withhold field-level Edit and mapped fields are not written.

Missing permissions. A 403 INSUFFICIENT_ACCESS on Event, Task or EmailMessage skips that object, completes the rest of the sync and flags the connection for attention. A 403 on Accounts, Contacts, Leads, Opportunities or Notes fails that part of the sync. If field-level security hides one of Revial's optional fields (such as AnnualRevenue, Phone or Title), Revial drops the field and retries; a hidden required field fails the query.

5. What Revial readsCopy Anchor Link

Accounts, Contacts, unconverted Leads (IsConverted = false), Opportunities, active OpportunityStage records, OpportunityContactRole, Events, Tasks (excluding TaskSubtype Email and ListEmail), EmailMessage including the full TextBody with EmailMessageRelation, and classic Notes. Queries use explicit field lists and follow nextRecordsUrl for pagination. The full field list is in What Revial syncs with Salesforce.

Outside the sync, Revial may also read a User by email, an Opportunity's or Contact's AccountId, Events and EventRelation (Visit Reports only), and object describe metadata for the field-mapping screen.

Revial does not read Cases, Campaigns, Chatter, Files or ContentDocument, Lightning notes, record types or field history.

6. What Revial writesCopy Anchor Link

Records are created with POST /sobjects/{Object}/ and updated with PATCH /sobjects/{Object}/{id}.

Summaries are Tasks rather than Notes because a completed Task appears on the activity timeline where sellers look. Revial never deletes records and never changes metadata.

7. Field mappingsCopy Anchor Link

Admins map Revial summary fields and custom extraction fields to fields on Account, Contact and Opportunity in Organization → CRM Settings → Property Mapping. Fields that already have a value are left alone unless the mapping is set to overwrite. Updates are sent as one batch PATCH; if it is rejected, each field is retried on its own and failures are reported per field.

Stages are normalised by keyword (qualification, needs analysis, proposal, negotiation); won and lost come from IsClosed and IsWon, and anything else becomes "other".

8. Sync cadence and API consumptionCopy Anchor Link

Revial's calls count against your org's daily API request allocation.

1. First sync — a full pull per object, newest first, up to 50,000 records per object. Opportunities are limited to open ones plus those modified in the last 12 months.
2. Later syncs — roughly every hour, WHERE LastModifiedDate > {watermark} in ascending order, so volume tracks changed records rather than org size.
3. Order — accounts → contacts → leads → stages → opportunities → activities → notes, each as a separate job; a transient failure retries on the next run.

OpportunityContactRole and EmailMessageRelation lookups are batched at 200 IDs per query. Data calls time out after 30 seconds.

Deletions are not detected. LastModifiedDate filtering does not return deleted records, and Revial does not reconcile them: a record deleted in Salesforce stays in Revial's copy until you disconnect.

Record cap. If an object has more than 50,000 changed records in one run, the remainder is skipped and not picked up later.

9. Meeting-to-CRM matchingCopy Anchor Link

When a meeting is linked to Salesforce records, Revial tries in order and the first match wins:

1. Direct — record IDs already attached to the meeting.
2. Sticky — the open opportunity the meeting is already linked to.
3. Email — attendee emails → contacts → their opportunities, scored.
4. Domain — company by website or email domain (no opportunity).
5. Company name — name match (no opportunity).

Opportunity scoring favours open deals, the attendee being the primary contact, other attendees on the deal, title similarity, later stages and recent activity. Closed opportunities are excluded. Free-email domains (Gmail, Outlook and similar) are ignored for company matching, so a meeting with only personal addresses may not attach to an account.

10. Security, limits and failure behaviourCopy Anchor Link

• API version: REST and SOQL v60.0.
• Timeouts: 30 seconds per data call.
• Least privilege: three scopes, no admin rights, no app-only access.
• Secrets: client credentials server-side only; tokens encrypted at rest.
• Partial permissions: see section 4.
• Pagination safety: a per-object ceiling of 50,000 records per run.
• Data storage: Revial stores the synced records together with the raw API response for each. They are deleted when you disconnect.

11. Auditing and disconnectingCopy Anchor Link

To see what Revial has done in your org:

• Setup → Connected Apps OAuth Usage — Revial's app, who authorised it, and per-user revoke.
• Setup → Login History — filter by the connecting user.
• API usage — attribute request volume to the connecting user.
• Records written by Revial — completed Tasks (and Visit Reports, if configured) created by the connecting user.

To disconnect:

• In Revial — Disconnect on the Salesforce card. Revial deletes its synced copy and the stored tokens. It does not call Salesforce's revoke endpoint.
• In Salesforce — revoke the app under Connected Apps OAuth Usage, or deactivate the connecting user. Revial receives invalid_grant, flags the connection and stops.

Neither removes Tasks or records Revial already wrote.

12. TroubleshootingCopy Anchor Link

Appendix A — Visit Reports (custom object)Copy Anchor Link

Some organisations file meeting outcomes into a custom object such as Visit_Report__c, linked to the calendar Event. Revial supports this through per-connection configuration set up by Revial — no code change in your org.

What you supply:

How the push works:

1. Match the Event — an Event starting within the window, linked to a contact resolved for the meeting (also through EventRelation); the closest start time wins. An Event picked by the seller is used directly.
2. Resolve the Account — the seller's choice, else the Event's WhatId if it is an Account, else that Opportunity's Account, else the Event contact's Account.
3. Create the record with the configured fields.
4. Update the Event — the back-link field and, if configured, the owner and stakeholder fields. Setting the owner field can reassign the Event's owner.

Revial never creates the Event. Distinct outcomes are reported: no_contacts_resolved (no attendee matched a contact — check the CRM sync), no_event_matched (no Event in the window — check your calendar sync), no_account_on_event, and linkFailed (report created, Event update failed — grant Edit on the Event field and fix the link by hand). A created report is never rolled back.