VIConversation
Interface that provides API to manage conversations.
Methods
addParticipants:completion:
- (void
)addParticipants:(NSArray<VIConversationParticipant *> *
)participants
completion:(nullable VIMessengerCompletion<VIConversationEvent *> *
)completion
Adds new participants to the conversation.
It is possible only on the following conditions:
- the participants are users of the main Voximplant developer account or its child accounts
- the current user can manage other participants ([VIConversationParticipant canManageParticipants] is YES)
- the conversation is not a direct one ([VIConversation direct] is NO)
Duplicated users are ignored. Causes VIErrorEvent if at least one user does not exist or already belongs to the conversation.
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with VIConversationEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didEditConversation:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Other parties of the conversation (online participants and logged in clients) can be informed about adding participants via the [VIMessengerDelegate messenger:didEditConversation:] event.
Parameters
participants:
NSArray<VIConversationParticipant *> *
Array of VIConversationParticipant to be added to the conversation. Should not be nil or empty array
completion:
nullable VIMessengerCompletion<VIConversationEvent *> *
Completion handler to get the result or nil
Returns
type:
void
editParticipants:completion:
- (void
)editParticipants:(NSArray<VIConversationParticipant *> *
)participants
completion:(nullable VIMessengerCompletion<VIConversationEvent *> *
)completion
Edits participants' permissions. It is possible only if the current user can manage other participants ([VIConversationParticipant canManageParticipants] is YES).
Duplicated users are ignored. Causes VIErrorEvent if at least one user does not exist or belong to the conversation.
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with VIConversationEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didEditConversation:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Other parties of the conversation (online participants and logged in clients) can be informed about editing participants via the [VIMessengerDelegate messenger:didEditConversation:] event.
Parameters
participants:
NSArray<VIConversationParticipant *> *
Array of VIConversationParticipant to be edited in the conversation. Should not be nil or empty array
completion:
nullable VIMessengerCompletion<VIConversationEvent *> *
Completion handler to get the result or nil
Returns
type:
void
markAsRead:completion:
- (void
)markAsRead:(SInt64
)sequence
completion:(nullable VIMessengerCompletion<VIConversationServiceEvent *> *
)completion
Marks the event with the specified sequence as read.
A method call with the specified sequence makes the [VIConversationParticipant lastReadEventSequence] property return this sequence, i.e., such sequences can be get for each participant separately.
If the sequence parameter specified less than 1, the method marks all the events as unread (for this participant) except the event with the sequence equals to '1'.
To get the method call result use one of the following options:
- Specify the handler parameter to consume the results with VIConversationServiceEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didReceiveReadConfirmation:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Other parties of the conversation (online participants and logged in clients) can be informed about marking events as read via the [VIMessengerDelegate messenger:didReceiveReadConfirmation:] event.
Parameters
sequence:
SInt64
Sequence number of the event in the conversation to be marked as read. Should not be greater than currently possible.
completion:
nullable VIMessengerCompletion<VIConversationServiceEvent *> *
Completion handler to get the result or nil
Returns
type:
void
removeParticipants:completion:
- (void
)removeParticipants:(NSArray<VIConversationParticipant *> *
)participants
completion:(nullable VIMessengerCompletion<VIConversationEvent *> *
)completion
Removes participants from the conversation.
It is possible only on two conditions:
- the current user can manage other participants ([VIConversationParticipant canManageParticipants] is YES).
- the conversation is not a direct one ([VIConversation direct] is NO)
Duplicated users are ignored. Causes VIErrorEvent if at least one user:
- does not exist
- is already removed
Note that you can remove participants that are marked as deleted ([VIUser deleted] is YES).
The removed users can later get this conversation's UUID via the [VIUser leaveConversationList] method.
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with VIConversationEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didEditConversation:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Other parties of the conversation (online participants and logged in clients) can be informed about removing participants via the [VIMessengerDelegate messenger:didEditConversation:] event.
Parameters
participants:
NSArray<VIConversationParticipant *> *
Array of VIConversationParticipant to be removed from the conversation. Should not be nil or empty array
completion:
nullable VIMessengerCompletion<VIConversationEvent *> *
Completion handler to get the result or nil
Returns
type:
void
retransmitEventsFrom:count:completion:
- (void
)retransmitEventsFrom:(SInt64
)from
count:(NSUInteger
)count
completion:(nullable VIMessengerCompletion<VIRetransmitEvent *> *
)completion
Requests a number of events starting with the specified sequence to be sent from the cloud to this client.
Only VIConversationEvent and VIMessageEvent events can be retransmitted; any other events cannot be retransmitted.
The method is used to get history or missed events in case of network disconnect. Client should use this method to request all events based on the last event sequence received from the cloud and last event sequence saved locally (if any).
The maximum number of retransmitted events per method call is 100. Requesting more than 100 events causes VIErrorEvent.
If the current user quits a [VIConversation uber] conversation, messages that are posted during the user's absence are not retransmitted later.
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with VIRetransmitEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didRetransmitEvents:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Parameters
from:
SInt64
First event in sequence range, inclusive
count:
NSUInteger
Number of events
completion:
nullable VIMessengerCompletion<VIRetransmitEvent *> *
Completion handler to get the result or nil
Returns
type:
void
retransmitEventsFrom:to:completion:
- (void
)retransmitEventsFrom:(SInt64
)from
to:(SInt64
)to
completion:(nullable VIMessengerCompletion<VIRetransmitEvent *> *
)completion
Requests events in the specified sequence range to be sent from the cloud to this client.
Only VIConversationEvent and VIMessageEvent events can be retransmitted; any other events cannot be retransmitted.
The method is used to get history or missed events in case of network disconnect. Client should use this method to request all events based on the last event sequence received from the cloud and last event sequence saved locally (if any).
The maximum number of retransmitted events per method call is 100. Requesting more than 100 events causes VIErrorEvent.
If the current user quits a [VIConversation uber] conversation, messages that are posted during the user's absence are not retransmitted later.
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with VIRetransmitEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didRetransmitEvents:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Parameters
from:
SInt64
First event in sequence range, inclusive
to:
SInt64
Last event in sequence range, inclusive
completion:
nullable VIMessengerCompletion<VIRetransmitEvent *> *
Completion handler to get the result or nil
Returns
type:
void
retransmitEventsTo:count:completion:
- (void
)retransmitEventsTo:(SInt64
)to
count:(NSUInteger
)count
completion:(nullable VIMessengerCompletion<VIRetransmitEvent *> *
)completion
Requests a number of events up to the specified sequence to be sent from the cloud to this client.
Only VIConversationEvent and VIMessageEvent events can be retransmitted; any other events cannot be retransmitted.
The method is used to get history or missed events in case of network disconnect. Client should use this method to request all events based on the last event sequence received from the cloud and last event sequence saved locally (if any).
The maximum number of retransmitted events per method call is 100. Requesting more than 100 events causes VIErrorEvent.
If the current user quits a [VIConversation uber] conversation, messages that are posted during the user's absence are not retransmitted later.
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with VIRetransmitEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didRetransmitEvents:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Parameters
to:
SInt64
Last event in sequence range, inclusive
count:
NSUInteger
Number of events
completion:
nullable VIMessengerCompletion<VIRetransmitEvent *> *
Completion handler to get the result or nil
Returns
type:
void
sendMessage:payload:completion:
- (void
)sendMessage:(nullable NSString *
)text
payload:(nullable NSArray<NSDictionary<NSString *, NSObject *> *> *
)payload
completion:(nullable VIMessengerCompletion<VIMessageEvent *> *
)completion
Sends a message to the conversation.
Sending messages is available only for participants that have write permissions ([VIConversationParticipant canWrite] is YES).
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with
in case of success/error accordingly. - Implement the [VIMessengerDelegate messenger:didSendMessage:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Other parties of the conversation (online participants and logged in clients) can be informed about sending messages to the conversation via the Implement the [VIMessengerDelegate messenger:didSendMessage:] event.
To be informed about sending messages while being offline, participants can subscribe to the VIMessengerNotificationSendMessage messenger push notification.
Parameters
text:
nullable NSString *
Message text, maximum 5000 characters
payload:
nullable NSArray<NSDictionary<NSString *, NSObject *> *> *
Message payload
completion:
nullable VIMessengerCompletion<VIMessageEvent *> *
Completion handler to get the result or nil
Returns
type:
void
typing:
- (void
)typing:(nullable VIMessengerCompletion<VIConversationServiceEvent *> *
)completion
Informs the cloud that the user is typing some text.
The method calls within 10s interval from the last call cause VIErrorEvent.
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with VIConversationServiceEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didReceiveTypingNotification:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Other parties of the conversation (online participants and logged in clients) can be informed about typing via the [VIMessengerDelegate messenger:didReceiveTypingNotification:] event.
Parameters
completion:
nullable VIMessengerCompletion<VIConversationServiceEvent *> *
Completion handler to get the result or nil
Returns
type:
void
update:
- (void
)update:(nullable VIMessengerCompletion<VIConversationEvent *> *
)completion
Sends conversation's changes to the cloud. The changes are: title, public join flag and custom data.
Successful update happens if a participant is the owner ([VIConversationParticipant owner] is YES).
To get the method call result use one of the following options:
- Specify the completion parameter to consume the results with VIConversationEvent or VIErrorEvent in case of success/error accordingly.
- Implement the [VIMessengerDelegate messenger:didEditConversation:] and [VIMessengerDelegate messenger:didReceiveError:] events.
Other parties of the conversation (online participants and logged in clients) can be informed about changing the title or custom data and enabling/disabling public join via the [VIMessengerDelegate messenger:didEditConversation:] event.
Parameters
completion:
nullable VIMessengerCompletion<VIConversationEvent *> *
Completion handler to get the result or nil
Returns
type:
void
Props
createdTime
@property (assign, readonly, nonatomic) NSTimeInterval
createdTime
UNIX timestamp (seconds) that specifies the time of the conversation creation.
Returns
type:
NSTimeInterval
customData
@property (copy, nonatomic) NSDictionary<NSString *, NSObject *> *
customData
Custom data, up to 5kb.
Note that changing this property value does not send changes to the cloud. Use [VIConversation update:] to send all changes at once.
Returns
type:
NSDictionary<NSString *, NSObject *> *
direct
@property (assign, readonly, nonatomic, getter = isDirect) BOOL
direct
Whether the conversation is direct.
A direct conversation cannot be uber and/or public.
There can be only 2 participants in a direct conversation which is unique and the only one for these participants. There cannot be more than 1 direct conversation for the same 2 users.
If one of these users tries to create a new direct conversation with the same participant via [VIMessenger createConversation:completion:] the method returns the UUID of the already existing direct conversation.
Returns
type:
BOOL
lastSequence
@property (assign, readonly, nonatomic) SInt64
lastSequence
Sequence of the last event in the conversation.
Returns
type:
SInt64
lastUpdateTime
@property (assign, readonly, nonatomic) NSTimeInterval
lastUpdateTime
UNIX timestamp (seconds) that specifies the time when one of VIConversationEvent or VIMessageEvent has been the last provoked event in this conversation.
Returns
type:
NSTimeInterval
participants
@property (strong, readonly, nonatomic) NSArray<VIConversationParticipant *> *
participants
An array of participants and their permissions.
Returns
type:
NSArray<VIConversationParticipant *> *
publicJoin
@property (assign, nonatomic, getter = isPublicJoin) BOOL
publicJoin
Whether the conversation is public.
If YES, anyone can join the conversation by UUID.
A public conversation cannot be direct.
Note that changing this property value does not send changes to the cloud. Use [VIConversation update:] to send all changes at once
Returns
type:
BOOL
title
@property (copy, nullable, nonatomic) NSString *
title
Current conversation title.
Note that changing this property value does not send changes to the cloud. Use [VIConversation update:] to send all changes at once
Returns
type:
NSString *
uber
@property (assign, readonly, nonatomic, getter = isUber) BOOL
uber
Whether the conversation is uber.
A uber conversation cannot be direct.
Users in a uber conversation cannot retrieve messages that have been posted to the conversation after they quit.
Returns
type:
BOOL
uuid
@property (strong, readonly, nonatomic) NSString *
uuid
Universally unique identifier (UUID) of this conversation.
Returns
type:
NSString *