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.

Note

  • All the public APIs in the SDK should be called after initializing the SDK via install API

  • Events invoked before setting HelpshiftCocos2dx::setHelpshiftEventsListener() cannot be received again

Helpshift Events Listener/Delegates implementation​

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

For example:

#include "HelpshiftEvent.h"

void handleAuthFailureEvent(HSAuthenticationFailureReason reason) {
    // your code here
    // ...
}

void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {

    if (strcmp(eventName, SDK_SESSION_STARTED) == 0) {
        // your code here
        //...
    }
    if (strcmp(eventName, RECEIVED_UNREAD_MESSAGE_COUNT) == 0) {
        // your code here
        //...
    }
    // ... and so on
    // list of events given below
}

// init method of your UI
bool HelloWorld::init()
{
    //////////////////////////////
    // 1. super init first
    if ( !Scene::init() )
    {
        return false;
    }

    HelpshiftCocos2dx::setHelpshiftEventsListener(handleHelpshiftEvent,
                                                  handleAuthFailureEvent);

    // Your code here
    // ...
}

Helpshift Events​

You can find list of all Helpshift Events in HelpshiftEvent.h file.

To use Helpshift Events, include HelpshiftEvent.h in your UI file.

#include "HelpshiftEvent.h"

Conversation Status Event​

This event contains information about the current ongoing conversation.

  • Event name: CONVERSATION_STATUS
  • Event data:
    • DATA_LATEST_ISSUE_ID
    • DATA_LATEST_ISSUE_PUBLISH_ID
    • DATA_IS_ISSUE_OPEN
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, CONVERSATION_STATUS) == 0) {
        std::string publishId = eventData[DATA_LATEST_ISSUE_PUBLISH_ID].asString();
        // your code here
        //...
    }
}

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: WIDGET_TOGGLE
  • Event data: DATA_SDK_VISIBLE
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, WIDGET_TOGGLE) == 0) {
        std::string data = eventData[DATA_SDK_VISIBLE].asString();
        // your code here
        //...
    }
}

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 : ACTION_CLICKED
  • Event data:
    • DATA_ACTION
    • DATA_ACTION_TYPE
    • DATA_ACTION_TYPE_CALL
    • DATA_ACTION_TYPE_LINK
Key (Constant)Key (Raw)Type
ACTION_CLICKEDuserClickOnActionString
DATA_ACTIONactionTypeString
DATA_ACTION_TYPEactionDataString
DATA_ACTION_TYPE_CALLcallString
DATA_ACTION_TYPE_LINKlinkString
Note

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

void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, ACTION_CLICKED) == 0) {

        // Using Constants
        std::string dataAction = eventData[DATA_ACTION].asString();
        std::string dataActionType = eventData[DATA_ACTION_TYPE].asString();

        // Using Raw keys
        std::string dataAction = eventData["actionData"].asString();
        std::string dataActionType = eventData["actionType"].asString();

        // your code here
        //...
    }
}

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: CONVERSATION_START
  • Event data: DATA_MESSAGE
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, CONVERSATION_START) == 0) {
        std::string data = eventData[DATA_MESSAGE].asString();
        // your code here
        //...
    }
}

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: MESSAGE_ADD
  • Event data:
    • DATA_MESSAGE_TYPE
    • DATA_MESSAGE_BODY
    • DATA_MESSAGE_TYPE_ATTACHMENT
    • DATA_MESSAGE_TYPE_TEXT
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, MESSAGE_ADD) == 0) {
        std::string data = eventData[DATA_MESSAGE_TYPE_ATTACHMENT].asString();
        CCLOG("User sent an attachment");
        // your code here
        //...
    }
}

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 : AGENT_MESSAGE_RECEIVED

  • Event data:

    KeyTypeValue
    DATA_PUBLISH_IDStringConversation ID of the ongoing issue
    DATA_MESSAGE_TYPEStringMessage Type of the message
    DATA_MESSAGE_BODYStringThe actual message sent by the agent or empty
    DATA_CREATED_TIMELongUnix epoch timestamp in ms
    DATA_ATTACHMENTSVectorAttachments, if they are present

The DATA_ATTACHMENTS is a vector of Map, with one of Map for each attachment, The data for attachment map is -

KeyTypeValue
DATA_URLStringURL of the attachment
DATA_CONTENT_TYPEStringMIME type of the attachment
DATA_FILE_NAMEStringFile name of the attachment
DATA_SIZEIntegerSize 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 DATA_CONTENT_TYPE is absent from the payload. For such cases, file type can be inferred from extension from file name
  • DATA_MESSAGE_TYPE has following types :
    • DATA_MESSAGE_TYPE_APP_REVIEW_REQUEST
    • DATA_MESSAGE_TYPE_SCREENSHOT_REQUEST
    • DATA_MESSAGE_TYPE_TEXT
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, AGENT_MESSAGE_RECEIVED) == 0) {
        std::string publishId = eventData[DATA_PUBLISH_ID].asString();
        std::string messageType = eventData[DATA_MESSAGE_TYPE].asString();
        std::string messageBody = eventData[DATA_MESSAGE_BODY].asString();
        std::string createdTs = eventData[DATA_CREATED_TIME].asString();


        const Value& agentMessageReceivedValue = eventData[DATA_ATTACHMENTS];

        // your code here
        //...
    }
}

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: CSAT_SUBMIT
  • Event data:
    • DATA_CSAT_RATING
    • DATA_ADDITIONAL_FEEDBACK
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, CSAT_SUBMIT) == 0) {
        std::string data = eventData[DATA_CSAT_RATING].asString();
        // your code here
        //...
    }
}

Conversation End Event​

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

  • Event name: CONVERSATION_END
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, CONVERSATION_END) == 0) {
        // your code here
        //...
    }
}

Conversation Rejected Event​

This event is triggered when an agent rejects the conversation.

  • Event name: CONVERSATION_REJECTED
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, CONVERSATION_REJECTED) == 0) {
        // your code here
        //...
    }
}

Conversation Resolved Event​

This event is triggered when an agent resolves the conversation.

  • Event name: CONVERSATION_RESOLVED
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, CONVERSATION_RESOLVED) == 0) {
        // your code here
        //...
    }
}

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: CONVERSATION_REOPENED
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, CONVERSATION_REOPENED) == 0) {
        // your code here
        //...
    }
}

User Authentication Failed Event​

If you have User Authentication feature enabled on the Dashboard and if you pass an invalid token in the HelpshiftCocos2dx::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
void handleAuthFailureEvent(HSAuthenticationFailureReason reason) {
    // your code here
    // ...
}

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: SDK_SESSION_STARTED
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, SDK_SESSION_STARTED) == 0) {
        // your code here
        //...
    }
}

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: SDK_SESSION_ENDED
void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    if (strcmp(eventName, SDK_SESSION_ENDED) == 0) {
        // your code here
        //...
    }
}

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: RECEIVED_UNREAD_MESSAGE_COUNT
  • Event Data: DATA_MESSAGE_COUNT and DATA_MESSAGE_COUNT_FROM_CACHE
  // Call to get unread message count from Helpshift
  void getUnreadMessageCount(Ref *pSender) {
    bool shouldFetchFromServer = true;
    HelpshiftCocos2dx::requestUnreadMessageCount(shouldFetchFromServer);
  }

  void updateBadgeCount(int count) {
    // Your UI Logic here
  }

  void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
      if (strcmp(eventName, RECEIVED_UNREAD_MESSAGE_COUNT) == 0) {
          if (eventData.find(DATA_MESSAGE_COUNT) != eventData.end()) {
            int count = eventData[DATA_MESSAGE_COUNT].asInt();
            bool countFromCache = eventData[DATA_MESSAGE_COUNT_FROM_CACHE].asBool();
            // Use the 'count' variable for further processing
            updateBadgeCount(count);
        }
      }
  }

If you call the method HelpshiftCocos2dx::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, HelpshiftCocos2dx::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.

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

IDENTITY_DATA_LIMIT_EXCEEDED​

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

  • APIs - addUserIdentities
  • Data - nil

IDENTITY_DATA_SYNC_FAILED​

User identities failed to sync with backend

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

APP_ATTRIBUTES_LIMIT_EXCEEDED / MASTER_ATTRIBUTES_LIMIT_EXCEEDED​

Number of unsynced app or master attributes exceeds the permissible limit

  • APIs - updateAppAttributes, updateMasterAttributes
  • Data - nil

APP_ATTRIBUTES_VALIDATION_FAILED / MASTER_ATTRIBUTES_VALIDATION_FAILED​

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

APP_ATTRIBUTES_SYNC_FAILED / MASTER_ATTRIBUTES_SYNC_FAILED​

Attributes failed to sync with backend

  • APIs - updateAppAttributes, updateMasterAttributes

Data -

KeyValueRecovery
One of the passed attribute keysINVALID_DATANA

IDENTITY_FEATURE_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