Skip to main content

Helpshift Delegates

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

Architecture Update SDKX 10.4.0
1. With SDK X 10.4.0 and above, Helpshift has introduced a new implementation approach for delegate events in React Native's new architecture. Please refer to the respective sections below to implement according to your app's architecture (Old or New).
2. Additionally, with SDK X 10.4.0 and above, `eventData` no longer needs to be parsed on Android. It is provided as an object and can be consumed directly.

Helpshift Delegate implementation​

Old Architecture​

  • To use Helpshift Delegate please import helpshiftEmitter
  • To use Helpshift Delegate constants please import helpshiftConstants

For example:

import { helpshiftEmitter , helpshiftConstants } from "helpshift-plugin-sdkx-react-native";

To handle helpshift events, you can use following listener.

const handleCallbacks = () => {
  helpshiftEmitter.addListener("onEventOccurred", (data) => {
    //handle helpshift events using data.eventname
  });
  helpshiftEmitter.addListener("onUserAuthenticationFailure", (data) => {
    //your code here
  });
};

We need add a listener with helpshiftEmitter for "onEventOccurred" and "onUserAuthenticationFailure".

New Architecture (SDK X 10.4.0+)​

import {
  onEventOccurredListener,
  onUserAuthFailedListener,
  HelpshiftEventData
} from "helpshift-plugin-sdkx-react-native";

useEffect(() => {
  const helpshiftEvent = onEventOccurredListener(handleEvent);
  const onUserAuthFailed = onUserAuthFailedListener(handleUserAuthFailed);

  return () => {
    helpshiftEvent?.remove();
    onUserAuthFailed?.remove();
  };
}, []);

const handleEvent = React.useCallback((payload: HelpshiftEventData) => {
  // use payload
}, []);

const handleUserAuthFailed = React.useCallback((payload: HelpshiftEventData) => {
  // use payload
}, []);

Note

helpshiftConstants is available from SDK X 10.3.1 onwards. For older SDK X versions, please use the raw keys instead.

Events​

Helpshift session started event​

This event gets fired when the Helpshift session starts

helpshiftEmitter.addListener("onEventOccurred", (data) => {
  if (data.eventName == "helpshiftSessionStarted") {
    //Your code here.
  }
});

Helpshift session ended event​

This event gets fired when the Helpshift session ends.

helpshiftEmitter.addListener("onEventOccurred", (data) => {
  if (data.eventName == "helpshiftSessionEnded") {
    //Your code here.
  }
});

Unread Message Count Event​

If you want a count of all new messages received in an existing conversation, you can call this API requestUnreadMessageCount(shouldFetchFromServer: boolean). The count of the number of messages will be conveyed to your app via this event.

helpshiftEmitter.addListener("onEventOccurred", (data) => {
  if (data.eventName == "receivedUnreadMessageCount") {
      let countData =
        Platform.OS == data.eventData
      console.log(countData.count);
  }
});

Conversation Status Event​

This event contains information about the current ongoing conversation.

helpshiftEmitter.addListener('onEventOccurred', (data) => {
  if (data.eventName == 'conversationStatus') {
    console.log(data?.eventData?.latestIssueId);
    console.log(data?.eventData?.latestIssuePublishId);
    console.log(data?.eventData?.open);
  }
});

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. For your reference, see the below example:

helpshiftEmitter.addListener('onEventOccurred', (data) => {
  if (data.eventName == 'widgetToggle') {
      console.log(data?.eventData?.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 : helpshiftConstants.HELPSHIFT_EVENT_NAME_USER_CLICK_ON_ACTION
  • Event data:
    • helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_DATA
    • helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_TYPE
    • helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_TYPE_CALL
    • helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_TYPE_LINK
Key (Constant)Key (Raw)Type
helpshiftConstants.HELPSHIFT_EVENT_NAME_USER_CLICK_ON_ACTIONuserClickOnActionstring
helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_TYPEactionTypestring
helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_DATAactionDatastring
helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_TYPE_CALLcallstring
helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_TYPE_LINKlinkstring
Note

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

helpshiftEmitter.addListener('onEventOccurred', (data) => {
  if (data.eventName == helpshiftConstants.HELPSHIFT_EVENT_NAME_USER_CLICK_ON_ACTION) {
      let eventActionType = eventData[helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_TYPE];
      let eventActionData = eventData[helpshiftConstants.HELPSHIFT_EVENT_DATA_ACTION_DATA];

      console.log('Event Receivd for ' + data.eventName + ' action type : ' + eventActionType + ' action data ' + eventActionData );
  }
});

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. For your reference, see the below example.

helpshiftEmitter.addListener("onEventOccurred", (data) => {
  if (data.eventName == "conversationStart") {
      console.log(data.eventData.message);
  }
});

Message Add Event​

This event is triggered when the user adds a message to a conversation. It might be a text message, a response via bot input, or an attachment. The event data object has the type and body keys, which indicate the type and body of the message added by the user. For your reference, see the below example.

helpshiftEmitter.addListener("onEventOccurred", (data) => {
  if (data.eventName == "messageAdd") {
    console.log(data?.eventData?.body);
    console.log(data?.eventData?.type);
  }
});

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 : helpshiftConstants.HELPSHIFT_EVENT_NAME_AGENT_MESSAGE_RECEIVED

  • Event data:

    KeyTypeValue
    helpshiftConstants.HELPSHIFT_EVENT_DATA_PUBLISH_IDstringConversation ID of the ongoing issue
    helpshiftConstants.HELPSHIFT_EVENT_DATA_MESSAGE_TYPEstringMessage Type of the message
    helpshiftConstants.HELPSHIFT_EVENT_DATA_MESSAGE_BODYstringThe actual message sent by the agent or empty
    helpshiftConstants.HELPSHIFT_EVENT_DATA_CREATED_TIMEnumberUnix epoch timestamp in ms
    helpshiftConstants.HELPSHIFT_EVENT_DATA_ATTACHMENTSobjectAttachments, if they are present
    helpshiftConstants.HELPSHIFT_EVENT_DATA_URLstringURL of the attachment
    helpshiftConstants.HELPSHIFT_EVENT_DATA_CONTENT_TYPEstringMIME type of the attachment
    helpshiftConstants.HELPSHIFT_EVENT_DATA_FILE_NAMEstringFile name of the attachment
    helpshiftConstants.HELPSHIFT_EVENT_DATA_SIZEnumberSize of the attachment in bytes
Note
  • This delegate is available from 10.3.1 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 helpshiftConstants.HELPSHIFT_EVENT_DATA_CONTENT_TYPE is absent from the payload. For such cases, file type can be inferred from extension from file name
  • helpshiftConstants.HELPSHIFT_EVENT_DATA_MESSAGE_TYPE has following types :
    • helpshiftConstants.HELPSHIFT_EVENT_DATA_MESSAGE_TYPE_APP_REVIEW_REQUEST
    • helpshiftConstants.HELPSHIFT_EVENT_DATA_MESSAGE_TYPE_SCREENSHOT_REQUEST
    • helpshiftConstants.HELPSHIFT_EVENT_DATA_MESSAGE_TYPE_TEXT
helpshiftEmitter.addListener(
  helpshiftConstants.HANDLE_HELPSHIFT_EVENT,
  (data) => {
    if (data.eventName == helpshiftConstants.HELPSHIFT_EVENT_NAME_AGENT_MESSAGE_RECEIVED) {
      try {
        let publishId = eventData[helpshiftConstants.HELPSHIFT_EVENT_DATA_PUBLISH_ID];
        let type = eventData[helpshiftConstants.HELPSHIFT_EVENT_DATA_MESSAGE_TYPE];
        let body = eventData[helpshiftConstants.HELPSHIFT_EVENT_DATA_MESSAGE_BODY];
        let createdTs = eventData[helpshiftConstants.HELPSHIFT_EVENT_DATA_CREATED_TIME];

        // isEmpty is undefined and empty check
        if (isEmpty(publishId) && isEmpty(type) && isEmpty(body) && createdTs == null) {
          console.log('Received no data');
          return;
        }

        console.log('publishId ' + publishId + ' type ' + type + ' body ' + body + ' createdTs ' + createdTs);
        let attachments = eventData[helpshiftConstants.HELPSHIFT_EVENT_DATA_ATTACHMENTS];

        if (attachments && attachments.length > 0) {
          attachments.forEach((attachment, index) => {
            let url = attachment[helpshiftConstants.HELPSHIFT_EVENT_DATA_URL];
            let contentType = attachment[helpshiftConstants.HELPSHIFT_EVENT_DATA_CONTENT_TYPE];
            let fileName = attachment[helpshiftConstants.HELPSHIFT_EVENT_DATA_FILE_NAME];
            let size =attachment[helpshiftConstants.HELPSHIFT_EVENT_DATA_SIZE];

            if (isEmpty(url) && isEmpty(fileName) && size == null) {
              console.log('Received no data for attachment ' + (index + 1));
            }

            if (isEmpty(url) || isEmpty(fileName) || size == null) {
              console.log('Received incomplete data for attachment ' + (index + 1));
            }

            console.log('Attachment No. : ' + (index + 1) + ', url: ' + url + ', contentType: ' + contentType + ', fileName: ' + fileName + ', size: ' + size );
          });
        } else {
          console.log('No attachments received in message');
        }
      } catch (err) {
        console.error('Parsing Error', err);
      }
    }
  }
);

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. For your reference, see the below example.

helpshiftEmitter.addListener('onEventOccurred', (data) => {
  if (data.eventName == "csatSubmit") {
      console.log(data.eventData.rating);
  }
});

Conversation End Event​

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

helpshiftEmitter.addListener('onEventOccurred', (data) => {
  if (data.eventName == "conversationEnd") {
      console.log("Conversation Ended");
  }
});

Conversation Rejected Event​

This event is triggered when an agent rejects the conversation.

helpshiftEmitter.addListener('onEventOccurred', (data) => {
  if (data.eventName == "conversationRejected") {
      console.log("Conversation Rejected");
  }
});

Conversation Resolved Event​

helpshiftEmitter.addListener('onEventOccurred', (data) => {
  if (data.eventName == "conversationResolved") {
      console.log("Conversation Resolved");
  }
});

Conversation Reopened Event​

When the 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.

helpshiftEmitter.addListener('onEventOccurred', (data) => {
  if (data.eventName == "conversationReopened") {
      console.log("Conversation Reopened");
  }
});

User Authentication Failed Event​

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

You need add a listener with helpshiftEmitter for "onUserAuthenticationFailure".

You will receive various string name on onUserAuthenticationFailure event as shown in example.

helpshiftEmitter.addListener("onUserAuthenticationFailure", (data) => {
  if (data.eventName == "REASON_AUTH_TOKEN_NOT_PROVIDED") {
    console.log("no user authentication token provided");
  } else if (data.eventName == "REASON_INVALID_AUTH_TOKEN") {
    console.log("user authentication token is invalid");
  } else if (data.eventName == "UNKNOWN") {
    console.log("the reason for the authentication failure is unknown");
  }
});

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. All these events can be found in HelpshiftConstants.h 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

IDENTITY_TOKEN_INVALID​

Identities JWT not in valid format

  • APIs - addUserIdentities
  • Data - nil

IAT_IS_MANDATORY​

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

  • APIs - addUserIdentities
  • Data - nil

IDENTITY_DATA_INVALID​

Some of the identities in the JWT payload are not valid

  • APIs - addUserIdentities
  • Data -
KeyValueRecovery
One of the passed identity keysEXCEEDED_KEY_LENGTH_LIMITEnsure key length is within permissible limit
One of the passed identity keysEXCEEDED_VALUE_LENGTH_LIMITEnsure value length is within permissible limit
One of the passed identity keysEMPTY_DATAEnsure key or value is a valid non-empty value
One of the passed identity keysMETADATA_EXCEEDED_COUNT_LIMITEnsure total number of entries in metadata dictionary for this identity is within permissible limit
One of the passed identity metadata keysMETADATA_EXCEEDED_KEY_LENGTH_LIMITEnsure metadata key length is within permissible limit
One of the passed identity metadata keysMETADATA_EXCEEDED_VALUE_LENGTH_LIMITEnsure metadata value length is within permissible limit
One of the passed identity metadata keysMETADATA_EMPTY_KEY_OR_VALUEEnsure metadata key or value is a valid non-empty value

IDENTITIES_SIZE_LIMIT_EXCEEDED​

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

  • APIs - addUserIdentities
  • Data - nil

ADD_USER_IDENTITIES_SYNC_FAILED​

User identities failed to sync with backend

  • APIs - addUserIdentities
  • Data -
KeyValueRecovery
One of the passed identity keysHelpshiftInvalidDataNA

APP_ATTRIBUTES_LIMIT_EXCEEDED / MASTER_ATTRIBUTES_LIMIT_EXCEEDED​

Number of unsynced app or master attributes exceeds the permissible limit

  • APIs - updateAppAttributes, updateMasterAttributes
  • Data - nil

HelpshiftEventUpdateAppAttributesValidationFailed / HelpshiftEventUpdateMasterAttributesValidationFailed​

Validation of individual entries inside the attributes dictionary failed

  • APIs - updateAppAttributes, updateMasterAttributes
  • Data -
KeyValueRecovery
One of the passed attribute keysEXCEEDED_KEY_LENGTH_LIMITEnsure key length is within permissible limit
One of the passed attribute keysEXCEEDED_VALUE_LENGTH_LIMITEnsure value length is within permissible limit
One of the passed attribute keysEXCEEDED_COUNT_LIMITReduce the number of entries in the collection for specified key
One of the passed attribute keysINVALID_VALUE_TYPEEnsure value is one of the supported types - String, Bool, Number, String array or a String - String dictionary

UPDATE_APP_ATTRIBUTES_SYNC_FAILED / UPDATE_MASTER_ATTRIBUTES_SYNC_FAILED​

Attributes failed to sync with backend

  • APIs - updateAppAttributes, updateMasterAttributes

Data -

KeyValueRecovery
One of the passed attribute keysINVALID_DATANA

USER_IDENTITY_NOT_ENABLED​

Identity feature is not enabled for your domain

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

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 - nil

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 - nil