Rate this page:

Messaging: User2User

Beta

Messaging allows you to implement text communications within the main Voximplant developer account: account users can log in via Voximplant SDKs and become participants in conversations. Follow this tutorial to learn how to create your own web and mobile messaging client based on our SDKs.

What You Need

  • Voximplant developer account. If you don’t have one, sign up here.

  • Voximplant application, JS scenario, rule, and two users. Those will be created during this tutorial.

  • Client for users to log in. We’ll use our demo clients for Web, iOS and Android

  • Backend server for storing users of a Voximplant application.

Backend Server

It’s for the better to make a request for all available users within a Voximplant application at each client’s start. In order to do so, the client has to request all users related to already created conversation by using your Voximplant account credentials.

This is where the backend server is in need: we don’t want to store private authorization on the client side since it’s totally insecure (chances are you don’t want it either), so we can delegate it to backend. We’ve implemented a backend server using PHP, check the full listing of it here. You’re free to either use our solution or implement your own server using another programming language.

1. Voximplant Application Settings

First, log in to your account here: https://manage.voximplant.com/auth. On the left menu, select Applications, click New application and create a messaging application.

Next, you have to create at least two users for your application. Switch to the Users tab, click Create user, set username (e.g., user1) and password, then select the Create another checkbox and click Create. The same window for creating the second user will appear in which you should unselect Create another as we don’t need more users. We’ll need these users’ login-password pairs to authenticate in the clients.

2. Client

Connect to Voximplant and login

Initialize your project depending on what type of client you are going to use.

First, you have to make the login screen to work properly. The client has to know what credentials to use for authentication.

Connect to Voximplant and login

Connect to Voximplant and login

After successful initialization the client renders the login screen where you specify credentials, click Sign in and after that the client can log in to the Messaging module.

We suggest that this part of the code should do the following:

  • initiates a messaging instance

  • gets the current user info

  • gets all the conversations where the current user belongs to

  • receive other users from backend

  • add listeners for events that will be triggering over WebSockets

Sign in

Sign in

From now on, your login screen allows users to authenticate in your client.

Retrieve conversations

The client can retrieve all conversations that your user belongs to via the getConversations method:

Get current conversations

Get current conversations

Create conversations

Voximplant Messaging allows creating different types of conversations: regular (public and non-public) and direct ones, see the details here. In these particular demo clients they are implemented as chat, direct and broadcast. To create a conversation, there is a createConversation method, whereas the demo clients have appropriate wrappers for it.

Client-specific note

Permissions that are specified on creating a conversation become default permissions for this particular conversation; this means that all new participants will inherit them. If none of permissions is specified on creating a conversation, the following ones will be applied: canRead, canWrite, canRemove.

Here is an example of how to create a chat where all members can write and see messages of each other:

Create conversations

Create conversations

Pay attention that conversations are created on behalf of a user which is currently logged in on your client. That means this user becomes the owner and the very first admin of a newly created application with all possible permissions.

Once a conversation is created, others can join it or be joined by administrators of the conversation.

Managing conversations

Being an administrator, your user can edit conversations and also leave them. It’s possible due to the addParticipants, removeParticipants, addAdmins, removeAdmins, editPermissions and leaveConversation methods.

Editing includes changing of:

  • the title

  • users’ permissions

  • number of users (add/remove users)

  • custom data

Let’s assume that the administrator wants to change all the mentioned aspects – this is how you can handle it by calling the appropriate methods.

The method to change the title and custom data. Custom data changing has a nuance: you can’t just pass changes of one field, you have to copy all other fields, otherwise, other fields will be deleted.

Managing conversations

Managing conversations

Changing the user’s permissions

Changing the user’s permissions

Adding and removing users

Adding and removing users

Leaving a conversation

Leaving a conversation

The method could come in handy if you need to remove the conversation: the owner can remove all other participants, then leave the conversation and that is how it would be deleted.

Send/receive messages

The following method is responsible for sending messages: sendMessage.

To receive messages, you have to handle the event on message sending. Sending messages works in the same, event-driven way.

We’ve added this on initialization step (addMessengerEventListeners / VIMessengerDelegate).

Send and receive messages

Send and receive messages

Edit/remove messages

To track changes of other messages, you have to subscribe to the didEditMessage / onEditMessage and didRemoveMessage / onRemoveMessage events as has been shown above.

Editing your messages

Editing your messages

Removing messages

Removing messages

Retransmit events

There is a great variety of possible actions in a conversation and each of them triggers an appropriate event:

  • new user has been added

  • users’ permissions have been changed

  • conversation type has been changed

  • a new message has been sent to a conversation

  • and so on.

If a user is logged in to a client, each and every one of these events can be tracked by using listeners, but it won’t work if a user hasn’t been logged in. For example, the admin added a new participant to a conversation. There possibly could be a lot of other events between the adding itself and the moment when a newly added user will log in to messaging. How to ensure that the client with this user will retrieve all events that had triggered before the login? Retransmitting events is the answer.

Each time when a user logs in, you have to retransmit events that triggered before – this is the way to keep users up to date.

In the Web SDK, there is a retransmitEvents method that returns maximum 100 events.

In the iOS SDK, there are three methods, each of them returns maximum 100 events:

  • retransmitEvents

  • retransmitEventsFrom

  • retransmitEventsTo

In example of retransmitEvents, it accepts two required parameters, to and count, in order to specify the range of events. The to value should be retrieved from the lastSequence property of a conversation and count is just a number of maximum of 100.

Retransmitting events

Retransmitting events