Bots Class Reference

Inherits from NSObject
Declared in Bots.h

+ initWithSettings:completionHandler:

Initialize the Bots SDK with the provided settings.

+ (void)initWithSettings:(OMCSettings *)settings completionHandler:(nullable void ( ^ ) ( NSError *_Nullable error , NSDictionary *_Nullable userInfo ))handler

Parameters

settings

The settings to use.
handler

An optional block to evaluate the result of the operation

Discussion

This may only be called once (preferably, in application:didFinishLaunchingWithOptions:).

Use +settings to retrieve and modify the given settings object.

See Also

Declared In

Bots.h

+ settings

Accessor method for the sdk settings.

+ (nullable OMCSettings *)settings

Return Value

Settings object passed in +initWithSettings:completionHandler:, or nil if +initWithSettings:completionHandler: hasn’t been called yet.

Discussion

Use this object to update settings at run time.

Note: Some settings may only be configured at init time. See the OMCSettings class reference for more information.

See Also

Declared In

Bots.h

+ show

Presents the Bots conversation screen.

+ (void)show

Discussion

Uses the top-most view controller of the UIApplicationDelegate as the presenting view controller.

+initWithSettings:completionHandler: must have been called prior to calling this method.

Declared In

Bots.h

+ close

Dismisses the Bots conversation, if shown.

+ (void)close

Discussion

Note: If a view controller was created and presented using newConversationViewController, calling this method will have no effect.

+initWithSettings:completionHandler: must have been called prior to calling this method.

Declared In

Bots.h

+ destroy

Destroys the Bots SDK

+ (void)destroy

Discussion

Bots is automatically terminated when the application exits. This method does not need to be called manually

Declared In

Bots.h

+ showConversationFromViewController:

Presents the Bots conversation screen, using the given view controller as presenting view controller.

+ (void)showConversationFromViewController:(UIViewController *)viewController

Discussion

In most cases, it is better to use +show. If you need more fine-grained control over which view controller is used as presenting view controller, use this method instead.

+initWithSettings:completionHandler: must have been called prior to calling this method.

Declared In

Bots.h

+ newConversationViewController

Creates and returns a Bots conversation view controller.

+ (nullable UIViewController *)newConversationViewController

Return Value

A new instance of the Bots conversation view controller class. Returns nil if +initWithSettings:completionHandler: hasn’t been called

Discussion

You may use this view controller to embed the conversation in a navigation controller, to change the modal presentation style, or display it in any way you choose.

A view controller created in this way is tied to the current user’s conversation at creation time. If the current user changes (i.e. by calling +login:jwt:completionHandler: or +logoutWithCompletionHandler:), the view controller is invalidated and must be recreated for the new user.

Note: It is the responsibility of the caller to show, hide, and maintain a reference to this view controller. Calling close will not dismiss a view controller created in this way.

Declared In

Bots.h

+ setUserFirstName:lastName:

Sets the current user’s first and last name to be used as a display name when sending messages.

+ (void)setUserFirstName:(nullable NSString *)firstName lastName:(nullable NSString *)lastName

Parameters

firstName

The first name of the user
lastName

The last name of the user

Discussion

This is a shortcut for -setFirstName and -setLastName on [OMCUser currentUser]

See Also

Declared In

Bots.h

+ conversation

Accessor method for the current conversation.

+ (nullable OMCConversation *)conversation

Return Value

Current conversation, or nil if +initWithSettings:completionHandler: hasn’t been called yet.

See Also

Declared In

Bots.h

+ login:jwt:completionHandler:

Logs in a new Bots user.

+ (void)login:(NSString *)userId jwt:(NSString *)jwt completionHandler:(nullable void ( ^ ) ( NSError *_Nullable error , NSDictionary *_Nullable userInfo ))handler

Parameters

userId

The distinct id of the user to login. Must not be nil.
jwt

jwt used to prove the origin of the login request. Must not be nil.

Discussion

You can either use this method to transition from logged out state to logged in, or to switch the currently logged in user to a different one.

User login state is persisted across app launches. You must call +logoutWithCompletionHandler: to reset to anonymous mode.

+initWithSettings:completionHandler: must have been called prior to calling this method.

You may not call login while the conversation screen is shown. Doing so will result in a no-op.

Declared In

Bots.h

+ logoutWithCompletionHandler:

Logs out the current user.

+ (void)logoutWithCompletionHandler:(nullable void ( ^ ) ( NSError *_Nullable error , NSDictionary *_Nullable userInfo ))completionHandler

Discussion

Calling this method while already in anonymous state has no effect.

You may not call logout while the conversation screen is shown. Doing so will result in a no-op.

Declared In

Bots.h

+ startConversationWithCompletionHandler:

Force-start a conversation for the current user

+ (void)startConversationWithCompletionHandler:(nullable void ( ^ ) ( NSError *_Nullable error , NSDictionary *_Nullable userInfo ))completionHandler

Discussion

Creates a user and conversation on the server, allowing the business to reach out proactively to the user via the public API.

It is strongly recommended to only call this method in the case where a message is likely to be sent.

This method is called automatically when starting a conversation via the -sendMessage: or -sendImage:withProgress:completion: methods, or when a user sends a message via the conversation view controller.

If a conversation already exists for the current user, this call is a no-op.

Declared In

Bots.h

+ setConversationInputDisplayed:

Toggles whether the input bar is displayed on the conversation view.

+ (void)setConversationInputDisplayed:(BOOL)displayed

Discussion

For some use cases, it can be useful to remove the ability for the user to craft their own messages. For example, if your conversation flow relies solely on postback buttons or quick replies, you may not want to allow the user to send anything other than the presented options.

Passing NO to this method will hide the input bar entirely, including the media button and the text area, thus preventing the user from sending messages themselves.

This method may be called at any time, even when the conversation view is currently displayed.

State is persisted across view controller launches.

Declared In

Bots.h

+ setPushToken:

Set the push notification token for this device.

+ (void)setPushToken:(NSData *)token

Discussion

This method is called automatically if OMCSettings.enableAppDelegateSwizzling is set to YES.

See Also

Declared In

Bots.h

+ handlePushNotification:

Handle an incoming push notification.

+ (void)handlePushNotification:(NSDictionary *)userInfo

Discussion

Call this method in your -application:didReceiveRemoteNotification: or -application:didReceiveRemoteNotification:fetchCompletionHandler: callback, passing the userInfo dictionary.

If the push notification did not originate from Bots, this is a no-op.

This method is called automatically if OMCSettings.enableAppDelegateSwizzling is set to YES.

See Also

Declared In

Bots.h

+ userNotificationCenterDelegate

An object conforming to UNUserNotificationCenterDelegate protocol, used to handle notifications on iOS 10 and above.

+ (nullable id<UNUserNotificationCenterDelegate>)userNotificationCenterDelegate

Return Value

An object conforming to UNUserNotificationCenterDelegate protocol, or nil if +initWithSettings:completionHandler: hasn’t been called yet.

Discussion

Implements both methods of UNUserNotificationCenterDelegate.

By default this object will automatically be set as the UNUserNotificationCenter delegate at init time. Bots will maintain a reference to your app’s existing delegate (if applicable), and automatically forward any calls for notifications that did not originate from Bots.

To disable automatic overriding, you must set OMCSettings.enableUserNotificationCenterDelegateOverride to NO before calling +initWithSettings:completionHandler:. If you choose to do so, you must manually forward any relevant calls from your own delegate object. To check the origin of a notification, see the documentation for OMCPushNotificationIdentifier. For example:

-(void)userNotificationCenter:(UNUserNotificationCenter )center willPresentNotification:(UNNotification )notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler { if(notification.request.content.userInfo[OMCPushNotificationIdentifier] != nil){ [[Bots userNotificationCenterDelegate] userNotificationCenter:center willPresentNotification:notification withCompletionHandler:completionHandler]; return; } }

-(void)userNotificationCenter:(UNUserNotificationCenter )center didReceiveNotificationResponse:(UNNotificationResponse )response withCompletionHandler:(void (^)())completionHandler { if(response.notification.request.content.userInfo[OMCPushNotificationIdentifier] != nil){ [[Bots userNotificationCenterDelegate] userNotificationCenter:center didReceiveNotificationResponse:response withCompletionHandler:completionHandler]; return; } }

See Also

Declared In

Bots.h

+ handleUserNotificationActionWithIdentifier:withResponseInfo:completionHandler:

Handle the user input from a reply type notification action.

+ (void)handleUserNotificationActionWithIdentifier:(NSString *)identifier withResponseInfo:(NSDictionary *)responseInfo completionHandler:(void ( ^ ) ( void ))completionHandler

Discussion

Call this method in your -application:handleActionWithIdentifier:forRemoteNotification:withResponseInfo:completionHandler:, passing the action identifier, responseInfo dictionary, and completionHandler callback.

This method will post a message on behalf of the user, with the contents of their inline reply. When the message upload completes (either in success or failure), the completion handler will be called.

If the action identifier does not match OMCUserNotificationReplyActionIdentifier, the completion handler will be called immediately and the notification will be ignored.

This method is called automatically if OMCSettings.enableAppDelegateSwizzling is set to YES.

See Also

Declared In

Bots.h

+ userNotificationCategories

A set of categories used for handling and displaying Bots user notification actions.

+ (NSSet *)userNotificationCategories

Discussion

On iOS 8, returns an empty set. On iOS 9, returns a set of UIUserNotificationCategory objects, to be used with UIUserNotificationSettings +settingsForTypes:categories: On iOS 10, returns a set of UNNotificationCategory objects, to be used with UNUserNotificationCenter -setNotificationCategories:

Categories are registered automatically if OMCSettings.requestPushPermissionOnFirstMessage is set to YES. If automatic registration is disabled, you must make sure to include the Bots categories in your calls to the above mentioned methods.

See Also

Declared In

Bots.h