To create a conversation, use the ConversationBuilder class in conjunction with the createConversation() method.

A unique ConversationId is required to create a conversation. This is up to the integrator to provide.

The ConversationBuilder interface automatically creates a GUID for this when it is instantiated. You can override this behaviour and specify your own ID using the withId("myConversationId") method.

The methods on this interface can be chained together.

ES6


import { ConversationBuilder } from "@comapi/sdk-js-foundation";

let conversation = new ConversationBuilder().withName("Support").withDescription("Support related chat").withUsers(["johnSmith", "joeBloggs"]);

sdk.services.appMessaging.createConversation(channelDetails)
    .then(conversationInfo => {
        console.log("conversation created", conversationInfo);
    })
    .catch(error => {
        fail("conversation creation failed: ", error);
    });

Classical

var conversation = new COMAPI.ConversationBuilder().withName("Support").withDescription("Support related chat").withUsers(["johnSmith", "joeBloggs"]);

sdk.services.appMessaging.createConversation(channelDetails)
    .then(function(conversationInfo) {
        console.log("conversation created", conversationInfo);
    })
    .catch(function(error) {
        fail("conversation creation failed: ", error);
    });

These samples are basically the same, except for the import of ConversationBuilder, which is available from the COMAPI global.

Add participants to a conversation

Participants can be added at the point that the conversation is created or on the fly at a later date.

To add a participant, you must specify two pieces of information:

profileId - the profileId of the user to add
role - the role of the participant ["member"|"owner"]

Example

    var participants = [
        {
            id: "johnSmith",
            role: "member",
        }, {
            id: "joeBloggs",
            role: "member",
        }
    ];

The addParticipantsToConversation() method takes a conversationId and an array of participant objects.

return sdk.services.appMessaging.addParticipantsToConversation(conversationInfo.id, participants)
    .then(result => {
        console.log("addMembersToConversation() succeeded", result);
    })
    .catch(error => {
        console.error("addMembersToConversation() failed", error);
    });

Remove participants from a conversation

To delete a participant, use the deleteParticipantsFromConversation() method. You can specify a list of users to remove.

sdk.services.appMessaging.deleteParticipantsFromConversation(conversationInfo.id, ["joeBloggs", "johnSmith"])
    .then(result => {
        console.log("deleteParticipantsFromConversation() succeeded", result);
    })
    .catch(error => {
        console.error("deleteParticipantsFromConversation() failed", error);
    });

List participants in a conversation

To query all the participants in a conversation, use the getParticipantsInConversation method. An array of participants is returned in the Promise result.

sdk.services.appMessaging.getParticipantsInConversation(conversationInfo.id)
    .then(result => {
        console.log("getParticipantsInConversation() succeeded", result);
    })
    .catch(error => {
        console.error("getParticipantsInConversation() failed", error);
    });

Delete a conversation

To delete a conversation, use the deleteConversation() method.

sdk.services.appMessaging.deleteConversation(conversationInfo.id)
    .then(result => {
        console.log("deleteConversation() succeeded", result);
    })
    .catch(error => {
        console.error("deleteConversation() failed", error);
    });

Conversation related events

All of these methods generate events which can be handled in your app.

Learn more in WebSocket events.

Events are especially useful when there is more than one user of your app, so all devices or users get notified of any conversation related changes

Event	Details
conversationDeleted	The conversation has been deleted.
conversationUndeleted	The conversation has been un-deleted.
conversationUpdated	The conversation has been updated; the name or description has changed.
participantAdded	A participant has been added to a conversation.
participantRemoved	A participant has been removed from a conversation.
participantTyping	A participant is `typing` in a conversation.