Skip to main content

Sending Signals to Salesloft

Technical Requirement​

Create or use an existing Salesloft OAuth or Frontend Application.

What is a Signal​

Salesloft defines a signal as a buyer-focused action or event that happened in the partner’s or customer’s platform. A signal should have high value and should drive a seller to act.

A signal is made up of:

  • a signal type
  • a signal name
  • data shape (metadata about the signal)
  • descriptions
  • at least one indicator(Indicators have metadata and description)
  • an attribution

It is important to note that users may choose to not take action on a signal. Actionability depends on the end user's governance (Play) configurations and settings within Salesloft.

Creating and Naming Your Signal​

Signal types will be generic and will not be partner-specific. However, team-specific (private) integrations should feel free to personalize their signal types. During a user’s session, subsequent benchmarks or events could occur that give value to the signal itself. The events that happen during that session should be considered signal indicators. All signals must have at least one indicator.

Signal name is the public-facing version of the signal type that shows up in the app. For example, video_watched is a signal type and Salesloft:Video Watched would be the signal name.

For each signal type, multiple aspects of the signal need to be determined by the partner.Per integration, the signal type can only be registered once.

Example:

Let’s imagine a partner that specializes in website visitor browsing behavior. Since the partner is the business expert in this domain, they can determine that meaningful interaction is a website visit. They can then request the definition of a new signal type for website_visit.

Data​

Developers will need to define additional pieces of information that Salesloft could present to the end user regarding the signal eg. content name, content url, score, percentage, etc. This additional information could be used to give more context around the signal or link the end user back to the platform.

When you are registering a signal, the data object is called data shape and when you are sending a signal it is called data.

Descriptions​

The signal description represents the central message of the signal and publishes to the Live Feed.

Template descriptions must follow ICU Messages format. Here is a link to a great resource of the capabilities that ICU Messages format provides.

Choosing Indicators​

During a buyer interaction, the application knows that the amount of time the visitor spends on the website is important and could be valuable information to the seller. We would define this as a signal indicator. Inside the website_visit signal type, the developer defines the signal indicator visitor_spent_more_than_30s and provides timestamps inside the indicator metadata. Indicators should be very specific.

An indicator contains:

  • Key: used to identify a relevant event that happened during the signal interaction. The key must start with a letter or _ and contain only alphanumeric characters, -, or _. The key must be unique in the signal type context.

  • Indicator Description: a plain English description of what the signal means for the end user. Write the description with the intention that they will be displayed to the end user in Salesloft. If there’s a play associated with the signal, the indicator description would be displayed on the Task that’s generated.

  • Metadata: list of attributes, data type, and required flags.

Example: Well Defined Signal Indicator:

    {
      "key": "spent_more_than_30s_on_site",
      "metadata": {"time_in_seconds": 42}
    }

Example: Poorly Defined Signal Indicator:

    {
      "key": "time_spent_on_site",
      "metadata": {"time_in_seconds": 30}
    }

Choosing an Attribution Type​

Developers will need to define how a signal should be attributed to a Salesloft object. Decisions made here will determine who (the Seller) sees the signal and who the task is assigned to. Possible attribution choices include Person, Account, User, Opportunity and Email Content.

Salesloft will use the attribution value to derive the appropriate Salesloft user to receive the signal.

Who sees the signal​

PersonAccountEmail ContentUserOpportunityThe Seller who sees the Signal
✖️✖️User specified by signal (Preferred)
✖️Person Owner
✖️Account Owner
✖️Opportunity Owner
✖️User who sent content
✖️✖️Person Owner
✖️✖️User who sent content
✖️✖️User who sent content
✖️✖️✖️User who sent content

Sending Signals to Salesloft​

When sending a signal to Salesloft there are three additional values that are required: urgency, occured_at and idempotency_key. See the table below for all required parameters.

Endpoint Params​

Signal​
ParameterRequired?TypeDescription
name✅StringFront-end version of signal type
type✅StringSignal type
data✅JSONContext metadata that could be shown to the end user. It must follow the structure defined on registration.
indicators✅Array [Indicators]A list of events that happened during the signal interaction.
urgency✅StringA way for the application to define the urgency level. Accepted values are high, medium, and low.
attribution✅JSONMap with Salesloft object IDs that were defined on signal_type registration. These ids can be retrieved using Salesloft API or integration context.
occurred_at✅TimestampISO 8601 timestamp of when the signal happened on the application's system.
idempotency_key✅StringA UUID4 that uniquely identifies the signal in the application system. If we receive two signals with the same idempotency_key one of them will be dropped. The first one wins.
broadcast_notification❌BooleanDetermines if the signal will display in the user's live feed. Defaults to true.
Indicator​
ParameterRequired?TypeDescription
key✅StringIndicator key defined on signal_type registration.
metadata❌JSONMetadata to support the signal indicator. The shape must match with metadata_shape defined on signal registration.

Registering and Sending Signals Examples​

The first step is to register a signal that matches your business use case. We have provided below a full signal registration example for a company that allows customers to create video content. This signal "fires" when the buyer watches the video.

Signal Registration Request Example​

POST https://api.salesloft.com/v2/integrations/signals/registrations/

   {
  "signal_name": "YourCompany:Video Watched",
  "type": "video_watched",
  "broadcast_notification": true,
  "data_shape": {
    "video_name": {
      "type": "string"
    },
    "video_url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://"
    },
    "watched_on": {
      "type": "string",
      "format": "date-time"
    }
  },
  "description": {
    "en-us": "watched {video_name} on {watched_on}",
    "es-es": "fue visto {video_name} el {watched_on}"
  },
  "indicators": [
    {
      "description": {
        "en-us": "{video_name} was viewed {view_count, plural, =1 {# time} other {# times}} within 7 days"
      },
      "key": "viewed_within_7_days",
      "metadata_shape": {
        "video_name": {
          "type": "string"
        },
        "view_count": {
          "type": "number"
        }
      }
    },
    {
      "description": {
        "en-us": "{video_name} was watched by more than 75 percent"
      },
      "key": "video_watched_75_percent",
      "metadata_shape": {
        "video_name": {
          "type": "string"
        },
        "started_viewing_at": {
          "format": "date-time",
          "type": "string"
        },
        "ended_viewing_at": {
          "format": "date-time",
          "type": "string"
        },
        "time_viewed_seconds": {
          "type": "number"
        },
        "video_length_seconds": {
          "type": "number"
        }
      }
    }
  ],
  "idempotency_key": "[UUID4]",
  "attribution": [
    "person",
    "email_tracked_content"
  ],
  "integration_id": 5278
}

Signal Registration Response Example​

   {
  "data": {
    "attribution": [
      "person",
      "email_tracked_content"
    ],
    "created_at": "2024-05-30T20:22:07.685395",
    "data_shape": {
      "video_name": {
        "type": "string"
      },
      "video_url": {
        "format": "uri",
        "pattern": "^https://",
        "type": "string"
      },
      "watched_on": {
        "format": "date-time",
        "type": "string"
      }
    },
    "description": {
      "en-us": "watched {video_name} on {watched_on}",
      "es-es": "fue visto {video_name} el {watched_on}"
    },
    "globally_installed_at": null,
    "id": 249,
    "indicators": [
      {
        "description": {
          "en-us": "{video_name} was viewed {view_count, plural, =1 {# time} other {# times}} within 7 days"
        },
        "key": "viewed_within_7_days",
        "metadata_shape": {
          "video_name": {
            "type": "string"
          },
          "view_count": {
            "type": "number"
          }
        }
      },
      {
        "description": {
          "en-us": "{video_name} was watched by more than 75 percent"
        },
        "key": "video_watched_75_percent",
        "metadata_shape": {
          "ended_viewing_at": {
            "format": "date-time",
            "type": "string"
          },
          "started_viewing_at": {
            "format": "date-time",
            "type": "string"
          },
          "time_viewed_seconds": {
            "type": "number"
          },
          "video_length_seconds": {
            "type": "number"
          },
          "video_name": {
            "type": "string"
          }
        }
      }
    ],
    "integration": {
      "_href": "https://api.salesloft.com/v2/integrations/5278/",
      "id": 5278
    },
    "integration_slug": "rhythm_integration",
    "owner_user_guid": "2ab00eec-be4c-48bc-a75d-20e50e910bb1",
    "signal_name": "YourCompany:Video Watched",
    "type": "video_watched"
  }
}

Live Signal Request Example​

Use Case: Product Usage Upsell​

As a Salesloft customer, I want my sellers to get notified when a current customer’s product usage increases so that I can upsell them other products in my suite.

POST https://api.salesloft.com/v2/signals.json

{
    "type": "product_usage_person",
    "broadcast_notification": true,
    "data": {
        "product_name": "Marketing Platform",
        "product_percentage": 0.75
    },
    "indicators": [
        {
            "key": "passed_key_milestone",
            "metadata": {
                "product_percentage": 0.75
            }
        }
    ],
    "idempotency_key": "[UUID4]",
    "occurred_at": "2024-05-01T14:44:56.621018-04:00",
    "urgency": "medium",
    "attribution": {
        "person_id": 207550815
    }
}

Response 201 - Created

Sample Response​
{
    "data": {
        "attribution": {
            "person_id": 202653389
        },
        "broadcast_notification": true,
        "data": {
            "product_name": "Marketing Platform",
            "product_percentage": 0.8
        },
        "description": {
            "en-us": "increased their usage of Marketing Platform by 80%"
        },
        "idempotency_key": "[UUID4]",
        "indicators": [
            {
                "description": {
                    "en-us": "Product Usage increased by 80%"
                },
                "key": "passed_key_milestone",
                "metadata": {
                    "product_percentage": 0.8
                }
            }
        ],
        "integration": {
            "_href": "https://api.salesloft.com/v2/integrations/5278",
            "id": 5278
        },
        "occurred_at": "2024-04-25T18:44:56.621018Z",
        "received_at": "2024-05-30T21:07:12.763257Z",
        "registration": {
            "_href": "https://api.salesloft.com/v2/integrations/signals/registrations/219",
            "id": 219
        },
        "type": "product_usage_person",
        "urgency": "medium"
    }
}

Use Case: High Engagement with a Video​

You want to tell an AE that an employee at a company with an Open sales opportunity has high engagement with a video embedded within the company website. Based on the user session, you see that the person was highly engaged. They have watched the video multiple times and viewed more than 75% in their latest session.

POST https://api.salesloft.com/v2/signals.json

{
    "type": "video_watched",
    "broadcast_notification": true,
    "data": {
        "video_name": "Salesloft Rhythm Demo",
        "video_url": "https://url-to-video/source",
        "watched_on": "2024-05-25T00:00:00.000000-05:00"
    },
    "indicators": [
        {
            "key": "viewed_within_7_days",
            "metadata": {
                "video_name": "Salesloft Rhythm Demo",
                "view_count": 5
            }
        },
        {
            "key": "video_watched_75_percent",
            "metadata": {
                "started_viewing_at": "2024-05-25T00:00:00.000000-05:00",
                "ended_viewing_at": "2024-05-25T00:45:00.000000-05:00",
                "time_viewed_seconds": 45,
                "video_length_seconds": 80,
                "video_name": "Salesloft Rhythm Demo"
            }
        }
    ],
    "urgency": "high",
    "occurred_at": "2024-05-30T15:36:15.228920-05:00",
    "idempotency_key": "[UUID4]",
    "attribution": {
        "person_id": 207550815
    }
}

Response 201 - Created

Sample Response​
{
    "data": {
        "attribution": {
            "person_id": 207550815
        },
        "broadcast_notification": true,
        "data": {
            "video_name": "Salesloft Rhythm Demo",
            "video_url": "https://url-to-video/source",
            "watched_on": "2024-05-25T05:00:00.000000Z"
        },
        "description": {
            "en-us": "watched Salesloft Rhythm Demo on May 25, 2024, 5:00:00 AM",
            "es-es": "fue visto Salesloft Rhythm Demo el 25 may 2024, 5:00:00"
        },
        "idempotency_key": "[UUID4]",
        "indicators": [
            {
                "description": {
                    "en-us": "Salesloft Rhythm Demo was watched by more than 75 percent"
                },
                "key": "video_watched_75_percent",
                "metadata": {
                    "ended_viewing_at": "2024-05-25T05:45:00.000000Z",
                    "started_viewing_at": "2024-05-25T05:00:00.000000Z",
                    "time_viewed_seconds": 45,
                    "video_length_seconds": 80,
                    "video_name": "Salesloft Rhythm Demo"
                }
            },
            {
                "description": {
                    "en-us": "Salesloft Rhythm Demo was viewed 5 times within 7 days"
                },
                "key": "viewed_within_7_days",
                "metadata": {
                    "video_name": "Salesloft Rhythm Demo",
                    "view_count": 5
                }
            }
        ],
        "integration": {
            "_href": "https://api.salesloft.com/v2/integrations/5278",
            "id": 5278
        },
        "occurred_at": "2024-05-30T20:36:15.228920Z",
        "received_at": "2024-05-30T20:57:31.744724Z",
        "registration": {
            "_href": "https://api.salesloft.com/v2/integrations/signals/registrations/249",
            "id": 249
        },
        "type": "video_watched",
        "urgency": "high"
    }
}

Testing​

Salesloft Live Feed

Send a signal and ensure that it is displayed in the Salesloft Live Feed to the proper user (Seller). It should be hydrated with a Person or Account name.

If your signal(s) do not show up:

  • Confirm that you have an integration icon registered for your integration
  • Ensure that you are logged in as the integration owner and assign any person or account records to yourself
  • Ensure that broadcast_notification in the signals payload is set to true

Allowlisting for Partners​

Partners with a completed and tested signal will proceed through Salesloft’s allowlisting process. Globally installed signals should be considered an immutable API contract with Salesloft and only additive changes will be allowed after this process is complete.