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.
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.
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.
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
From now on, your login screen allows users to authenticate in your client.
The client can retrieve all conversations that your user belongs to via the getConversations method:
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.
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:
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.
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:
number of users (add/remove users)
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.
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).
To track changes of other messages, you have to subscribe to the didEditMessage / onEditMessage and didRemoveMessage / onRemoveMessage events as has been shown above.
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:
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.