Looking for older SDK 3.X docs? Click here →

Helpshift APIs

Helpshift provides a way to use each functional element of the SDK separately based on your requirements. You can call only specific screens from the SDK based on the functionality you want to expose in your app.

Helpshift provides a way to use each functional element of the SDK separately based on your requirements. You can call specific screens from the SDK based on the functionality you want to expose in your app.

There are 6 ways to call Helpshift in your app:

  1. showConversation
  2. showFAQs
  3. showFAQSection
  4. showSingleFAQ
  5. Guided Issue Filing
  6. Add FAQs to Spotlight search

Currently any support session is presented only as a modalViewController and you cannot embed the UIView into your own UIViewController. iPad now supports two different modal presentation styles from SDK v4.2.0. Please refer API Options.

showConversation

You can use the api call showConversation:withOptions: to allow a user to directly send feedback or start a new conversation without having to first view FAQs. Once, a user starts a new conversation, this API call will show the conversation screen. The conversation will continue until it is resolved or rejected by the agent.

Definition
showConversation:withConfig:
Example Code
[HelpshiftSupport showConversation:self withConfig:nil]; // where self is the view controller you're calling Helpshift from
Use with
"Contact Us" or "Send Feedback" button

Definition
showConversation:withOptions:
Example Code

[HelpshiftSupport showConversation:self withOptions:nil]; // where self is the view controller you're calling Helpshift from

Use with

"Contact Us" or "Send Feedback" button

Supports these API Options.

From SDK version v4.13.0 as a measure to avoid users from filing tickets that don’t make sense (read, empty tickets, tickets that just say “hi” or “help” etc.), the SDK checks the content of the users question before he is allowed to file it. There is a minimum character limit for filing a ticket. This value comes from the localisation file of the current SDK language. This allows each language to have its own minimum character limit defined.

The localisation file contains a key value pair:

"IssueDescriptionMinimumCharacterLength" = 5;

The value for the key needs to be an unsigned integer value that represents a minimum limit character count for each language.

In case of a invalid value for this key or in case this key is missing from your localisation, a fallback value will be used by the SDK.

showFAQs

You can use the api call showFAQs:withOptions: to show FAQs in your app. This is the easiest approach to enable help in your app as it bundles all the capabilities of the Helpshift SDK in a simple and intuitive interface. Users can browse FAQs, search for an FAQ, and file issues with Support.

Definition
showFAQs:withConfig:
Example Code
[HelpshiftSupport showFAQs:self withConfig:nil]; // where self is the view controller you're calling Helpshift from
Use with
"Help" or "Support" button

Definition
showFAQs:withOptions:
Example Code
[HelpshiftSupport showFAQs:self withOptions:nil]; // where self is the view controller you're calling Helpshift from
Use with
"Help" or "Support" button

Supports these API Options.

English translation will be used for non-localized FAQs To use deep linking in your app using Helpshift FAQs, check here.

FAQ Filtering by tags

Starting v4.14.0 onwards, we have introduced FAQ filtering capability by tags. With the goal of helping the end user see focused & related content e.g. basis the user demographic or device profiles, developers can now choose the new capability for FAQ filtering and showing a focused FAQ list to the right audience.

Typical cases why you would want to use FAQ filtering are :

  • You want to show specific FAQs for specific audience. E.g. if you may categorize the users as ‘beginner’, ‘intermediate’ or ‘expert’ based on your business logic.
  • You may want to show specific FAQs based on the device. E.g. a set of FAQs for iPad vs. iPhone.

FAQ filtering is a 2 step approach :

  1. FAQs need to be classified using the field on the dashboard e.g. tags iphone & ipad. show me
  2. Once the FAQs are tagged, they can be filtered at the SDK using the filter options described here.

Helpshift has 2 types of tags mainly ‘Issue Tags’ & ‘Search Tags’.

  • Issue tags are used to filter the FAQ list on the SDK with the filter rules.
  • Search tags (a.k.a Search Keywords) When performing in-app search, Helpshift SDK gives preference to these keywords. You can also use this to add alternative keywords that users might search for, but which may not exist in the FAQ title or the content.

How to use FAQ filtering

This will be a config option which will be supported by the showFAQs and showFAQSection APIs.

The withTagsMatching option will be a dictionary containing 2 keys

  • operator : one of and, or, not which will serve as conditional operators for the given tags.
  • tags : the actual tags in the query

The withTagsMatching option will be should be added as an object against key “withTagsMatching ” in the dictionary optionsDictionary that is taken by showFAQs and showFAQSection APIs.

//If the developer wants to show all FAQs with tags iPad or iPhone
HelpshiftAPIConfigBuilder *apiBuilder = [[HelpshiftAPIConfigBuilder alloc] init];
apiBuilder.withTagsMatching = [[HelpshiftFAQFilter alloc] initWithFilterOperator:HsOperatorOr / HsOperatorAnd / HsOperatorNot andTags:@[@"tag1",@"tag2",...]];
HelpshiftAPIConfig *apiConfigObject = [apiBuilder build];
[HelpshiftSupport showFAQs:self withConfig:apiConfigObject];

//If the developer wants to show all FAQs with tags iPad or iPhone
NSDictionary * optionsDictionary = @{ @"withTagsMatching" : @{ @"operator" : @"or",
                                                               @"tags" : @[@"iPhone",@"iPad"]}};
[HelpshiftSupport showFAQs:self withOptions:optionsDictionary];

As of v4.14.0 you can have only one tag filter config which will be respected on showFAQs and showFAQSection. Also the tag filtering respects only one operator.

showFAQSection

You can use the api call showFAQSection:withController:withOptions: to show faqs from a particular FAQ section. This feature works like a permalink for displaying specific FAQ sections as context sensitive help in your app. For example, if your app requires the user to log in using email, facebook and twitter, you could wire a help action on the login screen that can link to the Helpshift FAQ section called "Login help" which has several questions related to login methods.

You will need the Section Publish ID from the FAQ tab of Helpshift Dashboard:

Definition
showFAQSection:withController:withConfig:
Example Code
[HelpshiftSupport showFAQSection:@"1" withConfig:nil] // where self is the view controller you're calling Helpshift from and @"1" is the FAQ section publish-id
Use with
"Login Help" or other category-specific sections

Definition
showFAQSection:withController:withOptions:
Example Code
[HelpshiftSupport showFAQSection:@"1"] // where self is the view controller you're calling Helpshift from and @"1" is the FAQ section publish-id
Use with
"Login Help" or other category-specific sections

Supports these API Options.

English translation will be used for non-localized FAQs.

showSingleFAQ

You can use the api call showSingleFAQ:withController:withOptions: to show a single faq question.

You will need the FAQ Publish ID from the FAQ tab of the Helpshift Dashboard:

/ .full-width /

Definition
showSingleFAQ:withController:withConfig:
Example Code
[HelpshiftSupport showSingleFAQ:@"1" withController:self withConfig:nil];
Use with
a '?' button when your user is performing a specific action

Definition
showSingleFAQ:withController:withOptions:
Example Code
[HelpshiftSupport showSingleFAQ:@"1" withController:self withOptions:nil];
Use with
a '?' button when your user is performing a specific action

Supports these API Options.

English translation will be used for non-localized FAQs

Guided Issue Filing

Applicable to version 5.1.0 and above.

Guided issue filing is a feature to capture more context when a user interacts with Helpshift Support. For example, lets say you want the user to file a ticket in case of a complaint and also in case he want to suggest a feature. With dynamic forms, you will now be able to distinguish between these two use cases and take required actions (like assigning appropriate agents).

Dynamic forms also enable better FAQ discovery. Lets say there is a frequently viewed FAQ or FAQ section buried deep in your FAQ hierarchy. Some users might miss it out and opt to file an issue instead. With dynamic forms, you can create a new section (like top FAQs) that links to that FAQ section. Or create and alternate title to an FAQ (like 'How do I pay for gems' instead of 'Billing').

The app configures a dynamic form using 'flows'. There are 6 types of flows:

Flow to show conversation screen

  • + (id) flowToShowConversationWithDisplayText:(NSString *)displayText andConfig:(HelpshiftAPIConfig *)configObject;
  • similar to the showConversation: API

  • + (id) flowToShowConversationWithDisplayText:(NSString *)displayText andConfigOptions:(NSDictionary *)configOptions;
  • similar to the showConversation: API

Flow to show all FAQs

  • + (id) flowToShowFAQsWithDisplayText:(NSString *)displayText andConfig:(HelpshiftAPIConfig *)configObject;
  • similar to the showFAQs: API

  • + (id) flowToShowFAQsWithDisplayText:(NSString *)displayText andConfigOptions:(NSDictionary *)configOptions;
  • similar to the showFAQs: API

Flow to show a FAQ section

  • + (id) flowToShowFAQSectionForPublishId:(NSString *)sectionPublishId withDisplayText:(NSString *)displayText andConfig:(HelpshiftAPIConfig *)configObject;
  • similar to the showFAQSection: API

  • + (id) flowToShowFAQSectionForPublishId:(NSString *)sectionPublishId withDisplayText:(NSString *)displayText andConfigOptions:(NSDictionary *)configOptions;
  • similar to the showFAQSection: API

Flow to show a single FAQ

  • + (id) flowToShowSingleFAQForPublishId:(NSString *)FAQPublishId withDisplayText:(NSString *)displayText andConfig:(HelpshiftAPIConfig *)configObject;
  • similar to the showSingleFAQ: API

  • + (id) flowToShowSingleFAQForPublishId:(NSString *)FAQPublishId withDisplayText:(NSString *)displayText andConfigOptions:(NSDictionary *)configOptions;
  • similar to the showSingleFAQ: API

Flow to show a nested Dynamic form

  • + (id) flowToShowNestedDynamicFormWithFlows:(NSArray *)nextDynamicFormFlows withDisplayText:(NSString *)displayText;

Flow to perform a custom action

  • + (id) flowToPerformCustomActionOnTarget:(id)target andSelector:(SEL)selector withOptionalObject:(id)optionalObject withDisplayText:(NSString *)displayText;

Each flow need a display text. This will be the text that will be displayed in the row. It has to be localised NSString. Some flows also expect a 'configOptions' dict. This will be the config that is passed to the subsequent Support API. For example any config you wish apply to the conversation screen needs to be passed to the flowToShowConversationWithDisplayText: API. This is also where you will add your custom HelpshiftSupportTags.

The app can create any number of flows. These flows are then grouped into a dynamic form and displayed in a tabular form. There are three ways to display a dynamic form:

  1. Present modally

    • + (BOOL) showDynamicFormOnViewController:(UIViewController *)viewController withTitle:(NSString *)title andFlows:(NSArray *)flows withConfigOptions:(NSDictionary *)configOptions;

    This option accepts an optional configOptions NSDictionary (similar to showConversation: or showFAQs: API). These options only apply to the dynamic form itself and not the included flows. Any config that needs to be applied to a flow will have to be provided in the flow APIs. The only configOption currently available here right now is 'presentFullScreenOniPad' which can be set to 'yes' or 'no'.

  2. Push on current navigation controller stack

    • + (BOOL) pushDynamicFormOnViewController:(UIViewController *)viewController withTitle:(NSString *)title andFlows:(NSArray *)flows;
  3. Get an embeddable UIViewController (for use in UITabBarController)

    • + (UIViewController *) dynamicFormWithTitle:(NSString *)title andFlows:(NSArray *)flows;

Each dynamic form needs :

  1. Title: This will be the title displayed on the action bar
  2. flows: An List of supported Flow objects as discussed above.

Add FAQs to Spotlight search

Applicable to SDK v5.1.0 and above.

Search in iOS 9 gives users great new ways to access information inside of your app. When you make your content searchable, users can access activities and content deep within your app through Spotlight and Safari search results, Handoff, and Siri suggestions. Using APIs related to search, you decide what content gets indexed, what information to show in search results, and where the user is redirected after tapping a result from your app.

The Helpshift SDK can now use these new APIs to add all of your FAQs to the on-device search index. This will ensure that the FAQs that you have added will get maximum visibility. This will also help ensure that your users find solutions to their problems easily and help reduce support tickets and eventually churn.

Install config Option
addFaqsToDeviceSearch
Values
HsAddFaqsToDeviceSearchOnInstall / HsAddFaqsToDeviceSearchAfterViewingFAQs / HsAddFaqsToDeviceSearchNever

Install config Option
addFaqsToDeviceSearch
Values
on_install / after_viewing_faqs / never

on_install / HsAddFaqsToDeviceSearchOnInstall : This will fetch and add FAQs to the CoreSpotlight index right after your application calls Helpshift's install method. We will make sure to do all the fetching on background threads so that we do not affect the Application's responsiveness. Since FAQs are not something that is updated very frequently, we have capped the number of fetches to only 4 per day. So in-effect the SDK will scan for new FAQs only once every 6 hours.

after_viewing_faqs / HsAddFaqsToDeviceSearchAfterViewingFAQs : This will add FAQs to the CoreSpotlight index only after the user actually opens the Help section (wired to the showFAQs and showFAQSection APIs).

never / HsAddFaqsToDeviceSearchNever : The Helpshift SDK will not add FAQs to the CoreSpotlight index.

For the search entry to launch the appropriate FAQ screen, the application should forward the hand off delegate to Helpshift via the

[HelpshiftSupport handleContinueUserActivity:userActivity withController:viewController andRestorationHandler:restorationHandler]

Example :

- (BOOL) application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *))restorationHandler {
    NSString *activityIdentifier = [userActivity.userInfo objectForKey:CSSearchableItemActivityIdentifier];
    if(activityIdentifier && [activityIdentifier hasPrefix:@"helpshift_faq_"]) {
        return [HelpshiftSupport handleContinueUserActivity:userActivity withController:[UIApplication sharedApplication].keyWindow.rootViewController andRestorationHandler:restorationHandler];
    }
    return NO;
}

displayAttachmentFileAtLocation

Applicable to SDK v4.10.0 and above

Agents can attach a wide variety of files when replying to users. Following types of file formats are currently supported:

  • iWork documents
  • Microsoft Office documents (Office ‘97 and newer)
  • Rich Text Format (RTF) documents
  • PDF files
  • Images
  • Text files whose uniform type identifier (UTI) conforms to the public.text type
  • Comma-separated value (csv) files
  • Video files (3gp, m4v)
  • Audio files (mp3, mp4, aac)
  • Image files (jpg, png, gif)

A new API displayAttachmentFileAtLocation:onViewController: lets the app capture the tap event on an attachment and present it to the user. If the app wants to handle the previewing of attachments itself, it must return true for this call.

If the app does not wish to display the attachment, it can return false. In this case the SDK will display the attachment itself using the QLPreviewController.

Please note that the app needs to include the Quick Look Framework

Besides providing the ability to preview all the supported documents type, Quick Look also provides a sharing/printing widget and full screen viewing.

Close Helpshift Session

This API can be used to close an active Helpshift session and return to the app. Any open Helpshift screen will be dismissed and control will return to the original UIViewController that launched the Helpshift screen.

This API has no affect on any open issue. Users will continue to see their messages next time a Helpshift session is launched.

Definition
closeHelpshiftSupportSession
Example Code
[HelpshiftSupport closeHelpshiftSupportSession];

Extra APIs

This section lists down the extra APIs which need to be implemented in order for the Helpshift SDK to function correctly, if the developer has not enabled the -ObjC flag in the Other Linker Flags section.

Handle events for background

The Helpshift SDK uses background session calls for sending app data to the server. In order for this to work correctly, the app developer needs to listen to the application:handlleEventsForBackgroundURLSession:completionHandler: and call the below Helpshift API

[HelpshiftCore handleEventsForBackgroundURLSession:completionHandler:];

For example,

- (void) application:(UIApplication *)application
handleEventsForBackgroundURLSession:(NSString *)identifier
completionHandler:(void (^)())completionHandler {
    [HelpshiftCore handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler];
}

This function will return a BOOL to indicate if the Helpshift SDK has handled the event.