1. References
  2. IOS SDK
  3. messaging
  4. VIConversation
Rate this page:

VIConversation

Interface that may be used to manage conversation.

Methods

addParticipants:completion:

Copy URL
- (
void
)addParticipants:(
NSArray<VIConversationParticipant *> *
)participants 
             completion:(
nullable VIMessengerCompletion<VIConversationEvent *> *
)completion

Add new participants to the conversation.

It's possible only on the following conditions:

Duplicated users are ignored. Will cause 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:

  1. Specify the completion parameter to consume the results with VIConversationEvent or VIErrorEvent in case of success/error accordingly.
  2. 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

Returns

  • type:

    void

editParticipants:completion:

Copy URL
- (
void
)editParticipants:(
NSArray<VIConversationParticipant *> *
)participants 
              completion:(
nullable VIMessengerCompletion<VIConversationEvent *> *
)completion

Edit participants' permissions. It's possible only if the current user can manage other participants ([VIConversationParticipant canManageParticipants] is YES).

Duplicated users are ignored. Will cause 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:

  1. Specify the completion parameter to consume the results with VIConversationEvent or VIErrorEvent in case of success/error accordingly.
  2. 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

Returns

  • type:

    void

markAsRead:completion:

Copy URL
- (
void
)markAsRead:(
SInt64
)sequence 
        completion:(
nullable VIMessengerCompletion<VIConversationServiceEvent *> *
)completion

Mark 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 will mark 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:

  1. Specify the handler parameter to consume the results with VIConversationServiceEvent or VIErrorEvent in case of success/error accordingly.
  2. 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. Shouldn't be greater than currently possible.

  • completion:

    nullable VIMessengerCompletion<VIConversationServiceEvent *> *

    Completion handler to get the result or nil

Returns

  • type:

    void

removeParticipants:completion:

Copy URL
- (
void
)removeParticipants:(
NSArray<VIConversationParticipant *> *
)participants 
                completion:(
nullable VIMessengerCompletion<VIConversationEvent *> *
)completion

Remove participants from the conversation.

It's possible only on two conditions:

Duplicated users are ignored. Will cause 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:

  1. Specify the completion parameter to consume the results with VIConversationEvent or VIErrorEvent in case of success/error accordingly.
  2. 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

Returns

  • type:

    void

retransmitEventsFrom:count:completion:

Copy URL
- (
void
)retransmitEventsFrom:(
SInt64
)from 
                       count:(
NSUInteger
)count 
                  completion:(
nullable VIMessengerCompletion<VIRetransmitEvent *> *
)completion

Request 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 can't 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 amount of retransmitted events per method call is 100. Requesting more than 100 events will cause VIErrorEvent.

If the current user quits a [VIConversation uber] conversation, messages that are posted during the user's absence will not be retransmitted later.

To get the method call result use one of the following options:

  1. Specify the completion parameter to consume the results with VIRetransmitEvent or VIErrorEvent in case of success/error accordingly.
  2. 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:

Copy URL
- (
void
)retransmitEventsFrom:(
SInt64
)from 
                          to:(
SInt64
)to 
                  completion:(
nullable VIMessengerCompletion<VIRetransmitEvent *> *
)completion

Request 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 can't 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 amount of retransmitted events per method call is 100. Requesting more than 100 events will cause VIErrorEvent.

If the current user quits a [VIConversation uber] conversation, messages that are posted during the user's absence will not be retransmitted later.

To get the method call result use one of the following options:

  1. Specify the completion parameter to consume the results with VIRetransmitEvent or VIErrorEvent in case of success/error accordingly.
  2. 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:

Copy URL
- (
void
)retransmitEventsTo:(
SInt64
)to 
                     count:(
NSUInteger
)count 
                completion:(
nullable VIMessengerCompletion<VIRetransmitEvent *> *
)completion

Request 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 can't 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 amount of retransmitted events per method call is 100. Requesting more than 100 events will cause VIErrorEvent.

If the current user quits a [VIConversation uber] conversation, messages that are posted during the user's absence will not be retransmitted later.

To get the method call result use one of the following options:

  1. Specify the completion parameter to consume the results with VIRetransmitEvent or VIErrorEvent in case of success/error accordingly.
  2. Implement the [VIMessengerDelegate messenger:didRetransmitEvents:] and [VIMessengerDelegate messenger:didReceiveError:] events.

Parameters

Returns

  • type:

    void

sendMessage:payload:completion:

Copy URL
- (
void
)sendMessage:(
nullable NSString *
)text 
            payload:(
nullable NSArray<NSDictionary<NSString *, NSObject *> *> *
)payload 
         completion:(
nullable VIMessengerCompletion<VIMessageEvent *> *
)completion

Send 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:

  1. Specify the completion parameter to consume the results with in case of success/error accordingly.
  2. 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:

Copy URL
- (
void
)typing:(
nullable VIMessengerCompletion<VIConversationServiceEvent *> *
)completion

Inform 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:

  1. Specify the completion parameter to consume the results with VIConversationServiceEvent or VIErrorEvent in case of success/error accordingly.
  2. 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

Returns

  • type:

    void

update:

Copy URL
- (
void
)update:(
nullable VIMessengerCompletion<VIConversationEvent *> *
)completion

Send conversation changes to the cloud. The sent changes are: title, public join flag and custom data.

Successful update will happen if a participant is the owner ([VIConversationParticipant owner] is YES).

To get the method call result use one of the following options:

  1. Specify the completion parameter to consume the results with VIConversationEvent or VIErrorEvent in case of success/error accordingly.
  2. 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

Returns

  • type:

    void

Props

createdTime

Copy URL
@property (assign, readonly, nonatomic) 
NSTimeInterval
 createdTime

A UNIX timestamp (seconds) that specifies the time of the conversation creation.

Returns

  • type:

    NSTimeInterval

customData

Copy URL
@property (copy, nonatomic) 
NSDictionary<NSString *, NSObject *> *
customData

A 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

Copy URL
@property (assign, readonly, nonatomic, getter = isDirect) 
BOOL
 direct

A Boolean value that determines whether the conversation is direct.

A direct conversation can't 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 can't 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 will return the UUID of the already existing direct conversation.

Returns

  • type:

    BOOL

lastSequence

Copy URL
@property (assign, readonly, nonatomic) 
SInt64
 lastSequence

The sequence of the last event in the conversation.

Returns

  • type:

    SInt64

lastUpdateTime

Copy URL
@property (assign, readonly, nonatomic) 
NSTimeInterval
 lastUpdateTime

A UNIX timestamp (seconds) that specifies the time when one of VIConversationEvent or VIMessageEvent was the last provoked event in this conversation.

Returns

  • type:

    NSTimeInterval

participants

Copy URL
@property (strong, readonly, nonatomic) 
NSArray<VIConversationParticipant *> *
participants

An array of participants alongside with their permissions.

Returns

publicJoin

Copy URL
@property (assign, nonatomic, getter = isPublicJoin) 
BOOL
 publicJoin

A Boolean value that determines whether the conversation is public.

If YES, anyone can join the conversation by UUID.

A public conversation can't 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

Copy URL
@property (copy, nullable, nonatomic) 
NSString *
title

The 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

Copy URL
@property (assign, readonly, nonatomic, getter = isUber) 
BOOL
 uber

A Boolean value that determines whether the conversation is uber.

A uber conversation can't be direct.

Users in a uber conversation will not be able to retrieve messages that were posted to the conversation after they quit.

Returns

  • type:

    BOOL

uuid

Copy URL
@property (strong, readonly, nonatomic) 
NSString *
uuid

An universally unique identifier (UUID) of this conversation.

Returns

  • type:

    NSString *