Inherits from NSObject
Declared in SKYChatExtension.h

Overview

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.

Tasks

Other Methods

Creating and fetching conversations

Adding and removing participants

Creating messages

Send message delivery and read receipts

Message Edit & Delete Function

Modifying read position with message marker

Typing indicator

Subscribing to events using pubsub

Extension Methods

Properties

automaticallyMarkMessagesAsDelivered

@property (assign, nonatomic) bool automaticallyMarkMessagesAsDelivered
Discussion

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.

Declared In

SKYChatExtension.h

container

@property (assign, nonatomic, readonly, nonnull) SKYContainer *container
Discussion

Gets an instance of SKYContainer used by this SKYChatExtension.

Declared In

SKYChatExtension_Private.h

userChannelMessageHandler

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

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.

Declared In

SKYChatExtension.h

Instance Methods

addAdminsWithUserIDs:toConversation:completion:NS_SWIFT_NAME:

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

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.

Parameters

userIDs

array of admin user ID

conversation

conversation record

completion

completion block

Declared In

SKYChatExtension.h

addMessage:toConversation:completion:NS_SWIFT_NAME:

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

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.

Parameters

message

message to add to a conversation

conversation

conversation object

completion

completion block

Declared In

SKYChatExtension.h

addParticipantsWithUserIDs:toConversation:completion:NS_SWIFT_NAME:

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

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.

Parameters

userIDs

array of participant user ID

conversation

conversation record

completion

completion block

Declared In

SKYChatExtension.h

createConversationWithParticipantIDs:title:metadata:adminIDs:distinctByParticipants:completion:NS_SWIFT_NAME:

- (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 NS_SWIFT_NAME
Discussion

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.

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

Declared In

SKYChatExtension.h

createConversationWithParticipantIDs:title:metadata:completion:NS_SWIFT_NAME:

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

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.

Parameters

participantIDs

an array of all participants in the conversation

title

title of the conversation

metadata

application metadata for the conversation

completion

completion block

Declared In

SKYChatExtension.h

createDirectConversationWithUserID:title:metadata:completion:NS_SWIFT_NAME:

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

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.

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

Declared In

SKYChatExtension.h

createMessageWithConversation:body:attachment:metadata:completion:NS_SWIFT_NAME:

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

Creates a message in the specified conversation with an attachment.

Parameters

conversation

conversation object

body

message body

attachment

SKYAsset object containing the attachment.

metadata

application metadata for the conversation

completion

completion block

Declared In

SKYChatExtension.h

createMessageWithConversation:body:metadata:completion:NS_SWIFT_NAME:

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

Creates a message in the specified conversation.

Parameters

conversation

conversation object

body

message body

metadata

application metadata for the conversation

completion

completion block

Declared In

SKYChatExtension.h

deleteAllUserChannelsWithCompletion:NS_SWIFT_NAME:

- (void)deleteAllUserChannelsWithCompletion:(void ( ^ _Nullable ) ( NSError *_Nullable error ))completion NS_SWIFT_NAME
Discussion

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.

Parameters

completion

the completion handler

Declared In

SKYChatExtension.h

deleteConversation:completion:NS_SWIFT_NAME:

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

Deletes a conversation.

This method can be used to delete an existing conversation.

Parameters

conversation

the conversation to be saved

completion

completion block

Declared In

SKYChatExtension.h

deleteMessage:inConversation:completion:NS_SWIFT_NAME:

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

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.

Parameters

message

the message object

conversation

the conversation object

completion

completion block

Declared In

SKYChatExtension.h

editMessage:withBody:completion:NS_SWIFT_NAME:

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

Edit a message in a conversation

The message body is updated.

Parameters

message

the message object

body

the new message body

completion

completion block

Declared In

SKYChatExtension.h

fetchConversationWithConversationID:fetchLastMessage:completion:NS_SWIFT_NAME:

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

Fetches a conversation by conversation ID.

Parameters

conversationID

ID of conversation

fetchLastMessage

whether to fetch the last message

completion

completion block

Declared In

SKYChatExtension.h

fetchConversationsWithCompletion:NS_SWIFT_NAME:

- (void)fetchConversationsWithCompletion:(SKYChatFetchConversationListCompletion _Nullable)completion NS_SWIFT_NAME
Discussion

Fetches conversations.

Parameters

completion

completion block

Declared In

SKYChatExtension.h

fetchConversationsWithFetchLastMessage:completion:NS_SWIFT_NAME:

- (void)fetchConversationsWithFetchLastMessage:(BOOL)fetchLastMessage completion:(SKYChatFetchConversationListCompletion _Nullable)completion NS_SWIFT_NAME
Discussion

Fetches conversations with optional last message in conversation.

Parameters

fetchLastMessage

whether to fetch the last message

completion

completion block

pageSize

maximum number of conversations to be fetched

page

page index of conversations to be fetched

Declared In

SKYChatExtension.h

fetchMessagesWithConversation:limit:beforeTime:order:completion:NS_SWIFT_NAME:

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

Fetch messages in a conversation.

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

Declared In

SKYChatExtension.h

fetchMessagesWithConversationID:limit:beforeTime:order:completion:NS_SWIFT_NAME:

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

Fetch messages in a conversation by ID.

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

Declared In

SKYChatExtension.h

fetchOrCreateUserChannelWithCompletion:NS_SWIFT_NAME:

- (void)fetchOrCreateUserChannelWithCompletion:(SKYChatChannelCompletion _Nullable)completion NS_SWIFT_NAME
Discussion

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

Parameters

completion

the completion handler

Declared In

SKYChatExtension.h

fetchReceiptsWithMessage:completion:NS_SWIFT_NAME:

- (void)fetchReceiptsWithMessage:(SKYMessage *_Nonnull)message completion:(void ( ^ _Nullable ) ( NSArray<SKYChatReceipt*> *_Nullable receipts , NSError *_Nullable error ))completion NS_SWIFT_NAME
Discussion

Fetch delivery and read receipts of a message.

Parameters

message

the message object

completion

completion block

Declared In

SKYChatExtension.h

fetchTotalUnreadCount:NS_SWIFT_NAME:

- (void)fetchTotalUnreadCount:(SKYChatUnreadCountCompletion _Nullable)completion NS_SWIFT_NAME
Discussion

Fetches the total unread count of conversations and messages.

Parameters

completion

completion block

Declared In

SKYChatExtension.h

fetchUnreadCountWithConversation:completion:NS_SWIFT_NAME:

- (void)fetchUnreadCountWithConversation:(SKYConversation *_Nonnull)conversation completion:(SKYChatUnreadCountCompletion _Nullable)completion NS_SWIFT_NAME
Discussion

Fetches unread count of a conversation

Parameters

conversation

the conversation object

completion

completion block

Declared In

SKYChatExtension.h

initWithContainer:

- (nullable instancetype)initWithContainer:(nonnull SKYContainer *)container
Discussion

Creates an instance of SKYChatExtension.

For most user of the chat extension, get an instance of SKYChatExtension by using the category method called [SKYContainer chatExtension].

Parameters

container

the SKYContainer that contains user credentials and server configuration

Return Value

an instance of SKYChatExtension

Declared In

SKYChatExtension_Private.h

leaveConversation:completion:

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

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.

Declared In

SKYChatExtension.h

leaveConversationWithConversationID:completion:NS_SWIFT_NAME:

- (void)leaveConversationWithConversationID:(NSString *_Nonnull)conversationID completion:(void ( ^ _Nullable ) ( NSError *_Nullable error ))completion NS_SWIFT_NAME
Discussion

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.

Declared In

SKYChatExtension.h

markDeliveredMessages:completion:NS_SWIFT_NAME:

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

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.

Parameters

messages

messages to delivered

completion

completion block

Declared In

SKYChatExtension.h

markDeliveredMessagesWithID:completion:NS_SWIFT_NAME:

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

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.

Parameters

messageIDs

ID of messages to delivered

completion

completion block

Declared In

SKYChatExtension.h

markLastReadMessage:inConversation:completion:NS_SWIFT_NAME:

- (void)markLastReadMessage:(SKYMessage *_Nonnull)message inConversation:(SKYConversation *_Nonnull)conversation completion:(SKYChatConversationCompletion _Nullable)completion NS_SWIFT_NAME
Discussion

Mark a message as the last read message in a conversation.

The last read message affects the last read position of messages in a conversation. The number of unread conversations will change. Calling this method will not affect delivery and read receipts.

Parameters

message

the message object

conversation

the conversation object

completion

completion block

Declared In

SKYChatExtension.h

markReadMessages:completion:NS_SWIFT_NAME:

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

Marks messages as read.

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

Parameters

messages

messages to mark

completion

completion block

Declared In

SKYChatExtension.h

markReadMessagesWithID:completion:NS_SWIFT_NAME:

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

Marks messages as read.

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

Parameters

messageIDs

ID of messages to mark

completion

completion block

Declared In

SKYChatExtension.h

removeAdminsWithUserIDs:fromConversation:completion:NS_SWIFT_NAME:

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

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.

Parameters

userIDs

array of admin user ID

conversation

conversation record

completion

completion block

Declared In

SKYChatExtension.h

removeParticipantsWithUserIDs:fromConversation:completion:NS_SWIFT_NAME:

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

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.

Parameters

userIDs

array of participant user ID

conversation

conversation record

completion

completion block

Declared In

SKYChatExtension.h

saveConversation:completion:NS_SWIFT_NAME:

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

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.

Parameters

conversation

the conversation to be saved

completion

completion block

Declared In

SKYChatExtension.h

sendTypingIndicator:inConversation:NS_SWIFT_NAME:

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

Send typing indicator to the specified conversation.

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

Parameters

typingEvent

the event type

conversation

the conversation

Declared In

SKYChatExtension.h

sendTypingIndicator:inConversation:date:completion:NS_SWIFT_NAME:

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

Send typing indicator to the specified conversation.

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

Parameters

typingEvent

the event type

conversation

the conversation

date

the date/time when this typing indicator occurs

completion

the completion handler

Declared In

SKYChatExtension.h

subscribeToConversation:NS_SWIFT_NAME:

- (id _Nonnull)subscribeToConversation:(void ( ^ _Nonnull ) ( SKYChatRecordChangeEvent event , SKYConversation *_Nonnull conversation ))handler NS_SWIFT_NAME
Discussion

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.

Parameters

handler

the conversation handler

Return Value

NSNotificationCenter observer

Declared In

SKYChatExtension.h

subscribeToMessagesInConversation:handler:NS_SWIFT_NAME:

- (id _Nonnull)subscribeToMessagesInConversation:(SKYConversation *_Nonnull)conversation handler:(void ( ^ _Nonnull ) ( SKYChatRecordChangeEvent event , SKYMessage *_Nonnull record ))handler NS_SWIFT_NAME
Discussion

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.

Parameters

conversation

the conversation object

handler

the message handler

Return Value

NSNotificationCenter observer

Declared In

SKYChatExtension.h

subscribeToTypingIndicatorInConversation:handler:NS_SWIFT_NAME:

- (id _Nonnull)subscribeToTypingIndicatorInConversation:(SKYConversation *_Nonnull)conversation handler:(void ( ^ _Nonnull ) ( SKYChatTypingIndicator *_Nonnull indicator ))handler NS_SWIFT_NAME
Discussion

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.

Parameters

conversation

the conversation object

handler

the typing indicator handler

Return Value

NSNotificationCenter observer

Declared In

SKYChatExtension.h

subscribeToUserChannelWithCompletion:NS_SWIFT_NAME:

- (void)subscribeToUserChannelWithCompletion:(void ( ^ _Nullable ) ( NSError *_Nullable error ))completion NS_SWIFT_NAME
Discussion

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.

Parameters

completion

the completion handler

Declared In

SKYChatExtension.h

unsubscribeFromUserChannel

- (void)unsubscribeFromUserChannel
Discussion

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

Declared In

SKYChatExtension.h

unsubscribeToConversationWithObserver:

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

Unsubscribe to conversation events

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

Parameters

NSNotification

observer

Declared In

SKYChatExtension.h

unsubscribeToMessagesWithObserver:

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

Unsubscribe to message events

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

Parameters

NSNotification

observer

Declared In

SKYChatExtension.h

unsubscribeToTypingIndicatorWithObserver:

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

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.

Parameters

NSNotification

observer

Declared In

SKYChatExtension.h