Managing Conversations with the Client SDK

This guide covers how to manage Conversations with the Vonage Client SDK. Before you begin, make sure you added the SDK to your app and created a Session (Android, iOS, JS).

A Conversation can be seen as a chat room when working with the Vonage Client SDK. Your application's Users can join Conversations. When they join a Conversation, they become a Member. Members can then send and receive messages.

Actions such as deleting a Conversation or Event are possible by any User with a Conversation ID. To control which Users can perform certain actions, restrict via ACLs on the JWT.

Creating a Conversation

The createConversation method allows you to create a Conversation by optionally passing in some parameters. Conversation names are required to be unique. If you do not supply a Conversation name or display name, one will be generated for you.

You can set:

Name
Display Name
Image URL
TTL
Custom Sort Key
Custom Data

const params = {
    name: "name",
    displayName: "displayName",
    imageUrl: "https://...",
    ttl: null, // 600 (in seconds)
    customSortKey: "customSortKey",
    customData: {key: "value"}
};

client.createConversation(params)
    .then(conversationId => {
        console.log("Id of created Conversation: ", conversationId);
    }).catch(error => {
        console.error("Error creating Conversation: ", error);
    });

val params = CreateConversationParameters("Conversation","Alice+Bob")
client.createConversation(params) { error, conversationId ->
    error?.takeIf { it is VGError }?.let {
        // Handle Error in creating Conversation
    } ?: error?.let {
        // Handle generic Exception
    }
    conversationId?.let { /* Conversation created */ }
}

let params = VGCreateConversationParameters(name: "Conversation", displayName: "Alice+Bob")
client.createConversation(params) { error, conversationId in
    ...
}

Getting Conversations

The getConversations method allows you to get all Conversations where the current User is a Member. You can optionally pass in some parameters to configure the response, if not the default values will be used. This method returns a paginated response. If you are unfamiliar with pagination, view the pagination guide.

You can set:

Order
Page Size
A cursor
Whether to include custom data
What to order by

const params = {
    order: "asc", // "desc"
    pageSize: 100,
    cursor: null,
    includeCustomData: false,
    orderBy: null // "CUSTOM_SORT_KEY"     
};

client.getConversations(params)
    .then(({conversations, nextCursor, previousCursor}) => {
        console.log("Array of Conversations: ", conversations);
        console.log("Cursor for next set of results, if any. Could be null: ", nextCursor);
        console.log("Cursor for previous set of results, if any. Could be null: ", previousCursor);
    }).catch(error => {
        console.error("Error getting Conversations: ", error);
    });

val params = GetConversationsParameters(
    order = PresentingOrder.DESC,
    pageSize = 10,
)

client.getConversations(params) { error, conversationsPage ->
    err?.let { /* Handle Error in fetching Conversations */ }
    conversationsPage?.let {
        val nextCursor = it.nextCursor
        it.conversations.forEach {conversation ->
            println("Conversation id: ${conversation.id}, name: ${conversation.name}, display name: ${conversation.displayName}")
        }
    }
}

let params = VGGetConversationsParameters(order: .asc, pageSize: 100)
client.getConversations(params) { error, conversationsPage in 
    if error == nil {
        let conversations = conversationsPage!.conversations
    } else {
        // Handle failure
    }
}

Getting a Conversation

Given a Conversation ID, you are able to get a Conversation object.

client.getConversation(conversationId)
    .then(conversation => {
        console.log("Successfully got Conversation: ", conversation);
    }).catch(error => {
        console.error("Error getting Conversation: ", error);
    });

client.getConversation("CONV_ID") { error, conversation ->
    error?.let { /* Handle Error in fetching Conversation */ }
    conversation?.let { /*Conversation received.*/ }
}

client.getConversation("CONV_ID") { error, conversation in
    ...
}

Updating a Conversation

The updateConversation method allows you to update the properties of your Conversation. You can pass in some parameters with 3 options:

Omitting a value - There is no change on the Conversation.
Providing a value (VGOption.some() on Android and iOS) - The value is updated on the Conversation.
Passing null (VGOption.some(null/nil) on Android and iOS) - The value is set to null or the default on the Conversation.

You can update these Conversation properties:

Name
Display Name
Image URL
TTL
Custom Sort Key
Custom Data

// Update the conversation displayName and remove the imageUrl
const params = {
    displayName: "New Display Name",
    imageUrl: null,
};

client.updateConversation("CONV_ID", params)
    .then(conversationId => {
        console.log("ID of updated Conversation: ", conversationId);
    }).catch(error => {
        console.error("Error creating Conversation: ", error);
    });

// Update the conversation displayName and remove the imageUrl
val params = UpdateConversationParameters(displayName = Option.Some("New Display Name"),
            imageUrl = Option.Some(null))
client.updateConversation("CONV_ID", params) { err, conversationId ->
    if(err == null){
        storedConversation = conversationId
    } else {
        // Handle error
    }
}

// Update the conversation displayName and remove the imageUrl
let params = VGUpdateConversationParameters(displayName: .some(value: "New Display Name"),
                                            imageUrl: .some(value: nil))
client.updateConversation("CONV_ID", parameters: params) { error, conversationId in
    if error == nil {
        storedConversation = conversationId
    } else {
        // Handle failure
    }
}

Getting a Conversation's Events

Given a Conversation ID, you are able to get a Conversation's Events. You can optionally pass in some parameters to configure the response, if not the default values will be used. This method returns a paginated response. If you are unfamiliar with pagination, view the pagination guide.

You can set:

Order
Page Size
A cursor
Events to filter by
Whether to include deleted events

const params = {
    order: "asc", // "desc"
    pageSize: 100,
    cursor: null,
    eventFilter: null, // ['message', 'member:joined']
    includeDeletedEvents: false,
    startId: null // 3
};

client.getConversationEvents(conversationId, params)
    .then(({events, nextCursor, previousCursor}) => {
        console.log("Array of Events: ", events);
        console.log("cursor for next set of results, if any. could be null: ", nextCursor);
        console.log("cursor for previous set of results, if any. could be null: ", previousCursor);
    }).catch(error => {
        console.error("Error getting Events: ", error);
    });

val params = GetConversationEventsParameters(PresentingOrder.ASC, 100)
client.getConversationEvents("CONV_ID", params) { error, eventsPage ->
    error?.let { /* Handle Error in fetching Conversation Events */ }
    eventsPage?.let {
        it.events.forEach { event ->
            //Process events
        }
    }
}

let params = VGGetConversationEventsParameters(order: .asc, pageSize: 100)
client.getConversationEvents("CONV_ID", parameters: params) { error, eventsPage in
    if error == nil {
        let events = eventsPage!.events
    } else {
        // Handle failure
    }
}

Deleting a Conversation's Events

Given an Event ID and Conversation ID, you are able to delete an event.

client.deleteEvent(eventId, conversationId)
    .then(() => {
        console.log("Successfully deleted EVent.");
    }).catch(error => {
        console.error("Error deleting Event: ", error);
    });

client.deleteEvent("EVENT_ID", "CONV_ID") { error ->
    error?.takeIf { it is VGError }?.let {/* Handle Vonage Error */ } ?:
    error?.let {/* Handle generic Error */ }
}

client.deleteEvent("EVENT_ID", conversationId: "CONV_ID") { error in
    if error != nil {
        // Handle failure
    }
}

Deleting a Conversation

Given a Conversation ID, you are able to delete a Conversation.

client.deleteConversation(conversationId)
    .then(() => {
        console.log("Successfully deleted Conversation.");
    }).catch(error => {
        console.error("Error deleting Conversation: ", error);
    });

client.deleteConversation("CONV_ID") { error ->
    error?.takeIf { it is VGError }?.let {/* Handle Vonage Error */} ?:
    error?.let {/* Handle generic Error */}
    /* Conversation Deleted */
}

client.deleteConversation("CONV_ID") { error in
    ...
}