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.

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.

Add to Pods file::

pod 'PyrusServiceDesk', :git => ‘https://github.com/simplygoodsoftware/pyrusservicedesk.git’, :tag => ‘1.2.0’

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”.

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
    }

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)

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")

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.")
    }
 }

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

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)

@objc public class PyrusServiceDesk: NSObject

A class for creating a chat in your app.

@objc public init(_ appId: String?)

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

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

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

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

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

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

@objc public class ServiceDeskConfiguration: NSObject

A class for setting up chat UI.

@objc public var avatarForSupport : UIImage?

@objc public var chatTitle : String?

@objc public var themeColor : UIColor?

@objc public var userName : String?

@objc public var welcomeMessage : String?

@objc public protocol NewReplySubscriber

Protocol for sending notifications about new messages.

@objc func onNewReply()

@objc public protocol FileChooser

File transfer extension.

@objc var chooserDelegate : FileChooserDelegate? { get set }

@objc var label : String { get set}

@objc public protocol FileChooserDelegate

Sends status messages when the process is complete.

@objc func didEndWithCancel()

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