SKYChatExtension

@interface SKYChatExtension : NSObject

SKYChatExtension is a simple object that expose easy to use helper methods to develop a chat app.

Most of the functions provide by the chat plugin is available through this extension object.

The extension requires a SKYContainer to function. For most app developer, you should obtain a SKYChatExtension through the -[SKYContainer chatExtension] category method.

  • Gets or sets whether messages fetched from server are automatically marked as delivered.

    When this is true, the chat extension will automatically send delivery receipt to the server when a message is fetched from the server.

    This is enabled by default.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic)
        _Bool automaticallyMarkMessagesAsDelivered;

    Swift

    var automaticallyMarkMessagesAsDelivered: Bool { get set }
  • Gets or sets user channel message handler.

    The user channel message handler is a low-level interface for getting messages from the user channel. For most apps, get messages from user channel with notifications posted by chat extension.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) void (^)
        (NSDictionary<NSString *, id> *_Nonnull) userChannelMessageHandler;

    Swift

    var userChannelMessageHandler: (([String : Any]) -> Void)? { get set }
  • Creates a conversation with the selected participants.

    All participants will also become the admins of the created conversation. The conversation will not be distinct by participants by default.

    If participants list do not include the current user, the current user will be added to the list as well. The same apply for admins list.

    Declaration

    Objective-C

    - (void)
    createConversationWithParticipantIDs:
        (NSArray<NSString *> *_Nonnull)participantIDs
                                   title:(NSString *_Nullable)title
                                metadata:(NSDictionary<NSString *, id> *_Nullable)
                                             metadata
                              completion:(SKYChatConversationCompletion _Nullable)
                                             completion;

    Swift

    func createConversation(participantIDs: [String], title: String?, metadata: [String : Any]?, completion: SKYChatConversationCompletion? = nil)

    Parameters

    participantIDs

    an array of all participants in the conversation

    title

    title of the conversation

    metadata

    application metadata for the conversation

    completion

    completion block

  • Creates a conversation with the selected participants.

    If participants list do not include the current user, the current user will be added to the list as well. The same apply for admins list. If the admins list is not specified, the admins list will be the same as the participants list.

    If distinctByParticipants is set to YES, the chat extension will attempt to find an existing conversation with the same list of participants before creating a new one.

    Declaration

    Objective-C

    - (void)
    createConversationWithParticipantIDs:
        (NSArray<NSString *> *_Nonnull)participantIDs
                                   title:(NSString *_Nullable)title
                                metadata:(NSDictionary<NSString *, id> *_Nullable)
                                             metadata
                                adminIDs:(NSArray<NSString *> *_Nullable)adminIDs
                  distinctByParticipants:(BOOL)distinctByParticipants
                              completion:(SKYChatConversationCompletion _Nullable)
                                             completion;

    Swift

    func createConversation(participantIDs: [String], title: String?, metadata: [String : Any]?, adminIDs: [String]?, distinctByParticipants: Bool, completion: SKYChatConversationCompletion? = nil)

    Parameters

    participantIDs

    an array of all participants in the conversation

    title

    title of the conversation

    metadata

    application metadata for the conversation

    adminIDs

    an array of all participants that can administrate the conversation

    completion

    completion block

  • Creates a direct conversation with a specific user.

    The current user and the specified user will be in the participants list and admins list.

    The new conversation will have distinctByParticipants set to YES. This allows the application to reuse an exisitng direct conversation.

    Declaration

    Objective-C

    - (void)
    createDirectConversationWithUserID:(NSString *_Nonnull)userID
                                 title:(NSString *_Nullable)title
                              metadata:
                                  (NSDictionary<NSString *, id> *_Nullable)metadata
                            completion:
                                (SKYChatConversationCompletion _Nullable)completion;

    Swift

    func createDirectConversation(userID: String, title: String?, metadata: [String : Any]?, completion: SKYChatConversationCompletion? = nil)

    Parameters

    userID

    the ID of the other user in the direct conversation

    title

    title of the conversation

    metadata

    application metadata for the conversation

    completion

    completion block

  • Saves a conversation.

    This method can be used to save a new conversation or update an existing conversation. This method does not reuse an existing conversation even if distinctByParticipants is set to YES.

    To create or reuse a conversation, call createConversation… instead.

    Declaration

    Objective-C

    - (void)saveConversation:(SKYConversation *_Nonnull)conversation
                  completion:(SKYChatConversationCompletion _Nullable)completion;

    Swift

    func saveConversation(_ conversation: SKYConversation, completion: SKYChatConversationCompletion? = nil)

    Parameters

    conversation

    the conversation to be saved

    completion

    completion block

  • Deletes a conversation.

    This method can be used to delete an existing conversation.

    Declaration

    Objective-C

    - (void)deleteConversation:(SKYConversation *_Nonnull)conversation
                    completion:
                        (SKYChatDeleteConversationCompletion _Nullable)completion;

    Swift

    func deleteConversation(_ conversation: SKYConversation, completion: SKYChatDeleteConversationCompletion? = nil)

    Parameters

    conversation

    the conversation to be saved

    completion

    completion block

  • Fetches conversations.

    Declaration

    Objective-C

    - (void)fetchConversationsWithCompletion:
        (SKYChatFetchConversationListCompletion _Nullable)completion;

    Swift

    func fetchConversations(completion: SKYChatFetchConversationListCompletion? = nil)

    Parameters

    completion

    completion block

  • Fetches conversations with optional last message in conversation.

    Declaration

    Objective-C

    - (void)
    fetchConversationsWithFetchLastMessage:(BOOL)fetchLastMessage
                                completion:
                                    (SKYChatFetchConversationListCompletion _Nullable)
                                        completion;

    Swift

    func fetchConversations(fetchLastMessage: Bool, completion: SKYChatFetchConversationListCompletion? = nil)

    Parameters

    fetchLastMessage

    whether to fetch the last message

    page

    page index of conversations to be fetched

    pageSize

    maximum number of conversations to be fetched

    completion

    completion block

  • Fetches a conversation by conversation ID.

    Declaration

    Objective-C

    - (void)fetchConversationWithConversationID:(NSString *_Nonnull)conversationID
                               fetchLastMessage:(BOOL)fetchLastMessage
                                     completion:
                                         (SKYChatConversationCompletion _Nullable)
                                             completion;

    Swift

    func fetchConversation(conversationID: String, fetchLastMessage: Bool, completion: SKYChatConversationCompletion? = nil)

    Parameters

    conversationID

    ID of conversation

    fetchLastMessage

    whether to fetch the last message

    completion

    completion block

  • Adds participants to a conversation.

    The specified user IDs are added to the conversation record as participants. The modified conversation will be saved to the server.

    Declaration

    Objective-C

    - (void)addParticipantsWithUserIDs:(NSArray<NSString *> *_Nonnull)userIDs
                        toConversation:(SKYConversation *_Nonnull)conversation
                            completion:
                                (SKYChatConversationCompletion _Nullable)completion;

    Swift

    func addParticipants(userIDs: [String], to conversation: SKYConversation, completion: SKYChatConversationCompletion? = nil)

    Parameters

    userIDs

    array of participant user ID

    conversation

    conversation record

    completion

    completion block

  • Removes participants from a conversation.

    The specified user IDs are removed from the conversation record as participants. The modified conversation will be saved to the server.

    Declaration

    Objective-C

    - (void)removeParticipantsWithUserIDs:(NSArray<NSString *> *_Nonnull)userIDs
                         fromConversation:(SKYConversation *_Nonnull)conversation
                               completion:(SKYChatConversationCompletion _Nullable)
                                              completion;

    Swift

    func removeParticipants(userIDs: [String], from conversation: SKYConversation, completion: SKYChatConversationCompletion? = nil)

    Parameters

    userIDs

    array of participant user ID

    conversation

    conversation record

    completion

    completion block

  • Adds admins to a conversation.

    The specified user IDs are added to the conversation record as admins. The modified conversation will be saved to the server.

    Declaration

    Objective-C

    - (void)addAdminsWithUserIDs:(NSArray<NSString *> *_Nonnull)userIDs
                  toConversation:(SKYConversation *_Nonnull)conversation
                      completion:
                          (SKYChatConversationCompletion _Nullable)completion;

    Swift

    func addAdmins(userIDs: [String], to conversation: SKYConversation, completion: SKYChatConversationCompletion? = nil)

    Parameters

    userIDs

    array of admin user ID

    conversation

    conversation record

    completion

    completion block

  • Removes admins to a conversation.

    The specified user IDs are removed from the conversation record as admins. The modified conversation will be saved to the server.

    Declaration

    Objective-C

    - (void)removeAdminsWithUserIDs:(NSArray<NSString *> *_Nonnull)userIDs
                   fromConversation:(SKYConversation *_Nonnull)conversation
                         completion:
                             (SKYChatConversationCompletion _Nullable)completion;

    Swift

    func removeAdmins(userIDs: [String], from conversation: SKYConversation, completion: SKYChatConversationCompletion? = nil)

    Parameters

    userIDs

    array of admin user ID

    conversation

    conversation record

    completion

    completion block

  • Remove the current user from the specified conversation.

    This method should be called when the current user wants to leave a conversation. Since modifying the participant list is only allowed if the user is an admin, calling -removeParticipantsWithUserIDs:fromConversation:completion: does not work.

    Declaration

    Objective-C

    - (void)leaveConversation:(SKYConversation *_Nonnull)conversation
                   completion:(void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func leave(_ conversation: SKYConversation, completion: ((Error?) -> Void)? = nil)
  • Remove the current user from the specified conversation by ID.

    This method should be called when the current user wants to leave a conversation. Since modifying the participant list is only allowed if the user is an admin, calling -removeParticipantsWithUserIDs:fromConversation:completion: does not work.

    Declaration

    Objective-C

    - (void)leaveConversationWithConversationID:(NSString *_Nonnull)conversationID
                                     completion:(void (^_Nullable)(
                                                    NSError *_Nullable))completion;

    Swift

    func leave(conversationID: String, completion: ((Error?) -> Void)? = nil)
  • Creates a message in the specified conversation.

    Declaration

    Objective-C

    - (void)
    createMessageWithConversation:(SKYConversation *_Nonnull)conversation
                             body:(NSString *_Nullable)body
                         metadata:(NSDictionary<NSString *, id> *_Nullable)metadata
                       completion:(SKYChatMessageCompletion _Nullable)completion;

    Swift

    func createMessage(conversation: SKYConversation, body: String?, metadata: [String : Any]?, completion: SKYChatMessageCompletion? = nil)

    Parameters

    conversation

    conversation object

    body

    message body

    metadata

    application metadata for the conversation

    completion

    completion block

  • Creates a message in the specified conversation with an attachment.

    Declaration

    Objective-C

    - (void)
    createMessageWithConversation:(SKYConversation *_Nonnull)conversation
                             body:(NSString *_Nullable)body
                       attachment:(id)attachment
                         metadata:(NSDictionary<NSString *, id> *_Nullable)metadata
                       completion:(SKYChatMessageCompletion _Nullable)completion;

    Swift

    func createMessage(conversation: SKYConversation, body: String?, attachment: Any!, metadata: [String : Any]?, completion: SKYChatMessageCompletion? = nil)

    Parameters

    conversation

    conversation object

    body

    message body

    attachment

    SKYAsset object containing the attachment.

    metadata

    application metadata for the conversation

    completion

    completion block

  • Adds a message to a conversation.

    The message is modified with the conversation and saved to the server. If the message contains attachment and the attachment is not uploaded yet, the attachment will be uploaded first and the message is then saved to the server.

    Declaration

    Objective-C

    - (void)addMessage:(SKYMessage *_Nonnull)message
        toConversation:(SKYConversation *_Nonnull)conversation
            completion:(SKYChatMessageCompletion _Nullable)completion;

    Swift

    func addMessage(_ message: SKYMessage, to conversation: SKYConversation, completion: SKYChatMessageCompletion? = nil)

    Parameters

    message

    message to add to a conversation

    conversation

    conversation object

    completion

    completion block

  • Fetch messages in a conversation.

    Declaration

    Objective-C

    - (void)fetchMessagesWithConversation:(SKYConversation *_Nonnull)conversation
                                    limit:(NSInteger)limit
                               beforeTime:(NSDate *_Nullable)beforeTime
                                    order:(NSString *_Nullable)order
                               completion:
                                   (SKYChatFetchMessagesListCompletion _Nullable)
                                       completion;

    Swift

    func fetchMessages(conversation: SKYConversation, limit: Int, beforeTime: Date?, order: String?, completion: SKYChatFetchMessagesListCompletion? = nil)

    Parameters

    conversation

    conversation object

    limit

    the number of messages to fetch

    beforeTime

    only messages before this time is fetched

    order

    order of the messages, either ‘edited_at’ or ‘_created_at’

    completion

    completion block

  • Fetch messages in a conversation by ID.

    Declaration

    Objective-C

    - (void)fetchMessagesWithConversationID:(NSString *_Nonnull)conversationId
                                      limit:(NSInteger)limit
                                 beforeTime:(NSDate *_Nullable)beforeTime
                                      order:(NSString *_Nullable)order
                                 completion:
                                     (SKYChatFetchMessagesListCompletion _Nullable)
                                         completion;

    Swift

    func fetchMessages(conversationID conversationId: String, limit: Int, beforeTime: Date?, order: String?, completion: SKYChatFetchMessagesListCompletion? = nil)

    Parameters

    conversationId

    ID of the conversation

    limit

    the number of messages to fetch

    beforeTime

    only messages before this time is fetched

    order

    order of the messages, either ‘edited_at’ or ‘_created_at’

    completion

    completion block

  • Marks messages as read.

    Marking a messages as read also mark the message as delivered.

    Declaration

    Objective-C

    - (void)markReadMessages:(NSArray<SKYMessage *> *_Nonnull)messages
                  completion:(void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func markReadMessages(_ messages: [SKYMessage], completion: ((Error?) -> Void)? = nil)

    Parameters

    messages

    messages to mark

    completion

    completion block

  • Marks messages as read.

    Marking a messages as read also mark the message as delivered.

    Declaration

    Objective-C

    - (void)markReadMessagesWithID:(NSArray<NSString *> *_Nonnull)messageIDs
                        completion:
                            (void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func markReadMessages(id messageIDs: [String], completion: ((Error?) -> Void)? = nil)

    Parameters

    messageIDs

    ID of messages to mark

    completion

    completion block

  • Marks messages as delivered.

    The SDK marks a message as delivered automatically when the message is fetched from server. You are not required to call this method.

    Declaration

    Objective-C

    - (void)markDeliveredMessages:(NSArray<SKYMessage *> *_Nonnull)messages
                       completion:(void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func markDeliveredMessages(_ messages: [SKYMessage], completion: ((Error?) -> Void)? = nil)

    Parameters

    messages

    messages to delivered

    completion

    completion block

  • Marks messages as delivered.

    The SDK marks a message as delivered automatically when the message is fetched from server. You are not required to call this method.

    Declaration

    Objective-C

    - (void)markDeliveredMessagesWithID:(NSArray<NSString *> *_Nonnull)messageIDs
                             completion:
                                 (void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func markDeliveredMessages(id messageIDs: [String], completion: ((Error?) -> Void)? = nil)

    Parameters

    messageIDs

    ID of messages to delivered

    completion

    completion block

  • Fetch delivery and read receipts of a message.

    Declaration

    Objective-C

    - (void)fetchReceiptsWithMessage:(SKYMessage *_Nonnull)message
                          completion:(void (^_Nullable)(
                                         NSArray<SKYChatReceipt *> *_Nullable,
                                         NSError *_Nullable))completion;

    Swift

    func fetchReceipts(message: SKYMessage, completion: (([SKYChatReceipt]?, Error?) -> Void)? = nil)

    Parameters

    message

    the message object

    completion

    completion block

  • Delete a message in a conversation

    The message is soft-deleted in the message. Conversation unread count, last read message and last message are updated.

    Declaration

    Objective-C

    - (void)deleteMessage:(SKYMessage *_Nonnull)message
           inConversation:(SKYConversation *_Nonnull)conversation
               completion:(SKYChatConversationCompletion _Nullable)completion;

    Swift

    func deleteMessage(_ message: SKYMessage, in conversation: SKYConversation, completion: SKYChatConversationCompletion? = nil)

    Parameters

    message

    the message object

    conversation

    the conversation object

    completion

    completion block

  • Edit a message in a conversation

    The message body is updated.

    Declaration

    Objective-C

    - (void)editMessage:(SKYMessage *_Nonnull)message
               withBody:(NSString *_Nonnull)body
             completion:(SKYChatMessageCompletion _Nullable)completion;

    Swift

    func editMessage(_ message: SKYMessage, with body: String, completion: SKYChatMessageCompletion? = nil)

    Parameters

    message

    the message object

    body

    the new message body

    completion

    completion block

  • Send typing indicator to the specified conversation.

    This method calls -sendTypingIndicator:inConversation:date:completion: with the current date in the date parameter.

    Declaration

    Objective-C

    - (void)sendTypingIndicator:(SKYChatTypingEvent)typingEvent
                 inConversation:(SKYConversation *_Nonnull)conversation;

    Swift

    func sendTypingIndicator(_ typingEvent: SKYChatTypingEvent, in conversation: SKYConversation)

    Parameters

    typingEvent

    the event type

    conversation

    the conversation

  • Send typing indicator to the specified conversation.

    Most app developers should call the method -sendTypingIndicator:inConversation:date:completion: instead.

    Declaration

    Objective-C

    - (void)sendTypingIndicator:(SKYChatTypingEvent)typingEvent
                 inConversation:(SKYConversation *_Nonnull)conversation
                           date:(NSDate *_Nonnull)date
                     completion:(void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func sendTypingIndicator(_ typingEvent: SKYChatTypingEvent, in conversation: SKYConversation, at date: Date, completion: ((Error?) -> Void)? = nil)

    Parameters

    typingEvent

    the event type

    conversation

    the conversation

    date

    the date/time when this typing indicator occurs

    completion

    the completion handler

  • Fetches the user channel, or creates one if it does not exist.

    Declaration

    Objective-C

    - (void)fetchOrCreateUserChannelWithCompletion:
        (SKYChatChannelCompletion _Nullable)completion;

    Swift

    func fetchOrCreateUserChannel(completion: SKYChatChannelCompletion? = nil)

    Parameters

    completion

    the completion handler

  • Deletes all user channel.

    If chat extension is currently subscribed to a user channel, the chat extension will unsubscribe from the user channel first before deleting.

    Declaration

    Objective-C

    - (void)deleteAllUserChannelsWithCompletion:
        (void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func deleteAllUserChannels(completion: ((Error?) -> Void)? = nil)

    Parameters

    completion

    the completion handler

  • Subscribe to changes from user channel.

    Changes such as new messages and typing indicator are pushed to the client side using pubsub. If you are interested to receive these events, you should call this method so that chat extension will subscribe to these messages. When subscribed, the chat extension will post notifications using NSNotificationCenter. Observe to these notifications by adding an observer to the default NSNotificationCenter.

    If user channel does not exist yet, one will be created for you automatically.

    Alternatively, if you are interested in one type of events from the user channel such as typing indicators, you can call the -subscribeToTypingIndicatorInConversation:handler: convenient method to get typing indicator objects as they are received. You do not need to call this method as that convenient method will call this method for you.

    Declaration

    Objective-C

    - (void)subscribeToUserChannelWithCompletion:
        (void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func subscribeToUserChannelWithCompletion(completion: ((Error?) -> Void)? = nil)

    Parameters

    completion

    the completion handler

  • Unsubscribe from user channel.

    If the chat extension is currently subscribed to a user channel, the chat extension will unsubscribe from the underlying pubsub channel.

    The chat extension will also unsubscribe from user channel when the current user is changed (such as logout).

    Declaration

    Objective-C

    - (void)unsubscribeFromUserChannel;

    Swift

    func unsubscribeFromUserChannel()
  • Subscribe to typing indicator events in a conversation.

    To get typing indicator event, call this method with a handler that accepts a SKYChatTypingIndicator as parameter. You are also required to specify a conversation where typing indicator events apply. You may subscribe to multiple conversation at the same time.

    This method adds an observer to NSNotificationCenter and return the observer to you. If you are no longer interested in updates for a particular conversation. Remove the observer from NSNotificationCenter using the returned object.

    Declaration

    Objective-C

    - (id _Nonnull)
    subscribeToTypingIndicatorInConversation:(SKYConversation *_Nonnull)conversation
                                     handler:(void (^_Nonnull)(
                                                 SKYChatTypingIndicator *_Nonnull))
                                                 handler;

    Swift

    func subscribeToTypingIndicator(in conversation: SKYConversation, handler: @escaping (SKYChatTypingIndicator) -> Void) -> Any

    Parameters

    conversation

    the conversation object

    handler

    the typing indicator handler

    Return Value

    NSNotificationCenter observer

  • Subscribe to message events in a conversation.

    To get message event, call this method with a handler that accepts a SKYChatRecordChangeEvent and SKYMessage as parameters. You are also required to specify a conversation where message events apply. You may subscribe to multiple conversation at the same time.

    This method adds an observer to NSNotificationCenter and return the observer to you. If you are no longer interested in updates for a particular conversation. Remove the observer from NSNotificationCenter using the returned object.

    Declaration

    Objective-C

    - (id _Nonnull)
    subscribeToMessagesInConversation:(SKYConversation *_Nonnull)conversation
                              handler:
                                  (void (^_Nonnull)(SKYChatRecordChangeEvent,
                                                    SKYMessage *_Nonnull))handler;

    Swift

    func subscribeToMessages(in conversation: SKYConversation, handler: @escaping (SKYChatRecordChangeEvent, SKYMessage) -> Void) -> Any

    Parameters

    conversation

    the conversation object

    handler

    the message handler

    Return Value

    NSNotificationCenter observer

  • Subscribe to conversation events.

    To get conversion event, call this method with a handler that accepts a SKYChatRecordChangeEvent and SKYMessage as parameters.

    This method adds an observer to NSNotificationCenter and return the observer to you. If you are no longer interested in updates for a particular conversation. Remove the observer from NSNotificationCenter using the returned object.

    Declaration

    Objective-C

    - (id _Nonnull)subscribeToConversation:
        (void (^_Nonnull)(SKYChatRecordChangeEvent,
                          SKYConversation *_Nonnull))handler;

    Swift

    func subscribeToConversation(handler: @escaping (SKYChatRecordChangeEvent, SKYConversation) -> Void) -> Any

    Parameters

    handler

    the conversation handler

    Return Value

    NSNotificationCenter observer

  • Unsubscribe to conversation events

    This method removes an observer from NSNotificationCenter for message events. The observer can be obtained when subscribing conversation events.

    Declaration

    Objective-C

    - (void)unsubscribeToConversationWithObserver:(id _Nonnull)observer;

    Swift

    func unsubscribeToConversation(withObserver observer: Any)

    Parameters

    NSNotification

    observer

  • Unsubscribe to message events

    This method removes an observer from NSNotificationCenter for message events. The observer can be obtained when subscribing message events.

    Declaration

    Objective-C

    - (void)unsubscribeToMessagesWithObserver:(id _Nonnull)observer;

    Swift

    func unsubscribeToMessages(withObserver observer: Any)

    Parameters

    NSNotification

    observer

  • Unsubscribe to typing indicator events

    This method removes an observer from NSNotificationCenter for typing indicator events. The observer can be obtained when subscribing typing indicator events.

    Declaration

    Objective-C

    - (void)unsubscribeToTypingIndicatorWithObserver:(id _Nonnull)observer;

    Swift

    func unsubscribeToTypingIndicator(withObserver observer: Any)

    Parameters

    NSNotification

    observer