Inbox SDK for iOS
SDK integration
To add SDK into your project add the following pod into your pod file
pod 'YellowInbox'
Initialization
The SDK can be initialised by passing API_KEY, USER_ID and BOT_ID to the initialize method.
@objc public class func initialize(with
botId: String,
apiKey: String,
userId: String,
completion: ((_ isSuccess: Bool) -> Void)? = nil
)
apiKey
apiKey will be provided by yellow.ai, It is clients responsibility to keep the API_KEY safe. This is a mandatory parameter.
userId
userId will be the id registered/provided to yellow.ai by the client to authenticate their employee. This is a mandatory parameter.
botId
botId will be provided by yellow.ai. This is a mandatory parameter.
Example
import YellowInbox
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
YellowInbox.initialize(with: <#"bot id"#>,
apiKey: <#"API key"#>,
userId: <#"USER_ID"#>) { success in
if success { print("SDK initialized successfully") }
else { print("Error while initializing the SDK") }
}
}
}
Overview
Overview view is provided as a viewcontroller.
Overview Viewcontroller
If clients want to use the Overview viewcontroller in their application, they can call the following method to get the viewcontroller object.
let viewController = YellowInbox.makeOverviewViewController()
client can push, present and embed this viewcontroller as they do for any other viewcontrollers.
My Chat
Chats view is provided as a viewcontroller.
My Chat Viewcontroller
If clients want to use the MyChat viewcontroller in their application, they can call the following method to get the viewcontroller object.
let viewController = YellowInbox.makeMyChatsViewController()
client can push, present and embed this viewcontroller as they do for any other viewcontrollers.
Notifications
Background Notification
To receive firebase notification clients need to send Firebase device token to SDK. To do so the following method can be used.
YellowInbox.setNotificationToken(<#"device token"#>)
Make sure to call this function when the device token is changed.
Clients will receive firebase notification if the app is not running in foreground or in background, or if Ticket Create, User Message or Agent is added as collaborator actions happening on a ticket.
Clients need not to listen to these notifications when the app is running, SDK will take care of such events.
Clients need to call following method if they want to take user to appropriate view once user clicks on notification delivered in system tray and sent by yellow.ai
let viewController = YellowInbox.makeConversationView(ticketId: <#"ticket id"#>)
client can push and present this viewcontroller as they do for any other viewcontrollers.
Local Notification
Clients will receive local notification that will be triggered by the SDK based on the events received over XMPP. In case a client wants to override the normal behaviour of notification or want to update title/body, they can do so by they can do so by delegate methods.
Clients need to do the following step.
YellowInbox.delegate = self
Following are the delegates methods:
@objc func willShowCreateTicketLocalNotification(
title: String?,
body: String?) -> YellowLocalNotification?
@objc func willShowUpdateTicketLocalNotification(
title: String?,
body: String?) -> YellowLocalNotification?
Example
class ViewController: UIViewController, YellowInboxDelegate {
func willShowCreateTicketLocalNotification(
title: String?,
body: String?) -> YellowLocalNotification? {
return YellowLocalNotification(title: <#"title"#>, body: <#"body"#>)
}
func willShowUpdateTicketLocalNotification(
title: String?,
body: String?) -> YellowLocalNotification? {
return YellowLocalNotification(title: <#"title"#>, body: <#"body"#>)
}
}
Clients will get callbacks on these methods for creating and updating tickets notification. Clients can return a YellowLocalNotification instance with a modified title and body. if client dont wont to update the content the can return nil.
Video call Notification
If a client is receiving a video call notification while the app is in background, Simply tapping on notification and check for the notification type in didReceive response function.
In case the app is running and in the foreground, client need to check for notification type into will present method.
- Client need to set the Firebase token in case device token changes by calling
YellowInbox.setNotificationToken("DEVICE_TOKEN")
- In didReceive response function client need to check if notification type is video call. client can open received url on webview or any default webapp.
let notificationType: YellowInbox.Notification? = YellowInbox.notificationType(response.notification)
switch notificationType {
case let .videoCall(url, ticketId):
// Use this url to open in web browser
default: break;
}
Example
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate, MessagingDelegate {
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
let notificationType: YellowInbox.Notification? = YellowInbox.notificationType(notification)
if case .videoCall(let url, let ticketId) = notificationType {
SceneDelegate.shared?.showVideoCallAlert(for: url, ticketId: ticketId)
}
completionHandler([.alert, .badge, .sound])
}
func userNotificationCenter(_ center: UNUserNotificationCenter didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
let notificationType: YellowInbox.Notification? = YellowInbox.notificationType(response.notification)
if case .videoCall(let url, let ticketId) = notificationType {
SceneDelegate.shared?.showVideoCallAlert(for: url, ticketId: ticketId)
}
completionHandler()
}
}
A call declined from notification can be joined from the Chat view by tapping on the call icon
Agent Status
Get All Agent Statuses
To get all possible statuses of logged in User against the bot id (Used for initialising the SDK), client can call the following method. This can be used to show all the possible status when Agent want to change the status.
@objc public class func getAllAgentStatus(
onSuccess: @escaping ([YellowAgentStatus]?) -> Void,
onFailure: @escaping (Error) -> Void)
Get Agent Status
To get availability status of logged in User against the bot id (Used for initialising the SDK), client can call the following method
@objc public class func getAgentStatus(
onSuccess: @escaping (YellowAgentStatus?) -> Void,
onFailure: @escaping (Error) -> Void)
Example
YellowInbox.getAgentStatus(
onSuccess: { agentStatus in let status = agentStatus },
onFailure: { error in print(error) }
)
Set Agent Status
To set the status of logged in user against the bot id (Used for initialising the SDK), the client can call the following method and observe on it. Client need to pass the YellowAgentStatus object received from making YellowInbox.getAllAgentStatus() call
@objc public class func setAgentStatus(
_ status: YellowAgentStatus,
onSuccess: @escaping (YellowAgentStatus) -> Void,
onFailure: @escaping (Error) -> Void)
Example
YellowInbox.setAgentStatus(
status,
onSuccess: { _ in print("Status changed") },
onFailure: { error in print(error) }
)
Logout
By calling logout, all the services and notifications will be terminated. You can call this function when user logs out of the app
@objc public class func logout(completion: @escaping ((Bool, Error?) -> Void))
Example
YellowInbox.logout { isSuccess, error in
if isSuccess { print("Logout successfully") }
else if let error = error { print(error) }
}
Informational
Versions
YellowInbox SDK requires iOS 13.0 and above
Permissions
YellowInbox SDK usage following permissions.
<key>NSPhotoLibraryUsageDescription</key>
<string>Your description</string>
<key>NSCameraUsageDescription</key>
<string>Your description</string>
Clients need to add this permissions to their app’s Info.plist.