Overview

OAuth Connection
How the Integration Works
Data Permissions, Objects & Retention
Rate Limiting & Throttling

OAuth Connection

Nook users can connect their Nooks account to Salesforce via OAuth. For each connection, the Nooks service receives a token that is used to make calls to the Salesforce API.

Nooks requests the following scopes.

Access Analytics REST API resources (wave_api)
This allows Nooks to access and update Reports, Contacts, Leads, Accounts and other SFDC Objects when users update fields from the Nooks Dialer.
Access unique user identifiers (openid)
This allows Nooks to see the SFDC identifiers for Contacts, Leads and Accounts. We use this scope to enable directly linking to Salesforce from within the dialer. This enables Nooks's Account Research features, including surfacing
Manage user data via APIs (api)
This scope allows Nooks to log call Tasks when dialing from reports, so that activity is properly tracked and available within Salesforce. Some existing reports may not be configured to reflect Nooks activity; In this case, use the reporting from within Nooks via the Reporting tab.
Perform requests at any time (refresh_token, offline access)
This scope is required so that users don't have to log in to Salesforce every time they open Nooks.

These tokens follow the access roles and permissions granted to the connecting user. Users will only be able to access, view and objects within Nooks that they are already able to access within SFDC.

Occasionally, these API keys will expire and Nooks may prompt the user to re-connect.

For more details and documentation on Salesforce OAuth connections and the SFDC API: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_oauth_and_connected_apps.htm

How the Integration Works

Just-in-time Access

In order to ensure data is up-to-date from Salesforce, Nooks adopts a “just-in-time” access model to Salesforce data.

The below diagram shows how Nooks uses this access model to load contacts from a report, pull in context related to past Opportunities and log calls after they've been made.

Integrations Functionality

Nooks accesses data from Salesforce in two contexts:

Calling from Reports

The frontend client makes a request to Salesforce using its API to load the report as a list of Call Tasks. As the client performs calls on each of these call tasks, the client submits a request to log these requests to our call logging microservice.

This microservice handles logging this call for internal reporting as well as back to Salesforce for proper activity logging. Calls logged back to Salesforce use the standard Task object.

Salesforce Tasks do not include fields for call duration, call disposition or other details by default. Detailed analytics, transcripts and reporting links will be available as usual within Nooks's native call reporting.

Showing Opportunity / Account Fields

If an admin has configured Opportunity / Account fields to be displayed in Nooks, then the frontend client will request these from Salesforce upon task loading.

As tasks are loaded, Nooks will attempt to retrieve these preselected fields based on the SFDC AccountID provided by the Sales Engagement Platform (this is a metadata field on Outreach & Salesloft)

If no such ID field is available, Nooks will search for an exact match on Company to Account Name to try and find the related record.

Upon success, these fields will be visible within the Prospect Card view in the dialer.

Editing Salesforce Fields from the Dialer

Salesforce Data is read-only by default. If you would like to enable editing fields from Nooks (handy for fixing titles and updating info fields), managers can enable editing from the Settings menu under Integrations >> Salesforce.

Data Permissions, Objects & Retention

Permissions Model

Nooks uses the standard SFDC data models and inherits access roles from Salesforce. Custom fields will be retrieved based on user permissions; Nooks users will only be able to see fields that they are able to see on Salesforce itself.

List of SFDC Objects

Nooks interacts with the following standard objects in Salesforce. Nooks does not support custom objects at this time.

Object	Documentation Link
Lead	sforce_api_objects_lead
Contact	sforce_api_objects_contact
Account	sforce_api_objects_account
Opportunity	sforce_api_objects_opportunity
Report	sforce_api_objects_report
Task	sforce_api_objects_task
User	sforce_api_objects_user

What data does Nooks store?

Nooks generally uses a Just-In-Time model for interactions with Salesforce. As a result, no data from SFDC is stored on Nooks servers with 3 exceptions.

Nooks maintains a list of SFDC Users to support User Mapping settings.
These are not Contacts or Accounts, only Users of the integrated team.
Three fields are stored: UserId, Email and Name.
Nooks keeps track of SFDC Tasks created via its call logging microservices.
One field is stored: the associated SFDC TaskId for calls made from Nooks.
Nooks maintains a short-term cache of retrieved Fields for faster dialer loading and increased SFDC API efficiency by minimizing lookups.

Cached fields are limited to what is visible in the Dialer, and these fields are deleted from the cache as soon as the user loads a different sequence into the Dialer.

Rate Limiting & Throttling

Nooks will poll the Salesforce API hourly to keep track of how many API calls are available within a 24 hour period. If less than 20% of the API limit is available, Nooks will pause call logging and field retrieval until the next hour.

This is to ensure that Nooks does not cause you to exceed your Salesforce API call limit.

Salesforce Reports and Fields

Getting Started with Salesforce

Apollo Integration - Technical Doc

Outreach Integration - Technical Doc

Hubspot Integration - Technical Doc