JavaScript SDK Context Object

The HelpScout SDK provides powerful context-aware features to enable your application to interact with the environment seamlessly. An integral part of this are the getApplicationContext() and watchApplicationContex() methods, which fetch the current application context encapsulating a wealth of information about the company, conversation, customer, mailbox, and user. This page presents a detailed breakdown of the Context object returned by this method, and how you can utilize each property to create more immersive, responsive, and personalized experiences.

When working with the Context object, it’s essential to keep in mind that all its properties are optional. The reason for this is that the context can vary depending on the specific state of the application or where it is loaded.

For example, if you are creating a new conversation within the application, the conversation property may not be available in the Context object. In such cases, attempting to access this property directly without verifying its existence could lead to errors in the application.

To handle this situation, you can use the JavaScript optional chaining operator (?.) to safely access nested properties within the Context object. The optional chaining operator allows you to attempt property access, and if any property in the chain is undefined or null, the expression will short-circuit and return undefined without throwing an error.

Here’s an example of how you can use the optional chaining operator to access the conversation property safely:

HelpScout.getApplicationContext().then(context => {
  const conversationStatus = context?.conversation?.status;
});

In the above code, if the conversation property or any of its nested properties are not available, the conversationStatus variable will be set to undefined instead of causing an error.

By employing the optional chaining operator and double-checking the existence of properties in the Context object, you can ensure that your code handles various scenarios gracefully and avoids unexpected errors.

Property Type Description
Context    
company Company Information about the current company.
conversation Conversation Information about the current conversation.
customer Customer Information about the current customer.
mailbox Mailbox Information about the current mailbox.
user User Information about the current user.

Company

Property Type Description
Company    
id number The company’s unique identifier.

Conversation

Property Type Description
Conversation    
id number The conversation’s unique identifier.
assignee Assignee The user assigned to the conversation.
customerId number The main customer’s unique identifier.
customers ConversationCustomer[] An array of customers related to the conversation.
customFields CustomField[] An array of custom fields associated with the conversation.
following boolean Indicates if the current user is following the conversation.
mailboxId number The unique identifier of the mailbox the conversation belongs to.
number number The conversation’s number within the mailbox.
status Status The current status of the conversation.
subject string The subject of the conversation.
tags Tag[] An array of tags associated with the conversation.
Assignee    
id number The assignee’s unique identifier.
first string The assignee’s first name.
last string The assignee’s last name.
type string The assignee’s type (e.g., ‘user’, ‘team’).
email string The assignee’s email address.
ConversationCustomer    
id number The customer’s unique identifier.
firstName string The customer’s first name.
lastName string The customer’s last name.
emails ConversationCustomerEmail[] An array of customer’s email addresses.
ConversationCustomerEmail    
id number The email’s unique identifier.
value string The email address.
default boolean Indicates if the email is the customer’s default email.
CustomField    
id number The custom field’s unique identifier.
name string The custom field’s name.
value string The custom field’s value.
text string The custom field’s text representation.
Tag    
id number The tag’s unique identifier.
tag string The tag’s text.
Status Description
active The conversation is active and ongoing.
pending The conversation is pending further action.
closed The conversation is closed.
spam The conversation is marked as spam.

Customer

Property Type Description
Customer    
id number The customer’s unique identifier.
firstName string The customer’s first name.
lastName string The customer’s last name.
emails Email[] An array of the customer’s email addresses.
phones Phone[] An array of the customer’s phone numbers.
company string (optional) The customer’s company.
jobTitle string (optional) The customer’s job title.
photoUrl string The URL of the customer’s photo.
conversationCount number The number of conversations the customer is involved in.
note string The note associated with the customer’s profile.
properties CustomerProperty[] An array of the customer’s properties.
socialProfiles SocialProfile[] An array of the customer’s social profiles.
websites Website[] An array of the customer’s websites.
Email    
id number The email’s unique identifier.
value string The email address.
Phone    
id number The phone’s unique identifier.
value string The phone number.
type PhoneType The phone number’s type (e.g., ‘work’, ‘home’, ‘mobile’, ‘fax’, ‘pager’, ‘other’).
CustomerProperty    
slug string The property’s slug.
name string The property’s name.
value string (optional) The property’s value.
text string (optional) The property’s text representation.
type CustomerPropertyType The property’s type (e.g., ‘text’, ‘number’, ‘url’, ‘date’, ‘dropdown’).
SocialProfile    
id number The social profile’s unique identifier.
type SocialProfileType The social profile’s type (e.g., ‘facebook’, ‘twitter’, ‘linkedin’, ‘other’).
url string The social profile’s URL.
Website    
id number The website’s unique identifier.
value string The website’s URL.

Mailbox

Property Type Description
Mailbox    
id number The mailbox’s unique identifier.
name string The mailbox’s name.
email string The mailbox’s email address.

User

Property Type Description
User    
id number The user’s unique identifier.
firstName string The user’s first name.
lastName string The user’s last name.
email string The user’s email address.
initials string The user’s initials.
photoUrl string The URL of the user’s photo.
isAdmin boolean Indicates if the user has admin privileges.
↑Back to top
© Help Scout 2024