TCHConversation Class Reference

Inherits from NSObject
Declared in TCHConversation.h

Overview

Representation of a conversations conversation.

  delegate

Optional conversation delegate. Upon setting the delegate, you will receive the current conversation synchronization status by delegate method.

@property (nonatomic, weak, nullable) id<TCHConversationDelegate> delegate

Discussion

Optional conversation delegate. Upon setting the delegate, you will receive the current conversation synchronization status by delegate method.

Declared In

TCHConversation.h

  sid

The unique identifier for this conversation.

@property (nonatomic, copy, readonly, nullable) NSString *sid

Discussion

The unique identifier for this conversation.

Declared In

TCHConversation.h

  friendlyName

The friendly name for this conversation.

@property (nonatomic, copy, readonly, nullable) NSString *friendlyName

Discussion

The friendly name for this conversation.

Declared In

TCHConversation.h

  uniqueName

The unique name for this conversation.

@property (nonatomic, copy, readonly, nullable) NSString *uniqueName

Discussion

The unique name for this conversation.

Declared In

TCHConversation.h

  lastReadMessageIndex

Index of the last Message the User has marked as read in this Conversation.

@property (nonatomic, copy, readonly, nullable) NSNumber *lastReadMessageIndex

Discussion

Index of the last Message the User has marked as read in this Conversation.

Declared In

TCHConversation.h

– participants

Obtain the participants of this conversation.

- (nonnull NSArray<TCHParticipant*> *)participants

Discussion

Obtain the participants of this conversation.

Declared In

TCHConversation.h

  synchronizationStatus

The conversation’s synchronization status.

@property (nonatomic, assign, readonly) TCHConversationSynchronizationStatus synchronizationStatus

Discussion

The conversation’s synchronization status.

Declared In

TCHConversation.h

  status

The current user’s status on this conversation.

@property (nonatomic, assign, readonly) TCHConversationStatus status

Discussion

The current user’s status on this conversation.

Declared In

TCHConversation.h

  state

The current state for this conversation.

@property (readonly) TCHConversationState state

Discussion

The current state for this conversation.

Declared In

TCHConversation.h

  stateDateUpdatedAsDate

The date when TCHConversationState was last updated.

@property (readonly, nullable) NSDate *stateDateUpdatedAsDate

Discussion

The date when TCHConversationState was last updated.

Declared In

TCHConversation.h

  notificationLevel

The current user’s notification level on this conversation. This property reflects whether the user will receive push notifications for activity on this conversation.

@property (nonatomic, assign, readonly) TCHConversationNotificationLevel notificationLevel

Discussion

The current user’s notification level on this conversation. This property reflects whether the user will receive push notifications for activity on this conversation.

Declared In

TCHConversation.h

  dateCreated

The conversation creation date.

@property (nonatomic, strong, readonly, nullable) NSString *dateCreated

Discussion

The conversation creation date.

Declared In

TCHConversation.h

  dateCreatedAsDate

The conversation creation date as an NSDate.

@property (nonatomic, strong, readonly, nullable) NSDate *dateCreatedAsDate

Discussion

The conversation creation date as an NSDate.

Declared In

TCHConversation.h

  createdBy

The identity of the conversation’s creator.

@property (nonatomic, copy, readonly, nullable) NSString *createdBy

Discussion

The identity of the conversation’s creator.

Declared In

TCHConversation.h

  dateUpdated

The timestamp the conversation was last updated.

@property (nonatomic, strong, readonly, nullable) NSString *dateUpdated

Discussion

The timestamp the conversation was last updated.

Declared In

TCHConversation.h

  dateUpdatedAsDate

The timestamp the conversation was last updated as an NSDate.

@property (nonatomic, strong, readonly, nullable) NSDate *dateUpdatedAsDate

Discussion

The timestamp the conversation was last updated as an NSDate.

Declared In

TCHConversation.h

  lastMessageDate

The timestamp of the conversation’s most recent message.

@property (nonatomic, strong, readonly, nullable) NSDate *lastMessageDate

Discussion

The timestamp of the conversation’s most recent message.

Declared In

TCHConversation.h

  lastMessageIndex

The index of the conversation’s most recent message.

@property (nonatomic, strong, readonly, nullable) NSNumber *lastMessageIndex

Discussion

The index of the conversation’s most recent message.

Declared In

TCHConversation.h

– attributes

Return this conversation’s attributes.

- (nullable TCHJsonAttributes *)attributes

Return Value

The developer-defined extensible attributes for this conversation.

Discussion

Return this conversation’s attributes.

Declared In

TCHConversation.h

– setAttributes:completion:

Set this conversation’s attributes.

- (void)setAttributes:(nullable TCHJsonAttributes *)attributes completion:(nullable TCHCompletion)completion

Parameters

attributes

The new developer-defined extensible attributes for this conversation. (Supported types are NSString, NSNumber, NSArray, NSDictionary and NSNull)
completion

Completion block that will specify the result of the operation.

Discussion

Set this conversation’s attributes.

Declared In

TCHConversation.h

– setFriendlyName:completion:

Set this conversation’s friendly name.

- (void)setFriendlyName:(nullable NSString *)friendlyName completion:(nullable TCHCompletion)completion

Parameters

friendlyName

The new friendly name for this conversation.
completion

Completion block that will specify the result of the operation.

Discussion

Set this conversation’s friendly name.

Declared In

TCHConversation.h

– setUniqueName:completion:

Set this conversation’s unique name.

- (void)setUniqueName:(nullable NSString *)uniqueName completion:(nullable TCHCompletion)completion

Parameters

uniqueName

The new unique name for this conversation.
completion

Completion block that will specify the result of the operation.

Discussion

Set this conversation’s unique name.

Declared In

TCHConversation.h

– setNotificationLevel:completion:

Set the user’s notification level for the conversation. This property determines whether the user will receive push notifications for activity on this conversation.

- (void)setNotificationLevel:(TCHConversationNotificationLevel)notificationLevel completion:(nullable TCHCompletion)completion

Parameters

notificationLevel

The new notification level for the current user on this conversation.
completion

Completion block that will specify the result of the operation.

Discussion

Set the user’s notification level for the conversation. This property determines whether the user will receive push notifications for activity on this conversation.

Declared In

TCHConversation.h

– joinWithCompletion:

Join the current user to this conversation.

- (void)joinWithCompletion:(nullable TCHCompletion)completion

Parameters

completion

Completion block that will specify the result of the operation.

Discussion

Join the current user to this conversation.

Declared In

TCHConversation.h

– leaveWithCompletion:

Leave the current conversation.

- (void)leaveWithCompletion:(nullable TCHCompletion)completion

Parameters

completion

Completion block that will specify the result of the operation.

Discussion

Leave the current conversation.

Declared In

TCHConversation.h

– destroyWithCompletion:

Destroy the current conversation, removing all of its participants.

- (void)destroyWithCompletion:(nullable TCHCompletion)completion

Parameters

completion

Completion block that will specify the result of the operation.

Discussion

Destroy the current conversation, removing all of its participants.

Declared In

TCHConversation.h

– typing

Indicates to other users and the backend that the user is typing a message to this conversation.

- (void)typing

Discussion

Indicates to other users and the backend that the user is typing a message to this conversation.

Declared In

TCHConversation.h

– participantWithIdentity:

Fetch the participant object for the given identity if it exists.

- (nullable TCHParticipant *)participantWithIdentity:(nonnull NSString *)identity

Parameters

identity

The username to fetch.

Return Value

The TCHParticipant object, if one exists for the username for this conversation.

Discussion

Fetch the participant object for the given identity if it exists.

Declared In

TCHConversation.h

– participantWithSid:

Fetch the participant object for the given SID if it exists.

- (nullable TCHParticipant *)participantWithSid:(nonnull NSString *)sid

Parameters

sid

The participant’s SID.

Return Value

The TCHParticipant object, if one exists for the SID for this conversation.

Discussion

Fetch the participant object for the given SID if it exists.

Declared In

TCHConversation.h

– getUnreadMessagesCountWithCompletion:

Fetch the number of unread messages on this conversation for the current user.

- (void)getUnreadMessagesCountWithCompletion:(nonnull TCHNullableCountCompletion)completion

Parameters

completion

Completion block that will specify the requested count. If no completion block is specified, no operation will be executed.

Discussion

Fetch the number of unread messages on this conversation for the current user.

Use this method to obtain number of unread messages together with [TCHConversation setLastReadMessageIndex:completion:] instead of relying on TCHMessage indices which may have gaps. See [TCHMessage index] for details.

Available even if the conversation is not yet synchronized.

Note: if the last read index has not been yet set for current user as the participant of this conversation then unread messages count is considered uninitialized. In this case nil is returned. See [TCHConversation setLastReadMessageIndex:completion:].

This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Conversations system does not provide real time events for counter values changes.

So this is quite useful for any “unread messages count” badges, but is not recommended to build any core application logic based on these counters being accurate in real time. This function performs an async call to service to obtain up-to-date message count.

The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.

Declared In

TCHConversation.h

– getMessagesCountWithCompletion:

Fetch the number of messages on this conversation.

- (void)getMessagesCountWithCompletion:(nonnull TCHCountCompletion)completion

Parameters

completion

Completion block that will specify the requested count. If no completion block is specified, no operation will be executed.

Discussion

Fetch the number of messages on this conversation.

Available even if the conversation is not yet synchronized.

This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Conversations system does not provide real time events for counter values changes.

So this is quite useful for any UI badges, but is not recommended to build any core application logic based on these counters being accurate in real time. This function performs an async call to service to obtain up-to-date message count.

The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.

Declared In

TCHConversation.h

– getParticipantsCountWithCompletion:

Fetch the number of participants on this conversation.

- (void)getParticipantsCountWithCompletion:(nonnull TCHCountCompletion)completion

Parameters

completion

Completion block that will specify the requested count. If no completion block is specified, no operation will be executed.

Discussion

Fetch the number of participants on this conversation.

Available even if the conversation is not yet synchronized.

This method is semi-realtime. This means that this data will be eventually correct, but will also possibly be incorrect for a few seconds. The Conversations system does not provide real time events for counter values changes.

So this is quite useful for any UI badges, but is not recommended to build any core application logic based on these counters being accurate in real time. This function performs an async call to service to obtain up-to-date message count.

The retrieved value is then cached for 5 seconds so there is no reason to call this function more often than once in 5 seconds.

Declared In

TCHConversation.h

– sendMessageWithOptions:completion:

Sends a message to the conversation.

- (void)sendMessageWithOptions:(nonnull TCHMessageOptions *)options completion:(nullable TCHMessageCompletion)completion

Parameters

options

Message options.
completion

Completion block that will specify the result of the operation and a reference to the new message.

Discussion

Sends a message to the conversation.

Declared In

TCHConversation.h

– removeMessage:completion:

Removes the specified message from the conversation.

- (void)removeMessage:(nonnull TCHMessage *)message completion:(nullable TCHCompletion)completion

Parameters

message

The message to remove.
completion

Completion block that will specify the result of the operation.

Discussion

Removes the specified message from the conversation.

Declared In

TCHConversation.h

– getLastMessagesWithCount:completion:

Fetches the most recent count messages. This will return locally cached messages if they are all available or may require a load from the server.

- (void)getLastMessagesWithCount:(NSUInteger)count completion:(nonnull TCHMessagesCompletion)completion

Parameters

count

The number of most recent messages to return.
completion

Completion block that will specify the result of the operation as well as the requested messages if successful. If no completion block is specified, no operation will be executed.

Discussion

Fetches the most recent count messages. This will return locally cached messages if they are all available or may require a load from the server.

Declared In

TCHConversation.h

– getMessagesBefore:withCount:completion:

Fetches at most count messages including and prior to the specified index. This will return locally cached messages if they are all available or may require a load from the server.

- (void)getMessagesBefore:(NSUInteger)index withCount:(NSUInteger)count completion:(nonnull TCHMessagesCompletion)completion

Parameters

index

The starting point for the request.
count

The number of preceeding messages to return.
completion

Completion block that will specify the result of the operation as well as the requested messages if successful. If no completion block is specified, no operation will be executed.

Discussion

Fetches at most count messages including and prior to the specified index. This will return locally cached messages if they are all available or may require a load from the server.

Declared In

TCHConversation.h

– getMessagesAfter:withCount:completion:

Fetches at most count messages including and subsequent to the specified index. This will return locally cached messages if they are all available or may require a load from the server.

- (void)getMessagesAfter:(NSUInteger)index withCount:(NSUInteger)count completion:(nonnull TCHMessagesCompletion)completion

Parameters

index

The starting point for the request.
count

The number of succeeding messages to return.
completion

Completion block that will specify the result of the operation as well as the requested messages if successful. If no completion block is specified, no operation will be executed.

Discussion

Fetches at most count messages including and subsequent to the specified index. This will return locally cached messages if they are all available or may require a load from the server.

Declared In

TCHConversation.h

– messageWithIndex:completion:

Returns the message with the specified index.

- (void)messageWithIndex:(nonnull NSNumber *)index completion:(nonnull TCHMessageCompletion)completion

Parameters

index

The index of the message.
completion

Completion block that will specify the result of the operation as well as the requested message if successful. If no completion block is specified, no operation will be executed.

Discussion

Returns the message with the specified index.

Declared In

TCHConversation.h

– messageForReadIndex:completion:

Returns the oldest message starting at index. If the message at index does not exist, the next message will be returned.

- (void)messageForReadIndex:(nonnull NSNumber *)index completion:(nonnull TCHMessageCompletion)completion

Parameters

index

The index of the last message reported as read (may refer to a deleted message).
completion

Completion block that will specify the result of the operation as well as the requested message if successful. If no completion block is specified, no operation will be executed.

Discussion

Returns the oldest message starting at index. If the message at index does not exist, the next message will be returned.

Declared In

TCHConversation.h

– setLastReadMessageIndex:completion:

Set the last read index for this Participant and Conversation. Allows you to set any value, including smaller than the current index.

- (void)setLastReadMessageIndex:(nonnull NSNumber *)index completion:(nullable TCHCountCompletion)completion

Parameters

index

The new index.
completion

Optional completion block that will specify the result of the operation and an updated unread message count for the user on this conversation.

Discussion

Set the last read index for this Participant and Conversation. Allows you to set any value, including smaller than the current index.

Declared In

TCHConversation.h

– advanceLastReadMessageIndex:completion:

Update the last read index for this Participant and Conversation. Only update the index if the value specified is larger than the previous value.

- (void)advanceLastReadMessageIndex:(nonnull NSNumber *)index completion:(nullable TCHCountCompletion)completion

Parameters

index

The new index.
completion

Optional completion block that will specify the result of the operation and an updated unread message count for the user on this conversation.

Discussion

Update the last read index for this Participant and Conversation. Only update the index if the value specified is larger than the previous value.

Declared In

TCHConversation.h

– setAllMessagesReadWithCompletion:

Update the last read index for this Participant and Conversation to the max message currently on this device.

- (void)setAllMessagesReadWithCompletion:(nullable TCHCountCompletion)completion

Parameters

completion

Optional completion block that will specify the result of the operation and an updated unread message count for the user on this conversation.

Discussion

Update the last read index for this Participant and Conversation to the max message currently on this device.

Declared In

TCHConversation.h

– setAllMessagesUnreadWithCompletion:

Reset the last read index for this Participant and Conversation to no messages read.

- (void)setAllMessagesUnreadWithCompletion:(nullable TCHNullableCountCompletion)completion

Parameters

completion

Optional completion block that will specify the result of the operation and an updated unread message count for the user on this conversation.

Discussion

Reset the last read index for this Participant and Conversation to no messages read.

Declared In

TCHConversation.h

– addParticipantByIdentity:attributes:completion:

Add specified username to this conversation.

- (void)addParticipantByIdentity:(nonnull NSString *)identity attributes:(nullable TCHJsonAttributes *)attributes completion:(nullable TCHCompletion)completion

Parameters

identity

The username to add to this conversation.
attributes

The developer-defined extensible attributes for participant or nil to use default empty attributes. (Supported types are NSString, NSNumber, NSArray, NSDictionary and NSNull)
completion

Completion block that will specify the result of the operation.

Discussion

Add specified username to this conversation.

Declared In

TCHConversation.h

– addParticipantByAddress:proxyAddress:attributes:completion:

Add specified non chat participant to this conversation, i.e. sms, whatsapp participants etc.

- (void)addParticipantByAddress:(nonnull NSString *)address proxyAddress:(nonnull NSString *)proxyAddress attributes:(nullable TCHJsonAttributes *)attributes completion:(nullable TCHCompletion)completion

Parameters

address

The participant address to add to this conversation (phone number for sms and whatsapp participants)
proxyAddress

Proxy address (Twilio phone number for sms and whatsapp participants). See conversations quickstart for more info: https://www.twilio.com/docs/conversations/quickstart
attributes

The developer-defined extensible attributes for participant or nil to use default empty attributes. (Supported types are NSString, NSNumber, NSArray, NSDictionary and NSNull)
completion

StatusListener to report status of the action.

Discussion

Add specified non chat participant to this conversation, i.e. sms, whatsapp participants etc.

Declared In

TCHConversation.h

– removeParticipant:completion:

Remove specified participant from this conversation.

- (void)removeParticipant:(nonnull TCHParticipant *)participant completion:(nullable TCHCompletion)completion

Parameters

participant

The participant to remove from this conversation.
completion

Completion block that will specify the result of the operation.

Discussion

Remove specified participant from this conversation.

Declared In

TCHConversation.h

– removeParticipantByIdentity:completion:

Remove specified username from this conversation.

- (void)removeParticipantByIdentity:(nonnull NSString *)identity completion:(nullable TCHCompletion)completion

Parameters

identity

The username to remove from this conversation.
completion

Completion block that will specify the result of the operation.

Discussion

Remove specified username from this conversation.

Declared In

TCHConversation.h