App ID and App Key

You'll need these keys to integrate with Hotline from your Settings page ( . Do not share them with anyone.

Getting started

Follow these simple steps to integrate Hotline with your iOS app.
Our library contains a slice for arm64 architecture, and supports only iOS 7.0 and above. If you need to support iOS versions below 5.1.1, or for older Xcode versions, reach out to us at

Step 1 : Add Hotline to your project

Add Hotline to your project in a single step by updating your podfile to include Hotline as below    

pod 'HotlineSDK'


Step 2: Initialize and configure Hotline for your App

1. Import "Hotline.h" in your AppDelegate.m file

2. Initialize Hotline by pasting the following snippet in your -[AppDelegate application:didFinishLaunchingWithOptions:] method                    

#define SYSTEM_VERSION_GREATER_THAN_OR_EQUAL_TO(v)  ([[[UIDevice currentDevice] systemVersion] compare:v options:NSNumericSearch] != NSOrderedAscending)

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{

/* Initialize Hotline*/

HotlineConfig *config = [[HotlineConfig alloc]initWithAppID:@"<App ID>"  andAppKey:@"<App Key>"];

[[Hotline sharedInstance] initWithConfig:config];

/* Enable remote notifications */

UIUserNotificationSettings *settings =
[UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound categories:nil];
[[UIApplication sharedApplication] registerUserNotificationSettings:settings];
[[UIApplication sharedApplication] registerForRemoteNotifications];


[[UIApplication sharedApplication] registerForRemoteNotificationTypes:(UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound | UIRemoteNotificationTypeAlert)];


[self.window makeKeyAndVisible]; // or similar code to set a visible view

/*  Set your view before the following snippet executes */

/* Handle remote notifications */
if ([[Hotline sharedInstance]isHotlineNotification:launchOptions]) {
[[Hotline sharedInstance]handleRemoteNotification:launchOptions

/* Any other code to be executed on app launch */

/* Reset badge app count if so desired */
[[UIApplication sharedApplication] setApplicationIconBadgeNumber:0];

return YES;


3. Set options as config options as needed

You can turn-on/turn-off features like voice messaging at the initialization. Use the snippet below ahead of calling the initWithConfig: method to configure Hotline features as desired.     

config.displayFAQsAsGrid = YES; // set to NO for List View
config.voiceMessagingEnabled = YES; // set NO to disable voice messaging
config.pictureMessagingEnabled = YES; // set NO to disable picture messaging (pictures from gallery/new images from camera)
config.cameraCaptureEnabled = YES; // set to NO for only pictures from the gallery (turn off the camera capture option)
config.agentAvatarEnabled = YES; // set to NO to turn of showing an avatar for agents. to customize the avatar shown, use the theme file
config.showNotificationBanner = YES; // set to NO if you don't want to show the in-app notification banner upon receiving a new message while the app is open 


 Note: Check Step 5 below to make sure it is compatible with iOS10. 

4. In your AppDelegate file, include the snippet below in [AppDelegate applicationDidBecomActive:]]


- (void)applicationDidBecomeActive:(UIApplication *)application{
/* Reset badge app count if so desired */
[[UIApplication sharedApplication] setApplicationIconBadgeNumber:0];



5. To enable Hotline to send push notifications to the application, add this implementation of - application:didRegisterForRemoteNotificationsWithDeviceToken: in your AppDelegate file that captures the device token and sends it to Hotline servers      
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
[[Hotline sharedInstance] updateDeviceToken:devToken];


Step 3: Handling Push notifications


-[Hotline isHotlineNotification:] returns a BOOL. If remote notification was not sent by Hotline, it returns NO and you can insert code to handle other notifications based on this check.

In your AppDelegate.m, insert the following method       

- (void) application:(UIApplication *)app didReceiveRemoteNotification:(NSDictionary *)info{
    if ([[Hotline sharedInstance]isHotlineNotification:info]) {
        [[Hotline sharedInstance]handleRemoteNotification:info andAppstate:app.applicationState];


Step 4: Entry points in the UI

Import "HotlineSDK/Hotline.h" into the class from which you want to invoke the Hotline SDK’s Conversation interface or FAQ interface.


To bring up the Hotline’s FAQ overlay at any point, you need to use -[[Hotline sharedInstance] presentSolutions:] method.

For example, if you were bringing up the feedback overlay on a button press, the target method in a ViewController class could look like:


- (IBAction)showFeedbackOverlay:(id)sender {
[[Hotline sharedInstance] showFAQs:self];


Customising FAQ Options: 

There are few options to customise the FAQ Flow exposed via the FaqOptions class. This can be configured and passed on to the FAQOptions() method. 

Sample Code:

FAQOptions *options = [FAQOptions new];
options.showContactUsOnFaqScreens = NO;
[[Hotline sharedInstance]showFAQs:self withOptions:options];


Filtering FAQ : 

You can filter and show only FAQs tagged with a specific term. The tags can be setup from the dashboard. 

Eg: To show FAQs related to payment failure, those specific FAQs  can be tagged with "payment_failure" tag and can be filtered and shown to users. This will show a list of filtered articles to the user. 

Sample Code: 


FAQOptions *options = [FAQOptions new];
[options filterByTags:@[ @"payment", @"billing" ] withTitle:@"Filtered_View_title" andType: ARTICLE];
[[Hotline sharedInstance]showFAQs:self withOptions:options];


You can also filter  categories by tags. This will show a filtered view of categories ( under which articles would be listed). This is useful to show different sets of categories to different customers ( e.g. Paid Customers Vs Free Customers ). 


FAQOptions *options = [FAQOptions new];
[options filterByTags:@[ @"payment", @"billing" ] withTitle:@"Filtered_View_title" andType: CATEGORY];
[[Hotline sharedInstance]showFAQs:self withOptions:options];

Note : When you filter by article type , the tags for category the articles belong to are also applied to articles. 


To bring up the Hotline’s Conversations List or single conversation overlay at any point, you need to use -[[Hotline sharedInstance] presentConversations:] method.

For example, if you were bringing up the feedback overlay on a button press, the target method in a ViewController class could look like:


- (IBAction)showFeedbackOverlay:(id)sender {
    [[Hotline sharedInstance] showConversations:self];


Filtering Channels: 

Different sets of channels can be made available for different sets of users by filtering Channels by tags. 

ConversationOptions *options = [ConversationOptions new];
[options filterByTags:@[ @"all", @"paiduser" ] withTitle:"Support"];
[[Hotline sharedInstance] showConversations:self withOptions: options];

If you are using FAQs as well in your app, you can make sure that when the user click contact us from FAQ section, the user still gets a filtered view. 

FAQOptions *options = [FAQOptions new];
[options filterContactUsByTags:@[ @"all", @"paiduser" ] withTitle:"Support"];
[[Hotline sharedInstance]showFAQs:self withOptions:options];

The contactUsTags  can also be used to show a different set of channels when the user comes from the self help section. 

Step 5: iOS 10 Compatibility: 

Starting iOS 10, Apple requires developers to declare access to privacy-sensitive controls ahead of time.


To comply with this new privacy requirement, developers must add the required keys to the Info.plist:

"NSMicrophoneUsageDescription" "NSPhotoLibraryUsageDescription" and "NSCameraUsageDescription" 
Moreover, we will also log a warning message on the XCode console if you have missed adding the required keys.  

Warning! Failing this iOS 10 will exit the app by crashing when user tries to access the controls of microphone, camera or photo library.
For more clarification, click 

iOS 10 Simulator issue 

 Hotline SDK depends on keychain services. Xcode 8.0 (8A218a) /  iOS 10 simulators have an issue with keychain services, which does not allow the SDK to retrieve data from the store when there are no "entitlements" set up. We expect this issue will be fixed in the later version of Xcode. In the meantime, we suggest the following workaround to continue testing on the iOS 10 simulators.


In the project’s capabilities page, please turn on push notifications capability (and select the "fix issue" if any issue appears). This is a work around to ensure there is a valid entitlement file for the project (which the simulator requires to work correctly), and once testing is done you can discard these changes. Hopefully the issue will be resolved in the next Xcode update.

Step 6: Uploading your App’s SSL Push Certificate


1. Go to the Mac OS finder application, and search for “Keychain Access”. Open it. 
2. Find your App’s push certificate in the Certificates section. It will start with the string “"Apple Development iOS Push Services" (“Apple Production iOS push services” in case of production certificate) 
3. Expand the row, and you will find the private key. 
4. Select both the private key and certificate and export it as .p12 file and necessarily set a password.
5. Upload the saved .p12 file in the field below selecting development environment or production environment depending on whether you are using it for dev or production push services.

Upload your development / production certificate at from this link:

NOTE: Use an account with Hotline exclusively for Production or Development purposes. Do not use the same account for different environments - Apple fails push messages batches when it gets device tokens that are invalid for that environment. Create a new account if you need an additional environment.


Do more with Hotline         

* Following three methods are to identify a user.
* These user properties will be viewable on the Hotline web dashboard.
* The externalID (identifier) set will also be used to identify the specific user for any APIs 
* targeting a user or list of users in pro-active messaging or marketing

// Create a user object
HotlineUser *user = [HotlineUser sharedInstance];

// To set an identifiable name for the user = @"John Doe";

//To set user's email id = @"";

//To set user's phone number
user.phoneNumber = @"9790987495";

//To set user's identifier (external id to map the user to a user in your system. Setting an external ID is COMPULSARY for many of Hotline’s APIs


[[Hotline sharedInstance] updateUser:user];

/* Custom properties & Segmentation - You can add any number of custom properties. An example is given below.
These properties give context for your conversation with the user and also serve as segmentation criteria for your marketing messages */

//You can set custom user properties for a particular user
[[Hotline sharedInstance] updateUserPropertyforKey:@"customerType" withValue:@"Premium"];
//You can set user demographic information
[[Hotline sharedInstance] updateUserPropertyforKey:@"city" withValue:@"San Bruno"];
//You can segment based on where the user is in their journey of using your app
[[Hotline sharedInstance] updateUserPropertyforKey:@"loggedIn" withValue:@"true"];
//You can capture a state of the user that includes what the user has done in your app
[[Hotline sharedInstance] updateUserPropertyforKey:@"transactionCount" withValue:@"3"];

/* If you want to indicate to the user that he has unread messages in his inbox, you can retrieve the unread count to display. */
//returns an int indicating the of number of unread messages for the user
[[Hotline sharedInstance] getUnreadMessagesCount]; 

/* Managing Badge number for unread messages - Manual
If you want to listen to a local notification and take care of updating the badge number yourself, listen for a notification with name "HOTLINE_UNREAD_MESSAGE_COUNT " as below

[[NSNotificationCenter defaultCenter]addObserverForName:HOTLINE_UNREAD_MESSAGE_COUNT object:nil queue:nil usingBlock:^(NSNotification *note) {
        NSLog(@"updated unread messages count %@", note.userInfo[@"count"]);





UI Customization options

Modify our default theme file HLTheme.plist to customize the interface or you could link your own custom theme file to the SDK by using the following snippet 
 [config setThemeName:@"<Theme name>"];


For more on theming and customization, please refer to this guide

String Customizations 

All strings used in the Hotline SDK UI can be customized and localized in multiple languages. 

You can do the following to customize your SDK. 

Creating a bundle 

Locate the HLLocalization.bundle in the HotlineSDK pod or  Download the HLLocalization.bundle from here. You can rename the file to a custom name.   

The structure of the bundle folder would be as follows:  

Sample bundle structure containing strings for English, French and German. 


Changing strings 

  1. In order to change a specific string used in the SDK UI, just update the appropriate key in HLLocalizable.strings. The keynames in the file are categorized by UI and the keys used are self explanatory. 
  2. Do the same for all the languages you wish to support
  3. SDK comes with only English at the moment, but you will be able to use translations for any language you want.

Linking to project

  1. Once you have changed all the required strings in the languages that you are supporting, link it under “Build Phases”  > “Copy Bundle Resources”  
  2. When you are initializing the SDK,  specify that bundle name as part of hotline config.
    config.stringsBundle = @"MyCustomBundle";


  1. Bundle name is case-sensitive
  2. extension .bundle is not required


Once you have made the changes, please run the app to verify the changes on the SDK UI. 


Checklist for launch: 

  1. Ensure you have the latest SDK
  2. Ensure you are initializing the SDK at the starting of application: didFinishLaunchingWithOptions: function
  3. Check if push notification is working properly when the app is in foreground, background and in killed state with production certificate
  4. See our Theming and Customization document here to make sure you are matching the experience with the rest of your app
  5. Configure your default channel name and welcome message right even if you aren't using other channels
  6. Capture the unique user identifier, email, phone number, or any other unique customer identifiers with the SDK to ensure smooth use of APIs, as well as for best use of our "Smart Plugs" feature on the dashboard.
  7. Ensure the push notifications are working for new installs as well as upgrades from your previous versions.

We have hosted a sample project which you could try use to try out our SDK APIs, which can be accessed from this link: