Workstation Notifications API

Last Updated May 16, 2023

Download as PDF

Brief Overview

With the Workstation Notifications API, you can use events in any system (even if it doesn't have a WalkMe snippet) to trigger a notification in WalkMe and automatically keep your users up-to-date. Trigger Workstation notifications with a REST call to our WalkMe Notification Webhook.

This article will provide the information necessary to make the REST call which requires both an authentication token and a JSON payload.

Any system that can call a REST API can be used to trigger notifications in Workstation.

Before you begin...

Calling the API requires some permissions and technical setup. Make sure you have access and can do the following:

• Admin Center access for your Workstation system to get the API Access Token
  • Note: If your organization has more than one Workstation system, you'll have to make separate API calls for each system.
• Application to configure and execute calls (i.e. Zapier or Postman) to the notification API.
  • You must have an application that can make authenticated outbound REST API calls. If you are unsure whether your organization has such an application, reach out to your IT team to discuss options.

How it works

Here's what you need from WalkMe in order to make the API trigger. Steps on how to gather everything follows.

1. Authentication and creating an access token
2. Identifying the Communication Center notification and target audience
3. Creating the JSON payload
4. Making the call

Specifically, you will find the information necessary to use a notification JSON with the following information:

• System ID
• Notification template ID
• End Users ID or Audience ID
• Notification type: popup or push
• Notification title
• Description
• Override information

Authentication and creating an access token

What is an access token?

An access token is a credential that can be used by an application to access an API. They inform the API that the bearer of the token has been authorized to access a particular action.

The access token authenticates the API call, giving the application permission to pass data from its system to Workstation.

Create access token

1. Go to the Admin Center
2. Navigate to the API Keys tab: https://admin.walkme.com/account-api-keys
3. Click Create new Key

From the Create new key panel:

1. Name the key
   • Tip: Indicate the purpose of the key in the name to help you remember later
2. Turn on Notification API
3. Select Write from the dropdown
4. Click Create

From the Key Details panel:

1. Copy the Client ID and the Client Secret

Authentication Token

For extra support and to get the authorization token: Developer page

ComCenter notification and Audience ID

Create a notification template

Go to Communication Center and create a custom template ( Learn how to create a notification). There's a few things to keep in mind for the notification you create for the API:

• The notification can only have one button
•  The button action can only use the Link Action 
  • You can use dynamic links or WalkMe permalinks

Optional: Add override rules in the template

In the case that you want a notification to be personalized, either to the user or to the event that's being triggered, you can add dynamic values that the API will fill in automatically.

In the image, there are two examples of values being overridden with dynamic text that will be replaced depending on the values the API trigger.

This is an example of API notification with Salesforce which is triggered when a new lead has been assigned. It will notify the salesperson of the opportunity name and link to the lead in Salesforce.

1. ###OPP_NAME_ATTRIBUTE### will be replaced by Opportunity name in Salesforce
2. ###URL### will be replaced by an actual URL, allowing for a custom action for every user, every time the API is triggered

Note: The value name (example: OPP_NAME_ATTRIBUTE) must be exactly copied into the JSON so it can be replaced.

Copy required values

The following steps will connect the notification with the API.

Copy the Custom Template ID that you created

1. Go to CommCenter 
2. Click New Notification
3. Under Custom Templates > Hover over the corner of the notification
4. Click the copy icon to copy the ID to your clipboard
   • Example: 75cfcba6-c320-42cb-938e-4c2bd08a43a3

Copy Target Audience ID

1. Go to Audiences
2. Hover over the audience > click the 3-dot menu on the right > click Copy ID
   • You can add multiple audiences to the JSON
   • Example ID: cf0bd4c1-86fd-4c79-a46a-c730d6789e63

Add information to the API connection application

For extra support  Developer page.

Now it's time to fill in some information on your API connection application. For clarity, we use Zapier to explain, but we are not endorsing this application over any other. Any similar app will work.

The information used below is universally necessary on all applications:

1. URL = https://api.walkme.com/accounts/connect/token
2. Payload Type = (Content-Type) application/x-www-form-urlencoded
3. Data = grant_type → client_credentials

Add Basic Authentication 

When using basic Auth, the clientID is the username and the client secret is used as the password.

1. Client ID | Client Secret (copied from Admin Center)
   • Example
     0o234234234UqD5d7 | JVnD346346346436345asfgasgbPt_4T7h2_

Once you've added this information, you will be given an access token.

1. Copy your Access Token

Update the JSON code

Now it's time to fill in the blanks and use the JSON code that will call the notification.

Make the call

Now that we have the information we need, let's connect the dots. To make the call (connect the systems to create and publish new notifications in your organization's Workstation), you'll need your JSON plus:

• Method: POST
• URL: https://api.walkme.com/public/v1/notifications/send