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.
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).
"provider_name": "ACME Oncall Tool",
"name": "Primary on call for ACME backend",
The payload fields will be described in detail below.
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
echo -n "firstname.lastname@example.org" | shasum
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.
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:
Contact us if you need more verbs.
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 (
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 (
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
No additional properties.
file_format file extension, e.g. jpg, png, zip
file_type user visible description of the file, e.g. "Figma Drawing"
change_id string used when displaying the change
change_label prefix used when displaying change id. e.g.
change_state e.g. merged, opened, closed
issue_id string used when displaying the issue
e.g. opened, closed, duplicate
issue_label prefix used when displaying issue ids. e.g.
Issue #455 ,
task_state e.g. opened, closed, complete, done
This gist contains a simple example for how to post a simple link to the incoming webhook using a node script.