JavaScript SDK

The Outreach client extensibility SDK helps your web-widget extensions to interact with the Outreach client. It is available as NPM package.

To begin using the SDK, install the package...

Copy
Copied
npm config set @getoutreach:registry https://npm.pkg.github.com
npm install @getoutreach/extensibility-sdk
...and call the init() method:
Copy
Copied
import extensibilitySdk from "@getoutreach/extensibility-sdk";
// ...
const outreachContext = await extensibilitySdk.init();
The init method ensures that your extension is able to run within the Outreach host application. It returns a promise resolving with the OutreachContext which contains contextual data configured to be passed to your extension from Outreach client.It is important to call the init method as soon as possible. Best time to do this is the DOMContentLoaded event or its equivalents in the framework of your choice. If your application redirects for any reason make sure to perform the redirects after the promise returned from init resolves.

Using SDK in extensions

When implementing shell, tab or tile extension you only need to call the init() method when your extension finishes loading. Using any further SDK methods is optional.Text editor extension is additionally expected to return the HTML string to be embedded back into the text editor. Use the enhanceTextEditor() method to return the string and optionally the adjusted message subject.

Extensibility SDK reference

extensibilitySdk object exposed by the npm package contains an instance of the SDK. For convenience extensibilitySdk is also exposed on window.outreach global object. extensibilitySdk provides following static methods:

environment()

Allows dynamically hiding or showing the right sidebar of the Outreach host application.

Copy
Copied
extensibilitySdk.environment({ fullWidth: false });

init()

initializes the SDK and returns a Promise resolving to OutreachContext objectYou have to call this function and wait for the promise to resolve before any other interaction with the SDK. You should call this function as early as possible for example in the DOMContentLoaded event or equivalent.
Copy
Copied
// cxt: OutreachContext
const cxt = await extensibilitySdk.init();

The OutreachContext object

extensibilitySdk.init() call returns a promise that resolves with the OutreachContext object. This object carries all the Outreach data available for your extension:
  • locale - (e.g. en) locale currently used in the host application.
  • theme - design theme of the host application. Possible values are Light or Dark.
  • account - account data configured for your extension.
  • user - currently logged-in user data configured for your extension.
  • organization - organization data configured for your extension.
  • opportunity - opportunity data configured for your extension.
  • prospect - prospect data configured for your extension.
  • config - user-specific extension configuration (if any).
  • host - info about the host application.
user, organization, account, opportunity and prospect object contain a subset of the corresponding data retrievable by Outreach API.

User

Carries information about the currently logged-in user.

  • usr.email - The email address of the user
  • usr.fname - The first name of the user
  • usr.id - User ID.
  • usr.lname - The last name of the user.
  • usr.name - The full name of the user.
  • usr.role
  • usr.tit - The user's job title (e.g., "Staff Accountant").
  • usr.uname - A reader-friendly unique identifier of the user.
  • usr.csfX - (where X is in an integer number) the value of the corresponding (1-5) user's custom fields.

Organization

Carries information about the organization of the currently logged-in user.

  • org.cur - Default organization currency.
  • org.id - Organization ID.
  • org.logo - Organization logo url.
  • org.name - Organization full name.
  • org.short Organization short name.

Account

For extensions that show up as a tab on the account detail page following account data can be made available:

  • acc.id - ID of the account.
  • acc.cstmId - a custom ID for the account, often referencing an ID in an external system.
  • acc.desc - description of the account.
  • acc.dmn - account company domain.
  • acc.extid - external ID of the Outreach prospect in the external system as mapped via plugin
  • acc.extprvd - prospect provider name (Salesforce, Dynamics, etc.)
  • acc.loc - the company’s primary geographic region (e.g. "Eastern USA").
  • acc.name - the name of the company (e.g. "Acme Corporation").
  • acc.tags - a list of tag values associated with the account (e.g. ["Enterprise", "Tier 1"]).
  • acc.ext - external account information.
  • acc.csfX (where X is in an integer number) the value of the corresponding (1-150) account's custom field.

Opportunity

For extensions that show up as a tab on the opportunity detail page following account data can be made available:

  • opp.amnt - the amount the opportunity is worth.
  • opp.desc - a description of the opportunity.
  • opp.ecrat - the date the opportunity was created in the external system.
  • opp.extid - retrieving external id of the Outreach prospect id in the external system.
  • opp.extprvd - retrieving prospect provider name (Salesforce, Dynamics, etc.)
  • opp.id - opportunity ID.
  • opp.name - the name of the opportunity.
  • opp.ntsp - the next step to take for the opportunity.
  • opp.prob - the chances of the opportunity succeeding are represented as a percentage.
  • opp.stage - the stage of the opportunity.
  • opp.tags - tags associated with the opportunity.
  • opp.type - the type of opportunity.
  • opp.ext - external information associated with the opportunity.
  • opp.csfX (where X is an integer number) the value of the corresponding opportunity's custom field.

Prospect

For extensions that show up as a tab on the prospect detail page following account data can be made available:

  • pro.accnme - Prospect account name.
  • pro.accdmn - Prospect account domain.
  • pro.adrcity - city of the prospect.
  • pro.adrcntry - country of the prospect.
  • pro.adrstate - state of the prospect.
  • pro.adrstreet - street address of the prospect.
  • pro.adrstreet2 - street address (2nd line) of the prospect.
  • pro.adrzip - postal code of the prospect.
  • pro.avail - the date and time the prospect is available to contact again.
  • pro.comp - the name of the prospect company. If associated with an account, this is the name of the account. (e.g. Acme International).
  • pro.emails - a list of email addresses associated with the prospect.
  • pro.loc - the locality of the prospect's company.
  • pro.extid - external ID of the Outreach prospect in the external system as mapped via plugin
  • pro.extprvd - prospect provider name (Salesforce, Dynamics, etc.)
  • pro.id - the prospect id.
  • pro.tags - list of tag values associated with the account (e.g. ["Interested", "2017 Expo"]).
  • pro.tzone - the prospect's current timezone, preferably in the IANA format (e.g., "America/LosAngeles").
  • pro.title - the title of the prospect.
  • pro.ext - external information associated with the prospect.
  • pro.csf1X (where X is an integer number) the value of the (1-150) prospect's custom field.

Email

For text editor extensions the following data can be made available:

  • eml.to - array of names and email addresses specified in TO field for the current message.
  • eml.cc - array of names and email addresses specified in CC field for the current message.
  • eml.bcc - array of names and email addresses specified in BCC field for the current message.
  • eml.subj - message subject.

navigate()

Navigates to a page within Outreach. Currently, supports navigating to Opportunity, Prospect, and Account.

Copy
Copied
// Navigate to the overview page of an opportunity with id `123`:
extensibilitySdk.navigate(NavigationDestination.OPPORTUNITY, "123");

// Navigate to the opportunity extension with app identifier 'tasks'
extensibilitySdk.navigate(NavigationDestination.OPPORTUNITY, "123/tasks");

// Manipulate URL query parameters of the iframe hosting the extension
extensibilitySdk.navigate(NavigationDestination.OPPORTUNITY, "123", {
  abc: "1",
  xyz: "2",
});

extensibilitySdk.navigate(NavigationDestination.APP, "left-side-menu-hello");

notify()

Pops up a traditional Outreach message toast styled as info, warning, or error.

Copy
Copied
extensibilitySdk.notify({ type: "info", text: "Saved!" });

enhanceTextEditor(html: string, subject?: string)

For text editor extension. Allows you to place HTML content at the current cursor position in the rich text editor and update the subject (optional).

Only works if the application is rendered as part of Text Editor Extension.

Copy
Copied
extensibilitySdk.enhanceTextEditor("Hello!", "Welcome message");

Calling extensibilitySdk.enahnceTextEditor("", "") will cause the application window to close.

Copy
Copied
extensibilitySdk.enhanceTextEditor("", "");

onLoad()

If an extension fails to load within 2 seconds a warning message pops up. After 5 seconds error message is shown. You can override this behavior by implementing onLoad() handler yourself. Function will receive the LoadingContext as its only parameter.
Copy
Copied
interface LoadingContext {
  loadTime: number;
  readyTime: number;
}

extensibilitySdk.onLoad = (ctx: LoadingContext) => {
  // show custom UI, report to telemetry
};