Mesibo Backend APIs - User Management
Estimated reading time: 10 minutesBefore your users can use mesibo services, mesibo need to know about your users so that mesibo can enable real-time messaging, calls, and conference between them.
mesibo identifies each user by a unique random string, called address
. The address
can be anything, for example, phone number, email address, your enterprise user ID, etc. You need to create a mesibo user for each of your app users.
mesibo will generate an authentication token when you create a user. This user token is also called the access token. You need to send this token to your apps so that your app can initialize mesibo Mesibo Real-time APIs using this token. Refer to the Get Started tutorial to learn more about it.
mesibo backend user-management APIs allow you to create and edit users and able to generate access tokens. You can anytime add, edit or delete users or access tokens using backend APIs as explained below.
Adding a User
To add a user and to generate a user access token, you need to send the following JSON request to the backend API. You can use the same API to regenerate the token:
{
"op":"useradd",
"token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
"user": {
"address":"xyz@example.com",
"name":"User Name",
"token": {
"appid": "com.example.mesiboapp",
"expiry": 525600
}
}
}
Following are the request parameters, some of them are OPTIONAL.
Basic Parameters
Following are the request parameters, most of them are OPTIONAL unless the Default value is mentioned as Mandatory.
Parameter | Description | Default |
---|---|---|
op | MUST have the value - “useradd” (see example above) | Mandatory |
token | Application Token obtained from the mesibo console | Mandatory |
user.address | User Address (unique string). For example, phone number, email address, enterprise user ID, etc. | Mandatory |
user.active | enable user | true - active |
Token Generation Parameters
You need to use the following parameters only when generating or regenerating user access token:
Parameter | Description | Default |
---|---|---|
user.token | Access token object with parameters as explained below. The access token will not be generated if this object is not present in the request. | |
user.token.appid | Android package name declared in the AndroidManifest.xml (and google-services.json), Or iOS Bundle id declared in the Xcode project. The generated token will be applicable for the app having this package name or Bundle id only. For all other platforms, you can pass any non-numeric, dotted string (for example, com.yourdomain.yourapp), and the same need to be passed to the setAppName function. Use lower case only. |
|
user.token.expiry | token expiry in minutes. You should generate the token for a long duration instead of regenerating it. Regenerating tokens too many times may be charged. | 1 year |
user.token.device | Unique device string identifying the device where the generated token will be used. This field is OPTIONAL. Refer to the multi-device login documentation for the usage detail. | |
user.token.linkto | Link to another user. This field is OPTIONAL. Refer to the multi-device login documentation for the usage detail. |
User Permissions Parameters
You need to use the following parameters only if you need to set custom permissions for the user.
Parameter | Description | Default | |
---|---|---|---|
user.permissions.incoming | enable incoming messages | true | |
user.permissions.outgoing | enable outgoing messages | true | |
user.permissions.calls | enable video and voice calls | true | |
user.permissions.turn | enable TURN server usage for video and voice calls | true | |
user.permissions.storage | enable message storage | true | |
user.permissions.groupCreate | enable group creation by user | true | |
user.permissions.retention | store all messages to database - On-premise only | false | |
user.permissions.webhook | send messages to webhook instead of real-time API | false | |
user.permissions.peers | Peers with whom the user can communicate, 0 = All, 1 = Only specific peers set by the backend, 2 = Contacts Only, 3 = Favorites Only, refer to the contacts parameters below |
0 (All) |
User Profile Parameters
You need to use the following parameters only if you are setting profile information from the backend. Generally, the profile information is set by the user/apps using real-time profile APIs.
Parameter | Description | Default |
---|---|---|
user.profile.name | Name of the user | |
user.profile.image | Image URL of the user | |
user.profile.tn | base64 thumbnail of the user image | |
user.profile.status | Status text of the user | |
user.profile.description | Description text of the user | |
user.profile.update | Set true to update the profile, false to overwrite |
false |
user.profile.remove | Set true to remove the profile |
false |
User Contacts Parameters
You need to use the following parameters only if you are adding or modifying contacts for the user. Generally, the contact information is set by the user/apps using real-time contact sync APIs.
Parameter | Description | Default |
---|---|---|
user.contact.address | address of the contact | Mandatory |
user.contact.contact | add as a contact | true |
user.contact.subscribe | subscribe to profile and online status update | true |
user.contact.favorite | mark as a favorite | false |
user.contact.pair | mark as a communication pair if you have set the user.permissions.peers=1 (specific peers only). |
|
user.contact.block | block user | false |
user.contact.remove | remove from the contacts list and also delete all the messages | false |
user.contact.visibility | set the visibility. Refer to the real-time profile APIs documentation | 0 |
If the request is successful, the response will be like,
{
"user": {
"uid":123,
"address":"xyz@example.com",
"token":"79a818d76fe45fb5a3ac395a0a98251c3db2eetb7b0d4aa0"
},
"op":"useradd",
"result":true
}
where,
- user.address = User address that was sent in the request
- user.uid = Numerical unique user ID generated by the backend. You can use this UID instead of the address in other requests.
- user.token = Access token which you should use in the real-time API
You should save user information (UID, Address, Access Token, etc.) from the response to your database so that you can access them later. If you do not save them and instead call mesibo backend API every time you need them, your app will be slow, and you may be charged for excessive backend API usage (refer to the Backend API Invocations
on the Pricing page).
Modifying a User
To edit an existing user, send the following JSON request to the backend API. You need to use the address
or the UID
obtained from the useradd
operation.
{
"op":"userset",
"token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
"user": {
"uid":123,
"profile": {
"name":"User Name",
"image":"https://example.com/image.jpg",
"description":"Some description",
}
}
}
Parameter | Description | Default |
---|---|---|
op | MUST have the value - “userset” (see example above) | Mandatory |
token | Application Token obtained from the mesibo console | Mandatory |
The userset
request is the same as the useradd
request. The only difference is that the user MUST already exist for the userset
request to succeed. The request will fail if the user does not exist.
The request and response parameters are the same as the ones in useradd
operation.
Deleting a User
Delete an existing user using address
or UID
obtained from the useradd
operation.
{
"op":"userdel",
"token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
"user": {
"uid":123
}
}
Parameter | Description | Default |
---|---|---|
op | MUST have the value - “userdel” (see example above) | Mandatory |
token | Application Token obtained from the mesibo console | Mandatory |
uid | User ID | Mandatory |
If the request is successful, the response will be like,
{
"user": {
"uid":123
},
"op":"userdel",
"result":true
}
Delete a User Access Token
Delete an existing user access token without deleting a user. The user will be logged-out but mesibo will store all received messages for the user. Those messages will be delivered when the user logs in the next time with a new token.
To delete the user token, send userset
request with user.token.remove
parameter:
{
"op":"userset",
"token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
"user": {
"uid":123
"token": {
"remove": true
}
}
}
Get Users (on-premise hosted backend only)
Get users using an address or a UID. You can use a pattern to get matching users.
On Cloud, this API is only for development purposes only, and hence it is rate-limited and a maximum of 20 users will be returned. The reason is that many mesibo customers have millions of users and it is not practical to retrieve them. You should store your users locally instead of obtaining from the mesibo. You MUST not use this API in production and excessive use can be blocked. However, no such limitations apply for on-premise.
To get users, send usersget
request with address
or uid
parameter and the count
. You can also send empty request (without address
or uid
).
{
"op":"usersget",
"token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
"count": 50
"user": {
"uid":123
}
}
You can also use ‘*’ wildcards in address
field to get multiple users matching the pattern, for example,
{
"op":"usersget",
"token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
"count": 50
"user": {
"address": "hello*"
}
}