Custom Range Integrations

Range integrates with other software to create suggested items for users to
add to their updates. If you would like to create suggestions from tools not currently integrated with Range, you can set up an incoming webhook to programmatically create suggestions.

Note: Workspaces can be configured to restrict who can create webhooks. If you do not have access please talk reach out to us or talk to your administrator.

Basic Flow

In general suggestions are created that reflect state changes that indicate work has happened: for example, a document was edited, a file was created, an issue opened, or a case closed.

Your integration can issue requests to the webhook whenever a state change happens that should trigger a suggestion. You should consider how suggestions should be de-duplicated and why they are being shown to the user.

The suggestion payload should be POSTed as JSON to the webhook endpoint issued via your workspace's integration settings (under Custom Range integrations).

{
  "email_hash": "462cdb844946306eb3a172a2274d91ec23897961",
  "is_future": true,
  "reason": "ASSIGNED",
  "dedupe_strategy": "UPSERT_PENDING",
  "attachment": {
    "source_id": "12345abc",
    "provider": "oncall",
    "provider_name": "ACME Oncall Tool",
    "html_url": "https://oncall.acme.corp/rotation/12345abc",
    "name": "Primary on call for ACME backend",
    "type": "LINK"
  }
}

The payload fields will be described in detail below.

Suggestion Assignment

The incoming webhook can assign suggestions to users in two ways via their Range user id or via a hash of their email. You can find user id's by looking at the URL of their profile, but for most people the email_hash approach will be easier.

// pseudo code
sha1("bob@acme.corp")

# bash
echo -n "bob@acme.corp" | shasum

De-duplication

In order to avoid duplicates, Range de-duplicates suggestions based on the suggestion's source_id and a dedupe_strategy . The deduplication strategy can be one of the following:

UNIQUE - Only one suggestion will ever be created, even if the suggestion has been published as part of an update.

UNIQUE_USER - As UNIQUE but one per user.

UNIQUE_PENDING - A suggestion will only be created if there isn't already a suggestion waiting to be published. If the user dismisses the suggestion, a new one won't be added for four hours.

UPSERT_PENDING - If an unpublished suggestion already exists, it will be updated with the state from the latest request. This is the most commonly used strategy.

Reasons

Each suggestion can have a reason as to why it is being shown to the user. This is generally a verb that represents the action that created the suggestion. A user may see the same attachment multiple times, with different reasons. For example, on Monday they may open a pull request, and then merge it on Tuesday.

Our current list of reasons is as follows:

ADDED
EDITED
COMMENTED
CLOSED
CREATED
OPENED
STATUS_UPDATED
REVIEWED
RESOLVED
MERGED
COMPLETED
ASSIGNED
ATTENDED
CHANGED

Attachments

The main content of a suggestion is an "attachment", it represents an artifact that may be included in suggestions for multiple users. The attachment's source_id should be globally unique to a provider. For example, if I edit a doc and you comment on a doc, they should both reference the same attachment but with different "reasons". But pull request #101 in acme-corp/widgets should be disambiguated from PR #101 in acme-corp/marketing-site.

An attachment can represent multiple types, and there optional properties associated with certain types.

All date fields should be in UTC ISO8601 (2006-01-02T15:04:05.999Z ) as compatible with JavaScript's toISOString() .

Core fields:

source_id unique identifier for the attachment. Used to de-duplicate suggestions.
provider lowercase-alphanumeric identifier for your custom provider. e.g. "figma".
provider_name user visible description of the provider, e.g. "Figma".
type the attachment type, see below.
name name for the suggestion, a file name, pull request title, or event name.
html_url URL to link to for people to access the attachment.

The attachment's primary key can be considered a tuple of (source_id , provider ).

Additional fields:

description (optional) descriptive text for the attachment. Limited to 255 chars.
parent_name name for the parent of the attachment, e.g. a folder, project, repo.
parent_html_url (optional) URL to link people to access the parent

Type: LINK

No additional properties.

Type: FILE

date_created
date_modified
file_format file extension, e.g. jpg, png, zip
file_type user visible description of the file, e.g. "Figma Drawing"

Type: EVENT

start_date (optional)
end_date (optional)
location (optional)
num_attendees (optional)
session_identifier

Type: CODE_CHANGE

change_id string used when displaying the change
change_label prefix used when displaying change id. e.g. PR #123, cl/123
change_state e.g. merged, opened, closed

Type: ISSUE

issue_id string used when displaying the issue issue_state e.g. opened, closed, duplicate
issue_label prefix used when displaying issue ids. e.g. Issue #455 , b/455
date_opened (optional)
date_closed (optional)

Type: TASK

task_state e.g. opened, closed, complete, done
date_completed (optional)

Sample Code

This gist contains a simple example for how to post a simple link to the incoming webhook using a node script.

We also have a self-hosted GitHub integration that may be a useful reference.

If there are entity types and fields that you would like us to consider, please get in touch.