Visitor — Pass User Context

The Pass User Context message enables the host app / environment to pass visitor information to the LiSA Player.

Please ensure the host app / environment awaits the App Listen message to ensure the LiSA Player is ready to accept visitor related messages.

This message is sent by the host app / environment to the LiSA Player.

Properties

Along with all standard Message properties, a Pass User Context message includes the following additional properties:

Name	Type	Description
avatarUrl	String Optional.	The avatarUrl property is used to provide a URL pointing to an image that represents the visitor's avatar. Ensure the image URL points to a properly hosted and publicly accessible resource to avoid display issues.
displayName	String Optional.	The displayName property is used to specify the current visitor's display name, which will be shown in comments.
id	String Required.	The id property is used to define the current visitor's unique identifier within the user management system of the host app or environment. This identifier will be associated with the visitor's session in LiSA.
isCommentsConsentRequired	Boolean Optional.	This property indicates whether the visitor is required to consent to the comments policy before being allowed to post comments. Default value: true
messageType	Literal Required.	lsc:visitor:pass-user-context
trackingParameters	TrackingParameters Optional.	Deprecated — please use Player Deeplink Parameters instead. The trackingParameters property is an object containing extra parameters that will be appended to all social sharing URLs. Please refer to TrackingParameters for detailed information.

Legacy Properties

If your integration uses LiSA Player Version 1, none of the properties described above — except id — will be available.

For LiSA Player Version 2, legacy properties can be ignored.

Name	Type	Description
action	Literal Required.	join ⚠️ Please use messageType instead.
avatar	String Optional.	The avatar property is used to provide a URL pointing to an image that represents the visitor's avatar. Ensure the image URL points to a properly hosted and publicly accessible resource to avoid display issues. ⚠️ Please use avatarUrl instead.
consent	Boolean Optional.	This property indicates whether the visitor is required to consent to the comments policy before being allowed to post comments. Default value: true ⚠️ Please use isCommentsConsentRequired instead.
editable	Boolean Optional.	This property indicates whether the visitor can edit their username in the comments. Default value: true ⚠️ This property is no longer supported in Player Version 2.
name	String Optional.	The name property is used to specify the current visitor's display name, which will be shown in comments. ⚠️ Please use displayName instead.
target	Literal Required.	user ⚠️ Please use messageType instead.

---

Type Definition

interface VisitorUserContextMessage extends Omit<
  Message,
  'messageType' | 'recipient'
> {
  avatarUrl?: string;
  displayName?: string;
  id: string;
  isCommentsConsentRequired?: boolean;
  recipient: 'LiSA';
  messageType: 'lsc:visitor:pass-user-context';
  /**
   * @deprecated - Please use [Player Deeplink Parameters](https://docs.hello-lisa.com/developers/guides/player-communication/message-api-reference/player/player-deeplink-parameters) instead.
   */
  trackingParameters?: TrackingParameters;

  // Legacy LiSA Player V1 attributes for backwards compatibility. 

  action: 'join';
  avatar?: string;
  consent?: boolean;
  editable?: boolean;
  name?: string;
  target: 'user';
}

---

TrackingParameters

The TrackingParameters object lets you include custom parameters in the player, which will be appended to all social sharing URLs.

Please note: Any value of type other than number or string will be ignored.

interface TrackingParameters {
  [key: string]: number | string;
}

Example

window.postMessage({
  avatarUrl: 'https://my-cdn.com/path/to/image.jpg',
  displayName: 'Jane Doe',
  id: '65cf573a-8c51-4b89-b2da-3d79b35fcf1b',
  isCommentsConsentRequired: false,
  recipient: 'LiSA',
  sender: 'Sender',
  messageType: 'lsc:visitor:pass-user-context',
  
  // Depracated - Please use Player Deeplink Parameters instead
  trackingParameters: {
    utm_campaign: 'spring-sale',
    utm_content: 'social-sharing',
    utm_source: 'lisa-social-commerce',
  },

  // Legacy properties - Can be omitted when integrating Player V2
  action: 'join',
  avatar: 'https://my-cdn.com/path/to/image.jpg',
  consent: true,
  editable: false,
  name: 'Jane Doe',
  target: 'user',
});