Helpshift Delegates

The Helpshift delegate provides callbacks/events to help app developers track global events generated by the SDK.

Note

All the public APIs in the SDK should be called after initializing the SDK via Helpshift installWithPlatformId API

Helpshift Delegates implementation

You have to define a class which implements Helpshift Support Delegates and then pass this to Helpshift by setting the delegate property of the sharedInstance.

Example

Objective-C

// Class implementation
#import <Foundation/Foundation.h>
@import HelpshiftX;

@interface MyDelegates ()<HelpshiftDelegate>
@end

@implementation MyDelegates

- (void) handleHelpshiftEvent:(NSString *)eventName withData(NSDictionary *)data {
    // your code here
}

- (void) authenticationFailedForUserWithReason(HelpshiftAuthenticationFailureReason)reason {
    // your code here
}

@end

// Class Usage
@property (strong, nonatomic) MyDelegate *delegate;
....
delegate = [[MyDelegates alloc] init];
Helpshift.sharedInstance.delegate = self;

Swift

import Foundation
import HelpshiftX

// Class implementation
class HelpshiftDelegateHandler: HelpshiftDelegate {
    func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
        // Your code here
    }

    func authenticationFailedForUser(with reason: HelpshiftAuthenticationFailureReason) {
        // Your code here
    }
}

// Class usage
let delegateHandler = HelpshiftDelegateHandler()
Helpshift.sharedInstance().delegate = delegateHandler

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.

Helpshift Events

Conversation Status Event

This event contains information about the current ongoing conversation.

• Event name: HelpshiftEventNameConversationStatus
  
• Event Data:
  • HelpshiftEventDataLatestIssueId
    
  • HelpshiftEventDataLatestIssuePublishId
    
  • HelpshiftEventDataIsIssueOpen

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationStatus]) {
        NSLog(@"Issue ID: %@", data[HelpshiftEventDataLatestIssueId]);
        NSLog(@"Publish ID: %@", data[HelpshiftEventDataLatestIssuePublishId]);
        NSLog(@"Is issue open: %@", data[HelpshiftEventDataIsIssueOpen]);
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationStatus {
        guard let data = data else { return }
        let issueId = data[HelpshiftEventDataLatestIssueId]
        let publishId = data[HelpshiftEventDataLatestIssuePublishId]
        let issueOpen = data[HelpshiftEventDataIsIssueOpen]

        print("Issue id \(issueId), publishId: \(publishId), issueOpen: \(issueOpen)")
    }
}

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:

• Event name: HelpshiftEventNameWidgetToggle
• Event data: HelpshiftEventDataVisible

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameWidgetToggle]) {
        NSLog(@"Is chat screen visible: %@", data[HelpshiftEventDataVisible]);
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameWidgetToggle {
        guard let data = data else { return }
        let widgetStatus = data[HelpshiftEventDataVisible]
        print("Is chat screen visible: \(widgetStatus)")
    }
}

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: HelpshiftEventNameConversationStart
• Event Data: HelpshiftEventDataMessage

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationStart]) {
        NSLog(@"Conversation started with text: %@", data[HelpshiftEventDataMessage]);
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationStart {
        guard let data = data else { return }
        let messageBody = data[HelpshiftEventDataMessage]
        print("Conversation started with text: \(messageBody))")
    }
}

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: HelpshiftEventNameMessageAdd
• Event Data:
  • HelpshiftEventDataMessageType
  • HelpshiftEventDataMessageTypeText
  • HelpshiftEventDataMessageTypeAttachment
  • HelpshiftEventDataMessageBody

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameMessageAdd]) {
        NSLog(@"New message added with body: %@", data[HelpshiftEventDataMessageBody]);
        NSLog(@"New message added with type: %@", data[HelpshiftEventDataMessageType]);
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameMessageAdd {
        guard let data = data else { return }
        let messageBody = data[HelpshiftEventDataMessageBody]
        let messageType = data[HelpshiftEventDataMessageType]
        print("Message: \(messageBody), type: \(messageType)")
    }
}

Agent Message Received Event

This event is triggered when the user receives any message from an agent in a conversation. It might be a text message, an attachment, app review request or a screenshot request. This delegate is not triggered for bot messages or messages sent via automations.

• Event name constant: HelpshiftEventNameAgentMessageReceived
• Event name raw value: agentMessageReceived
• Event data:

Key (Constant)	Key (Raw)	Type
HelpshiftEventDataPublishID	publishId	String
HelpshiftEventDataCreatedTime	createdTs	Number
HelpshiftEventDataMessageType	type	String
HelpshiftEventDataMessageBody	body	String
HelpshiftEventDataAttachments	attachments	Array

The attachments array is an array of dictionaries, with one dictionary for each attachment. The data for attachment dictionary is -

Key (Constant)	Key (Raw)	Type
HelpshiftEventDataURL	url	String
HelpshiftEventDataContentType	contentType	String
HelpshiftEventDataFileName	fileName	String
HelpshiftEventDataSize	size	Number

Note

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

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    if([eventName isEqualToString:HelpshiftEventNameAgentMessageReceived]) {
        NSLog(@"Conversation publish ID : %@", data[HelpshiftEventDataPublishID]);
        NSLog(@"Message created timestamp: %@", data[HelpshiftEventDataCreatedTime]);
        NSLog(@"Message type: %@", data[HelpshiftEventDataMessageType]);
        NSLog(@"Message body: %@", data[HelpshiftEventDataMessageBody]);

        NSArray<NSDictionary *> *attachments = data[HelpshiftEventDataAttachments];
        if(attachments) {
            NSLog(@"Message has %lu attachments", (unsigned long)attachments.count);
            for(NSDictionary *attachment in attachments) {
                NSLog(@"Attachment file name: %@", attachment[HelpshiftEventDataFileName]);
                NSLog(@"Attachment size: %@", attachment[HelpshiftEventDataSize]);
                NSLog(@"Attachment content type: %@", attachment[HelpshiftEventDataContentType]);
                NSLog(@"Attachment URL: %@", attachment[HelpshiftEventDataURL]);
            }
        } else {
            NSLog(@"Message has no attachments");
        }
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameAgentMessageReceived {
        print("Conversation publish ID : \(data![HelpshiftEventDataPublishID]!)")
        print("Message created timestamp: \(data![HelpshiftEventDataCreatedTime]!)")
        print("Message type: \(data![HelpshiftEventDataMessageType]!)")
        print("Message body: \(data![HelpshiftEventDataMessageBody]!)")
        if let attachments = data?[HelpshiftEventDataAttachments] as? [[AnyHashable: Any]] {
            print("Message has \(attachments.count) attachments")
            for attachment in attachments {
                print("Attachment file name: \(attachment[HelpshiftEventDataFileName]!)")
                print("Attachment size: \(attachment[HelpshiftEventDataSize]!)")
                print("Attachment content type: \(attachment[HelpshiftEventDataContentType]!)")
                print("Attachment URL: \(attachment[HelpshiftEventDataURL]!)")
            }
        } else {
            print("Message has no attachments")
        }
    }
}

User Click on Action Event

This event is triggered when the user clicks on the link or call action of an action card message. The event data object has actionType and actionData keys, which indicates the type of action and data associated with the action.

• Event name constant: HelpshiftEventNameUserClickOnAction
• Event name raw value: userClickOnAction
• Event Data:

Key (Constant)	Key (Raw)	Type
HelpshiftEventDataActionType	actionType	String
HelpshiftEventDataActionData	actionData	String

HelpshiftEventDataActionType can be one of -

• HelpshiftEventDataActionTypeCall or call
• HelpshiftEventDataActionTypeLink or link

Note

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

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameUserClickOnAction]) {
        NSLog(@"User click on action type: %@", data[HelpshiftEventDataActionType]);
        NSLog(@"Data for clicked action: %@", data[HelpshiftEventDataActionData]);
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameUserClickOnAction {
        print("User click on action type: \(data[HelpshiftEventDataActionType])")
        print("Data for clicked action: \(data[HelpshiftEventDataActionData])")
    }
}

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: HelpshiftEventNameCSATSubmit
• Event Data:
  • HelpshiftEventDataRating
  • HelpshiftEventDataAdditionalFeedback

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameCSATSubmit]) {
        NSLog(@"CSAT Submitted with rating: %@", data[HelpshiftEventDataRating]);
        NSLog(@"CSAT Submitted with feedback: %@", data[HelpshiftEventDataAdditionalFeedback]);
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameCSATSubmit {
        guard let data = data else { return }
        let rating = data[HelpshiftEventDataRating]
        let feedback = daat[HelpshiftEventDataAdditionalFeedback]
        print("CSAT Rating: \(rating), feedback:\(feedback))")
    }
}

Conversation End Event

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

• Event name: HelpshiftEventNameConversationEnd

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationEnd]) {
        NSLog(@"Conversation ended.");
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationEnd {
        print("Conversation ended")
    }
}

Conversation Rejected Event

This event is triggered when an agent rejects the conversation.

• Event name: HelpshiftEventNameConversationRejected

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationRejected]) {
        NSLog(@"Conversation rejected.");
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationRejected {
        print("Conversation rejected")
    }
}

Conversation Resolved Event

This event is triggered when an agent resolves the conversation.

Event name: HelpshiftEventNameConversationResolved

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationResolved]) {
        NSLog(@"Conversation resolved.");
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationResolved {
        print("Conversation resolved")
    }
}

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

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameConversationReopened]) {
        NSLog(@"Conversation reopened.");
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameConversationReopened {
        print("Conversation reopened")
    }
}

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:

• HelpshiftAuthenticationFailureReasonAuthTokenNotProvided
• HelpshiftAuthenticationFailureReasonInvalidAuthToken

Objective-C

- (void) authenticationFailedForUserWithReason:(HelpshiftAuthenticationFailureReason)reason {
    // Handle authentication failure
}

Swift

func authenticationFailedForUser(withReason reason: HelpshiftAuthenticationFailureReason) {
  // Handle authentication failure
}

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

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameSessionStarted]) {
        NSLog(@"Helpshift session started.");
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
        if eventName == HelpshiftEventNameSessionStarted {
            print("Helpshift 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: HelpshiftEventNameSessionEnded

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameSessionEnded]) {
        NSLog(@"Helpshift session ended.");
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
        if eventName == HelpshiftEventNameSessionEnded {
            print("Helpshift session ended.")
        }
}

Unread Message Count Event

If you want a count of all new messages received in an existing conversation, you can call this API [Helpshift requestUnreadMessageCount:];.

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: HelpshiftEventDataUnreadMessageCount
• Event data:
  • HelpshiftEventDataUnreadMessageCount
  • HelpshiftEventDataUnreadMessageCountIsFromCache

Example:

Objective-C

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameReceivedUnreadMessageCount]) {
        int count = data[HelpshiftEventDataUnreadMessageCount];
        NSLog(@"Unread count: %d", data[HelpshiftEventDataUnreadMessageCount]);
        NSLog(@"Is unreadCount served from local cache : %d", data[HelpshiftEventDataUnreadMessageCountIsFromCache]);
    }
}

Swift

func handleHelpshiftEvent(_ eventName: String, withData data: [AnyHashable : Any]?) {
    if eventName == HelpshiftEventNameReceivedUnreadMessageCount {
        guard let data = data else { return }
        let count = data[HelpshiftEventDataUnreadMessageCount] as? Int
        let isFromCache = data[HelpshiftEventDataUnreadMessageCount] as? Bool
        print("Count: \(count), fromCache: \(isFromCache)")
    }
}

If you call the method [Helpshift requestUnreadMessageCount:YES]; 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:NO];. 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

HelpshiftIdentityTokenInvalid

Identities JWT not in valid format

• APIs - addUserIdentities
• Data - nil

HelpshiftIatIsMandatory

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

• APIs - addUserIdentities
• Data - nil

HelpshiftIdentitiesDataInvalid

Some of the identities in the JWT payload are not valid

• APIs - addUserIdentities
• Data -

Key	Value	Recovery
One of the passed identity keys	HelpshiftKeyLengthLimitExceeded	Ensure key length is within permissible limit
One of the passed identity keys	HelpshiftValueLengthLimitExceeded	Ensure value length is within permissible limit
One of the passed identity keys	HelpshiftEmptyData	Ensure key or value is a valid non-empty value
One of the passed identity keys	HelpshiftMetadataCountLimitExceeded	Ensure total number of entries in metadata dictionary for this identity is within permissible limit
One of the passed identity metadata keys	HelpshiftMetadataKeyLengthLimitExceeded	Ensure metadata key length is within permissible limit
One of the passed identity metadata keys	HelpshiftMetadataValueLengthLimitExceeded	Ensure metadata value length is within permissible limit
One of the passed identity metadata keys	HelpshiftMetadataEmptyKeyOrValue	Ensure metadata key or value is a valid non-empty value

HelpshiftIdentitiesSizeLimitExceeded

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

• APIs - addUserIdentities
• Data - nil

HelpshiftEventAddUserIdentitiesSyncFailed

User identities failed to sync with backend

• APIs - addUserIdentities
• Data -

Key	Value	Recovery
One of the passed identity keys	HelpshiftInvalidData	NA

HelpshiftEventAppAttributesLimitExceeded / HelpshiftEventMasterAttributesLimitExceeded

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 -

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

HelpshiftEventUpdateAppAttributesSyncFailed / HelpshiftEventUpdateMasterAttributesSyncFailed

Attributes failed to sync with backend

• APIs - updateAppAttributes, updateMasterAttributes

Data -

Key	Value	Recovery
One of the passed attribute keys	HelpshiftInvalidData	NA

HelpshiftEventUserIdentityNotEnabled

Identity feature is not enabled for your domain

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

HelpshiftEventUserSessionExpired

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

HelpshiftEventRefreshUserCredentials

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