Helpshift Delegates

The Helpshift SDK provides delegate callbacks to help app developers track a user's activities within the help section.

Note

All the public APIs in the SDK should be called after initializing the SDK via Helpshift.install() API

Helpshift Events Listener/Delegates implementation

You can set HelpshiftEventsListener by calling the Helpshift.setHelpshiftEventsListener() method.

Note

• Events invoked before setting Helpshift.setHelpshiftEventsListener cannot be received agian.
• Please make sure you set the delegate immediately after calling the Helpshift install API to ensure you don't miss any events generated by the SDK.

For example:

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
 @Override
 public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
   switch(eventName){
     case HelpshiftEvent.CONVERSATION_START:
       //your code here
     break;
     // and so on...
     //the list of events is given below
   }
 }

 @Override
 public void onUserAuthenticationFailure(HelpshiftAuthenticationFailureReason reason) {
   // your code here
 }
});

Class Implementation: You have to define a class which implements HelpshiftEventsListener
and then set this event listener instance using Helpshift.setHelpshiftEventsListener() method.

class MyEventListener implements HelpshiftEventsListener {

  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName) {
      case HelpshiftEvent.CONVERSATION_START:
        //your code here
      break;
      // and so on...
      //the list of events is given below
    }
  }

  @Override
  public void onUserAuthenticationFailure(HelpshiftAuthenticationFailureReason reason) {
    // your code here
  }
}

MyEventListener listener = new MyEventListener();
Helpshift.setHelpshiftEventsListener(listener);

Helpshift Events

Conversation Status Event

This event contains information about the current ongoing conversation.

• Event name: HelpshiftEvent.CONVERSATION_STATUS
• Event data:
  • HelpshiftEvent.DATA_LATEST_ISSUE_ID
  • HelpshiftEvent.DATA_LATEST_ISSUE_PUBLISH_ID
  • HelpshiftEvent.DATA_IS_ISSUE_OPEN

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_STATUS:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_LATEST_ISSUE_PUBLISH_ID));
    }
  }
});

Widget Toggle Event

This event is triggered when the user opens or exits the chat screen. This event is triggered with a boolean value of "visible" key.

• Event name: HelpshiftEvent.WIDGET_TOGGLE
• Event data: HelpshiftEvent.DATA_SDK_VISIBLE

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.WIDGET_TOGGLE:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_SDK_VISIBLE));
    }
  }
});

User Click On Action Event

This event is triggered when the user clicks on the link or call action of an action card message.

• Event Name : HelpshiftEvent.ACTION_CLICKED
• Event data:
  • HelpshiftEvent.DATA_ACTION
  • HelpshiftEvent.DATA_ACTION_TYPE
  • HelpshiftEvent.DATA_ACTION_TYPE_CALL
  • HelpshiftEvent.DATA_ACTION_TYPE_LINK

Key (Constant)	Key (Raw)	Type
HelpshiftEvent.ACTION_CLICKED	userClickOnAction	String
HelpshiftEvent.DATA_ACTION	actionType	String
HelpshiftEvent.DATA_ACTION_TYPE	actionData	String
HelpshiftEvent.DATA_ACTION_TYPE_CALL	call	String
HelpshiftEvent.DATA_ACTION_TYPE_LINK	link	String

Note

The key constants are available from SDK X 10.3.0 onwards. For older SDK X versions, please use the raw keys instead.

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.ACTION_CLICKED:
          // With Key Constants
          String actionType = (String) data.get(HelpshiftEvent.DATA_ACTION_TYPE);
          String actionData = (String) data.get(HelpshiftEvent.DATA_ACTION);

          -------------------- OR --------------------

          // With Key Raw Values
          String actionType = (String) data.get("actionType");
          String actionData = (String) data.get("actionData");

          // `Utils.isEmpty` is null and empty Check
          if (Utils.isEmpty(actionType) || Utils.isEmpty(actionData)) {
            Log.d(TAG, "Event Received for " + eventName + " with actionType or action Data as empty");
            return;
          }

          Log.d(TAG, "Event Received for " + eventName + " action type " + actionType + " actionData " + actionData);
    }
  }});

Conversation Start Event

This event triggers when the user sends the first message in a conversation. The event data object has a key, message, which includes the message string the end-user sent to start the conversation.

• Event name: HelpshiftEvent.CONVERSATION_START
• Event data: HelpshiftEvent.DATA_MESSAGE

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_START:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_MESSAGE));
    }
  }
});

Message Add Event

This event is triggered when the user adds a message in a conversation. It might be a text message, response via bot input, or an attachment. The event data object has type and body keys, which indicates the type and body of the message added by the user.

• Event name: HelpshiftEvent.MESSAGE_ADD
• Event data:
  • HelpshiftEvent.DATA_MESSAGE_TYPE
  • HelpshiftEvent.DATA_MESSAGE_BODY
  • HelpshiftEvent.DATA_MESSAGE_TYPE_ATTACHMENT
  • HelpshiftEvent.DATA_MESSAGE_TYPE_TEXT

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.MESSAGE_ADD:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_MESSAGE_BODY));
        if(data.get(HelpshiftEvent.DATA_MESSAGE_TYPE).equals(HelpshiftEvent.DATA_MESSAGE_TYPE_ATTACHMENT)){
          Log.d(TAG, "user sent an attachment");
        }
    }
  }
});

Agent Message Received Event

This event is triggered when the user receives any message from an agent in a conversation. This delegate is not triggered for bot messages or messages sent via automations.

• Event name : HelpshiftEvent.AGENT_MESSAGE_RECEIVED

• Event data:

  Key	Type	Value
  HelpshiftEvent.DATA_PUBLISH_ID	String	Conversation ID of the ongoing issue
  HelpshiftEvent.DATA_MESSAGE_TYPE	String	Message Type of the message
  HelpshiftEvent.DATA_MESSAGE_BODY	String	The actual message sent by the agent or empty
  HelpshiftEvent.DATA_CREATED_TIME	Long	Unix epoch timestamp in ms
  HelpshiftEvent.DATA_ATTACHMENTS	Map<String, Object>	Attachments, if they are present
  HelpshiftEvent.DATA_URL	String	URL of the attachment
  HelpshiftEvent.DATA_CONTENT_TYPE	String	MIME type of the attachment
  HelpshiftEvent.DATA_FILE_NAME	String	File name of the attachment
  HelpshiftEvent.DATA_SIZE	Integer	Size of the attachment in bytes

Note

• This delegate is available from 10.3.0 and above versions
• The attachments key is only present if the agent has sent attachments.
• Since attachments sent by agents may not have the necessary MIME type or name, it is possible that HelpshiftEvent.DATA_CONTENT_TYPE is absent from the payload. For such cases, file type can be inferred from extension from file name
• HelpshiftEvent.DATA_MESSAGE_TYPE has following types :
  • HelpshiftEvent.DATA_MESSAGE_TYPE_APP_REVIEW_REQUEST
  • HelpshiftEvent.DATA_MESSAGE_TYPE_SCREENSHOT_REQUEST
  • HelpshiftEvent.DATA_MESSAGE_TYPE_TEXT

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> eventData) {
        switch (eventName) {
          case HelpshiftEvent.AGENT_MESSAGE_RECEIVED:
            Log.d(TAG,"Received Event for " + eventName);
            String publishId = (String) eventData.get(HelpshiftEvent.DATA_PUBLISH_ID);
            String type = (String) eventData.get(HelpshiftEvent.DATA_MESSAGE_TYPE);
            String body = (String) eventData.get(HelpshiftEvent.DATA_MESSAGE_BODY);
            Long createdTs = (Long) eventData.get(HelpshiftEvent.DATA_CREATED_TIME);

            // Utils.isEmpty() is null and empty Check

            if (Utils.isEmpty(publishId) && Utils.isEmpty(type) && Utils.isEmpty(body) && createdTs == null) {
              Log.d(TAG, "Received no data");
              return;
            }

            Log.d(TAG, "publishId " + publishId + " type " + type + " body " + body + " createdTs " + createdTs);
            List<Object> attachments = (List<Object>) eventData.get(HelpshiftEvent.DATA_ATTACHMENTS);

            if (Utils.isEmpty(attachments)) {
              Log.d(TAG, "No attachments received in message");
            } else {

              for (int i = 0; i < attachments.size(); i++) {
                Map<String, Object> attachment = (Map<String, Object>) attachments.get(i);

                String url = (String) attachment.get(HelpshiftEvent.DATA_URL);
                String contentType = (String) attachment.get(HelpshiftEvent.DATA_CONTENT_TYPE);
                String fileName = (String) attachment.get(HelpshiftEvent.DATA_FILE_NAME);
                Integer size = (Integer) attachment.get(HelpshiftEvent.DATA_SIZE);

                if (Utils.isEmpty(url) && Utils.isEmpty(fileName) && size == null) {
                  Log.d(TAG,"Received no data for attachment " + (i + 1));
                  continue;
                }

                if (Utils.isEmpty(url) || Utils.isEmpty(fileName) || size == null) {
                  Log.d(TAG,"Received incomplete data for attachment " + (i + 1));
                  continue;
                }

                Log.d(TAG, "Attachment No. : " + (i + 1) + ", url: " + url + ", contentType: " + contentType + ", fileName: " + fileName + ", size: " + size);
              }
            }
        }
  }});

CSAT Submit Event

This event is triggered when the user submits a CSAT rating after the conversation ends. The event data object has rating and additionalFeedback keys, which indicates the (star) rating and the additional comments provided by the user with the CSAT form.

• Event name: HelpshiftEvent.CSAT_SUBMIT
• Event data:
  • HelpshiftEvent.DATA_CSAT_RATING
  • HelpshiftEvent.DATA_ADDITIONAL_FEEDBACK

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CSAT_SUBMIT:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_CSAT_RATING));
        Log.d(TAG, data.get(HelpshiftEvent.DATA_ADDITIONAL_FEEDBACK));
    }
  }
});

Conversation End Event

This event is triggered when the conversation ends (resolved or rejected) and it cannot be reopened.

• Event name: HelpshiftEvent.CONVERSATION_END

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_END:
        //data will be empty
    }
  }
});

Conversation Rejected Event

This event is triggered when an agent rejects the conversation.

• Event name: HelpshiftEvent.CONVERSATION_REJECTED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_REJECTED:
        //data will be empty
    }
  }
});

Conversation Resolved Event

This event is triggered when an agent resolves the conversation.

• Event name: HelpshiftEvent.CONVERSATION_RESOLVED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_RESOLVED:
        //data will be empty
    }
  }
});

Conversation Reopened Event

When resolution question is enabled, the users are asked if they're satisfied with the resolution. If the user rejects it and sends a new message, then the conversation is reopened and the Conversation Reopened event is triggered.

• Event name: HelpshiftEvent.CONVERSATION_REOPENED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_REOPENED:
        //data will be empty
    }
  }
});

User Authentication Failed Event

If you have User Authentication feature enabled on the Dashboard and if you pass an invalid token in the Helpshift.login(userDataMap), then you will receive this event with reason string. Check here for more info.

Reason type:

• HelpshiftAuthenticationFailureReason.REASON_INVALID_AUTH_TOKEN
• HelpshiftAuthenticationFailureReason.REASON_AUTH_TOKEN_NOT_PROVIDED
• HelpshiftAuthenticationFailureReason.UNKNOWN

     // ...
    Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
       @Override
      public void onUserAuthenticationFailure(HelpshiftAuthenticationFailureReason reason) {
        Log.e(TAG, reason);
      }
      // ...
    });

Helpshift session delegates

Helpshift Session Started

If you want to keep track of when helpshift session starts in your app, you can implement this delegate callback. The delegate will get fired every time the Helpshift session starts.

• Event Name: HelpshiftEvent.SDK_SESSION_STARTED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.SDK_SESSION_STARTED:
        //sdk session started
    }
  }
});

Helpshift Session Ended

If you want to keep track of when helpshift session ends in your app, you can implement this delegate callback. The delegate will get fired every time the Helpshift session ends.

• Event Name: HelpshiftEvent.SDK_SESSION_ENDED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.SDK_SESSION_ENDED:
        //sdk session ended
    }
  }
});

Unread Message Count

If you want a count of all new messages received in an existing conversation, you can call this API requestUnreadMessageCount(final boolean shouldFetchFromServer).

The unread message count will be conveyed to your app via this event. You can also use this event to keep your badge counts updated.

• Event Name: HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT
• Event Data: HelpshiftEvent.DATA_MESSAGE_COUNTHelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE

// call requestUnreadMessageCount() api first
Helpshift.requestUnreadMessageCount(true);

// ...
Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT:
        int count = (int) data.get(HelpshiftEvent.DATA_MESSAGE_COUNT);
        boolean fromCache = (boolean) data.get(HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE);
        Log.d(TAG, "Message Count : " + count + ", From Cache: " + fromCache);
    }
  }
});

If you call the method Helpshift.requestUnreadMessageCount(true) it will return a notification count from server in the above delegate method asynchronously. The notification count here can be fetched either from the cache or from the Helpshift servers. The count from Helpshift’s servers is rate limited and it returns the latest value only if a subsequent call is made to the API after the reset timeout or when the user just closes the chat screen (whichever is earlier). If the API is called within the rate limit period then it returns value from local cache. For an active issue, the reset timeout is 1 minute and 5 minutes for inactive issues.

If you want to retrieve the current notification count stored locally, you can call the same method with the parameter set to false, Helpshift.requestUnreadMessageCount(false). In this case, SDK returns the count of unread messages available locally in this delegate method.

Locally saved unread message count are useful for saving an additional network call.

User Identity System Events

When using Identity system related APIs, the related events are communicated to your app using the events mentioned in this section. Events can have associated data which gives more information on the corresponding event. The constants for value of data is present in InvalidDataErrorReason file.

Where applicable, the max permissible limits are defined as follows -

• Key length - Max 255 chars
• Value length for any identity (except uid) - Max 300 chars
• Value length for uid identity - Max 750 chars
• Value length for CUF - Max 255 chars
• Value length for multiline CUF - Max 100000 chars
• Value length for user tags - Max 100 chars
• Collection size - Max 30 entries

INVALID_IDENTITY_TOKEN

Identities JWT not in valid format

• APIs - addUserIdentities
• Data - null

IAT_IS_MANDATORY

The iat key is missing in JWT. Issued At Timestamp or iat is a mandatory key in the JWT payload.

• APIs - addUserIdentities
• Data - null

IDENTITY_DATA_INVALID

Some of the identities in the JWT payload are not valid

• APIs - addUserIdentities
• Data -

Key	Value	Recovery
One of the passed identity keys	EXCEEDED_KEY_LENGTH_LIMIT	Ensure key length is within permissible limit
One of the passed identity keys	EXCEEDED_VALUE_LENGTH_LIMIT	Ensure value length is within permissible limit
One of the passed identity keys	EMPTY_DATA	Ensure key or value is a valid non-empty value
One of the passed identity keys	META_DATA_EXCEEDED_COUNT_LIMIT	Ensure total number of entries in metadata dictionary for this identity is within permissible limit
One of the passed identity metadata keys	META_DATA_EXCEEDED_KEY_LENGTH_LIMIT	Ensure metadata key length is within permissible limit
One of the passed identity metadata keys	META_DATA_EXCEEDED_VALUE_LENGTH_LIMIT	Ensure metadata value length is within permissible limit
One of the passed identity metadata keys	METADATA_EMPTY_KEY_OR_VALUE	Ensure metadata key or value is a valid non-empty value

IDENTITY_DATA_LIMIT_EXCEEDED

Number of identities in JWT payload is more than the permissible limit

• APIs - addUserIdentities
• Data - null

IDENTITY_DATA_SYNC_FAILED

User identities failed to sync with backend

• APIs - addUserIdentities
• Data -

Key	Value	Recovery
One of the passed identity keys	INVALID_DATA	NA

APP_ATTRIBUTES_LIMIT_EXCEEDED / MASTER_ATTRIBUTES_LIMIT_EXCEEDED

Number of unsynced app or master attributes exceeds the permissible limit

• APIs - updateAppAttributes, updateMasterAttributes
• Data - null

APP_ATTRIBUTES_VALIDATION_FAILED / MASTER_ATTRIBUTES_VALIDATION_FAILED

Validation of individual entries inside the attributes dictionary failed

• APIs - updateAppAttributes, updateMasterAttributes
• Data -

Key	Value	Recovery
One of the passed attribute keys	EXCEEDED_KEY_LENGTH_LIMIT	Ensure key length is within permissible limit
One of the passed attribute keys	EXCEEDED_VALUE_LENGTH_LIMIT	Ensure value length is within permissible limit
One of the passed attribute keys	EXCEEDED_COUNT_LIMIT	Reduce the number of entries in the collection for specified key
One of the passed attribute keys	INVALID_VALUE_TYPE	Ensure value is one of the supported types - String, Bool, Number, String array or a String - String dictionary

APP_ATTRIBUTES_SYNC_FAILED / MASTER_ATTRIBUTES_SYNC_FAILED

Attributes failed to sync with backend

• APIs - updateAppAttributes, updateMasterAttributes
• Data -

Key	Value	Recovery
One of the passed attribute keys	INVALID_DATA	NA

IDENTITY_FEATURE_NOT_ENABLED

Identity feature is not enabled for your domain

• APIs - addUserIdentities, updateAppAttributes, updateMasterAttributes
• Data - null

USER_SESSION_EXPIRED

Sent when the SDK's user session expires. Once the session expires, SDK will keep sending this event to your app on each foreground. In response to this event, you should refresh the JWT for the current user and log them in again with the new JWT.

Data - null

REFRESH_USER_CREDENTIALS

Sent when the SDK's user session is about to expire. This gives you a chance to proactively refresh the JWT for the current user and log them in the SDK with the new JWT to avoid disrupting their session.

Data - null