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 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 before calling the Conversation API so that they can callback your delegate methods.

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.