integrations:mobile-chat-ios

Mobile chat for iOS

With embeddable chat for iOS applications, your users can contact support from within the app and get help. Your support specialists will process tickets in Pyrus even if these messages come from a smartphone messenger app.

You can use the default chat or customize it for your app. You can also receive files and subscribe the userclient to push notifications about new messages.

This guide will help developers embed Pyrus chat into their app.

Get an App ID

First, connect your app to the Pyrus form where support team processes client requests. You need an administrator account in Pyrus with access to the form settings in order to get started. If you aren’t a form administrator, ask a colleague who has this access.

1. Go to the service ticket form configuration page and find Integrations. Click Set Up next to Mobile App Chat.

2. Copy App ID from the Credentials section.

Prepare the project

Add to Pods file::

pod 'PyrusServiceDesk', :git => ‘https://github.com/simplygoodsoftware/pyrusservicedesk.git’, :tag => ‘1.2.0’
Or download the framework and open Targets » General and move the framework to the Embedded Binaries.

To let users attach files to messages, you must configure access to the camera and gallery. In the file Info.plist, add

“Privacy - Camera Usage Description”, “Privacy - Photo Library Usage Description”, “Privacy - Microphone Usage Description”.

Initialize chat

When starting the app, invoke the init() method of the PyrusServiceDesk class. The parameters of the init() method:

  • appID, an object of the String class. It’s your application ID from the settings of the connected form in Pyrus. If you aren’t an administrator of the form, ask a colleague who has administrator rights to copy the AppID as described in the Get an App ID section.

Objective-C

Initialize the chat function in the AppDelegate.m file.

(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
PyrusServiceDesk *psd = [[PyrusServiceDesk alloc] init:@"your_app_id"];
return YES;
}

Swift

Initialize the chat function in the AppDelegate.swift file.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        PyrusServiceDesk.init("your_app_id")
        return true
    }

Launch the user interface

To launch the user interface, invoke the start() method of the PyrusServiceDesk class. The start() method parameters:

  • viewController, the object of the UIViewController class.

Objective-c:

[PyrusServiceDesk startOn:self];

Swift:

PyrusServiceDesk.start(on: self)

To customize the chat appearance, pass the configuration parameter. Parameters of the start() method:

  • viewController, an object of the UIViewController class. It’s used for launching chat UI.
  • configuration, an object of the ServiceDeskConfiguration class. It’s used for configuring chat UI.

Objective-c:

[PyrusServiceDesk startOn:self configuration:configuration];

Swift:

PyrusServiceDesk.start(on: self, configuration:configuration)

Customize the chat

The start() method is used for starting the chat interface. It contains the configuration parameter, an object of the ServiceDeskConfiguration class. Parameters of the ServiceDeskConfiguration class:

  • userName, an object of the String class — the username that a support specialist will see in a Pyrus ticket. If a user has logged into the app, you can pass his or her name, email, and other info to this method. It will help your support specialist understand who he or she is talking to and resolve the ticket more quickly.
  • chatTitle, an object of the String class — the title of the chat window.
  • welcomeMessage, an object of the String class — a welcome message that the user sees when opening a chat.
  • themeColor, an object of the UIColor class — the color of the main elements of the chat interface.
  • avatarForSupport, an object of the UIImage class — a support manager’s avatar.

Objective-C:

    	ServiceDeskConfiguration *configure = [[ServiceDeskConfiguration alloc] init];
    	configure.userName = @"John Smith";
   	configure.chatTitle = @"Support CompanyName";
    	configure.welcomeMessage = @"Hello! How can I help you?";
    	configure.themeColor = [UIColor redColor];
    	configure.avatarForSupport = [UIImage imageNamed:@"logo.png"];

Swift:

    	let configure : ServiceDeskConfiguration = ServiceDeskConfiguration.init()
	configure.userName = "John Smith"
   	configure.chatTitle = "Support CompanyName"
	configure.welcomeMessage = "Hello! How can I help you?"
   	configure.themeColor = .red
   	configure.avatarForSupport = UIImage.init(named: "logo.png")

Notifications about new messages

You can use push notifications to inform users about new messages in the chat. This is the alternative option. It’s easier to implement, but notifications will be delayed and you won’t see the content of a new comment. Enable push notifications

To get notifications about new messages from a support specialist, implement the NewReplySubscriber interface and pass the implementation to the subscribeToReplies() of the PyrusServiceDesk class.

@objc public protocol NewReplySubscriber{
    @objc func onNewReply()
}

Objective-C:

In the ViewController.h file

@interface ViewController : UIViewController

In the ViewController.m file

-(void)viewWillAppear:(BOOL)animated{
...
    [PyrusServiceDesk subscribeToReplies:self];
}
-(void)viewDidDisappear:(BOOL)animated{
...
    [PyrusServiceDesk unsubscribeFromReplies:self];
}
-(void)onNewReply {
    NSLog(@"New unread messages");
}

Swift:

class ViewController: UIViewController, NewReplySubscriber{
 override func viewWillAppear(_ animated: Bool) {
...
        PyrusServiceDesk.subscribeToReplies(self)
    }
    override func viewWillDisappear(_ animated: Bool) {
	...
        PyrusServiceDesk.unsubscribeFromReplies(self)
    }
    func onNewReply() {
        print("New unread messages.")
    }
 }

Enabling push notifications

You can use push notifications to inform the user about new messages in the chat. Here’s how it works:

Your app communicates with APNs when launching to receive its device token, which you then forward to your provider server. Your server includes that token with every notifications it sends.

To subscribe a user to notifications about new messages, register a push token.

Objective-C:

[PyrusServiceDesk setPushToken:@”your_token” completion:^(NSError* error){
        if(error)
        {
            //error
            NSLog(@"error = %@",error.localizedDescription);
        }
        else{
            //success
        }
    }];

Swift:

PyrusServiceDesk.setPushToken(“your_token”, completion: {
            (error) in
            if error != nil{
                //error
                print(error!.localizedDescription)
			...
            }
            else{
                //success
...
            }
        })

On the application server side, you should implement a webhook that will receive notifications about new messages in the in-app chat. Add the webhook URL in the form settings in Pyrus.

When there is a new message from the support team, a POST request will be sent to the webhook URL. It contains:

ticket_id — the number of the task to which the comment is added.

token — user's identificator including:

  • user_id — user ID, which is passed with each request
  • app_id — mobile application / web chat identificator
  • device_id — device identificator
  • type — device type: “iOS”

comment — information about the new comment:

  • comment_id — number of the new comment
  • body — comment text
  • is_inbound — always false, shows that the comment is from the support team

author — information about the author of the comment:

  • name — author's name
  • avatar_id — author's avatar identifier
  • avatar_color — the color of the author's avatar. Used if avatar_id is not specified

created_at — date and time the comment was created.

attachments — description of the attached files:

  • id — file identificator
  • name — file name
  • size — file size in bytes

Setting up the chat menu

For an enhanced support experience your users can send files without having to leave the chat flow. By default, users can attach photos taken with the device camera or select images from the gallery. To add other file types like configuration files, use the registerFileChooser() method of the PyrusServeDesk class.

PyrusServiceDesk.registerFileChooser (chooser: (FileChooser 
& UIViewController)?)

Chooser is an implementation of the FileChooser interface. To stop using the configured FileChooser, pass null to the method.

FileChooser has a label parameter where a string with the name of the corresponding menu option is stored (for example, Attach file) and a chooserDelegate parameter which is a protocol of the FileChooserDelegate type.

Objective-C:

In the CustomViewController.h:

@import PyrusServiceDesk;
@interface CustomViewController : UIViewController 
@end

In the CustomViewController.m:

 
#import "CustomViewController.h"
@interface CustomViewController ()
@end
@implementation CustomViewController
@synthesize chooserDelegate;
@synthesize label; //The label must be specified when initializing the CustomViewController
...
@end

Swift:

class CustomViewController: UIViewController, FileChooser{
    var chooserDelegate: FileChooserDelegate?
    var label: String = "Send logs"
    ...
}

CustomViewController can pass (chooserDelegate) to its delegate:

1. Cancellation message. Closes CustomViewController.

Objective-C:

[self.chooserDelegate didEndWithCancel];

Swift:

self.chooserDelegate?.didEndWithCancel()

2. Success message. It must contain the data and the path to it. Closes CustomViewController and sends data as an attachment to the chat.

Objective-C:

[self.chooserDelegate didEndWithSuccess:data url:url];

Swift:

self.chooserDelegate?.didEndWithSuccess(data, url: url)

Types and methods description

PyrusServiceDesk

@objc public class PyrusServiceDesk: NSObject

A class for creating a chat in your app.

init

@objc public init(_ appId: String?)

Parameters

appID For every query. If appID isn’t set, PyrusServiceDesk Controller won’t be created.

registerFileChooser

@objc public static func registerFileChooser(_ chooser: (FileChooser & UIViewController)?)

Parameters

chooser UIViewController with a FileChooser extension. This starts the interface for selecting files. Send null to disable it.

setPushToken

@objc public static func setPushToken(_ token:String?, completion: @escaping(Error?) -> Void)

Sends device ID to the server.

Parameters

completion Error. Not nil, if success. To find out what went wrong, check error.localizedDescription.
token A string with a device identifier.

start

@objc public static func start(on viewController:UIViewController)

Shows the chat.

Parameters

viewController Presents a chat.

start

 @objc public static func start(on viewController:UIViewController, configuration:ServiceDeskConfiguration?)

Shows the chat.

Parameters

configuration The ServiceDeskConfiguration object or nil. ServiceDeskConfiguration is an object that creates the user interface, including main color, welcome message, support avatar, and chat window title. If nil, the default configuration will be used.
viewController Presents the chat.

subscribeToReplies

@objc public static func subscribeToReplies(_ subscriber: NewReplySubscriber?)

This subscribes [subscriber] to notifications about new messages in the chat.

unsubscribeFromReplies

@objc public static func unsubscribeFromReplies(_ subscriber: NewReplySubscriber?)

This unsubscribes [subscriber] from notifications about new messages.

ServiceDeskConfiguration

@objc public class ServiceDeskConfiguration: NSObject

A class for setting up chat UI.

avatarForSupport

@objc public var avatarForSupport : UIImage?

A support specialist’s avatar. This appears when there is no avatar in a support specialist’s Pyrus profile.

chatTitle

@objc public var chatTitle : String?

Contains the text for a chat title. By default, it’s “Support.”

themeColor

@objc public var themeColor : UIColor?

Chat window color. By default, the app tintColor is used. If it isn’t set, then (red: 0, green: 0.4784313725, blue: 1, alpha: 1) is used.

userName

@objc public var userName : String?

The username (client’s name) that a support specialist sees in ticket in Pyrus. This uses “Guest” by default. If a user is logged into the app, you can pass that user’s name, email address, and other info to this method.

welcomeMessage

@objc public var welcomeMessage : String?

The first message that the user sees in the chat. If not specified, the chat will be displayed without a welcome message.

NewReplySubscriber

@objc public protocol NewReplySubscriber

Protocol for sending notifications about new messages.

onNewReply

@objc func onNewReply()

A new message is sent.

FileChooser

@objc public protocol FileChooser

File transfer extension.

chooserDelegate

@objc var chooserDelegate : FileChooserDelegate? { get set }

Sends status messages when the process is complete.

label

@objc var label : String { get set}

The name of the menu option.

FileChooserDelegate

@objc public protocol FileChooserDelegate

Sends status messages when the process is complete.

didEndWithCancel

@objc func didEndWithCancel()

Sends the “Canceled” status.

didEndWithSuccess

@objc func didEndWithSuccess(_ data : Data?, url : URL?)

Sends the “Success” status.

Parameters

data The attachment that will be sent to the chat. If empty or nil, an error message will be displayed.
url Path to the file.

Was this article helpful?

Yes, thanks! No, I have a question