Open in app

Sign in

Write

Sign in

SAMA chat server API: Users

EASY — ACCESSIBLE — UNDERSTANDABLE

Oleksandr Chabaniuk
SAMA communications

--

All messengers and services that use instant messaging require minimal user identification in the system. We have developed a universal API that you can use in both small startups and large-scale projects, so the constant support and expansion of our API functionality have great prospects that we will gradually bring to life.

The User object is your shadow in the application system, it will be responsible for your identification 👀 in the system and provide you with access 🔓 to the appropriate chats. That’s why the authorization process should be as confidential and fast as possible for convenient use.

At the moment, our API has 6 main methods:

  • ➕ user_create | Create a new user
  • 🔽 user_login | Log in to the system
  • 🔼 user_logut | Log out of the active user session
  • ✏️ user_edit | Edit user data
  • ❌ user_delete | Delete a user
  • 🔍 user_search | Search for users in the database

Create a new user

~ request name: user_create

Your first request will definitely be a request to create a user, so let’s see how to do it and what it can do.

The main fields we will work with will be login, password, and deviceId. Send a unique username and strong password and create your user.

It looks very easy, but why do we need the deviceId field?

In this field, you must enter the unique ID of your device or browser tab.

❕In the future, we will use this information to correctly manage the records of active user sessions.

Add two more fields and our request ⬆️ will look like this:

{
  request: {
    user_create: {
      login: "Oleks41",
      email: "oleks41@test.com",
      phone: "1234567890",
      password: "SecretCode",
      deviceId: "device_laptop"
    },
    id: "create_request"
  }
}

❗️login, email, and phone fields are unique, so they can’t be repeated.

The password field will be transmitted hidden, so no one will be able to see your secret code. Also, this field will be stored in an encrypted format only.

After successfully creating a user in the system, you will receive the following response ⬇️:

{
  response: {
    user: {
      _id: "64e8a21aa9d7b47ad358425c",
      login: "oleks41",
      email: "oleks41@test.com",
      phone: "1234567890",
      recent_activity: 1692967450,
      created_at: "2023-08-25T12:44:10.372Z",
      updated_at: "2023-08-25T12:44:10.372Z"
    },
    id: "create_request"
  }
}
  • The login field is stored in lowercase in the database. As a result, the login is not case-sensitive.
  • The recent_activity field of the user is generated automatically, setting the value to the time when the record was saved in the database.

Log in to the system

~ request name: user_login

That’s great! How do we register user sessions? Or close active user sessions?

When we need a user to log in to the system, we need to collect the user’s login and password information and send it to the server as a request ⬆️ like this:

{
  request: {
    user_login: {
      login: "Oliv3r1",
      password: "SecretCode",
      deviceId: "device_laptop"
    },
    id: "login_request"
  }
}

Having sent the request, let’s talk about the peculiarities of the method’s functioning and the user session’s structure in general ⚙️.

I believe that the fact of checking user registration in the system and data validation is an obvious function of this method, so let’s move on.

The main task of the method is to:

  • 💡 Token generation.
  • 🔑 Validation of an existing token.
  • 📂 Correctly saving the current user session in the system so that there is no session conflict.

Only one token? And when it expires, will the session be closed?

Yes, only one access token. At the moment, you will be redeeming the access token in response to your request, and when the token expires, you will need to re-enter your login details.

* In the near future, we plan to expand the logic of the current method so that the user does not need to constantly re-login.

It is worth noting that if you already have an access token, you can send it to the server without any extra user data, and it will be processed and verified on the server, if everything goes well, you will receive a new access token for the next login, and your session will be prolonged ♻️.

Therefore, your request ⬆️ may have an alternative entry:

{
  request: {
    user_login: {
      token: "...",
      deviceId: "device_laptop"
    },
    id: "login_request"
  }
}

And now for some features of user activity:

  • Each time you log in and out of the application, a notification will be sent to all users who are subscribed to track your activity, indicating your current activity status. The message ✉️ will look like this:
{
  last_activity: {
    6479dfa24f8e0c57edf07dd1: 1693209474 / "online"
  }
}

❕You can read more about user activity tracking and other API mechanisms in our feed now or in the near future.

  • If you pass an existing device ID, the previous sessions will be closed and only the current one will remain. All those devices receive notifications ✉️:
{ error: "Device replacement" }

And no matter what your request is, your response ⬇️ will look like this:

{
  response: {
    token: "...",
    user: {
      _id: "6479dfa24f8e0c57edf07dd1",
      login: "Oliv3r1",
      recent_activity: 1693209940,
      created_at: "2023-06-02T12:25:06.529Z",
      updated_at: "2023-06-02T12:25:06.529Z"
    },
    id: "login_request"
  }
}

If you still have doubts about the speed of our API, then scroll down to the Try SAMA 👇🏼 block and see for yourself 😉.

Log out of the active user session

~ request name: user_logout

If you no longer need the current session or simply want to close it, all you need to do is send a request ⬆️ from the desired user:

{
  request: {
    user_logout: {},
    id: "logout_request"
  }
}

If the server finds the specified session on the device, it will clear all records about it, close access using this token, and send you a response ⬇️ ️ message about the successful completion of the request:

{
  response: {
    success: true,
    id: "logout_request"
  }
}

Edit user data

~ request name: user_edit

What if I set the wrong password? Or did I make a mistake when entering my email or phone number?

No problem! All you need to do is send a requisition with new data.

However, if you want to change your password 🔑 as well, you will need to provide your current password to confirm the operation.

Your request ⬆️ with all possible parameters can look like this:

{
  request: {
    user_edit: {
      login: "Oliv3r2",
      current_password: "SecretCode",
      new_password: "NewSecretCode",
      first_name: "Darcy",
      last_name: "Stevenson",
      email: ".darcy.s@test.com",
      phone: "1234567890"
    },
    id: "edit_request"
  }
}

❗️login, email, and phone fields are unique, so they can’t be repeated like another user.

  • 👤 The first_name and last_name are edited by the created user.
  • 📓 Old contact details will be updated with new ones (read about it in our feed).

In response ⬇️, you will receive an object of the updated user:

{
  response: {
    user: {
      _id: "63480e68f4794709f802a2fa",
      login: "Oliv3r2",
      first_name: "Darcy",
      last_name: "Stevenson",
      email: "darcy.s@test.com",
      phone: "1234567890",
      created_at: "2022-10-13T13:11:04.447Z",
      updated_at: "2022-10-13T13:11:04.447Z"
    },
    id: "edit_request"
  }
}

Delete a user

~ request name: user_delete

Just like with the session closure request, to delete a user, you just need to send a request ⬆️ to the server from the desired user:

{
  request: {
    user_delete: {},
    id: "delete_request"
  }
}

❗️You can only delete the user from which you are sending this request, access to delete any other user is blocked.

If you’ve done everything right, then the server:

  • 🔒 Close all your sessions.
  • 🧹 Clean up the records about you in the database.
  • 📨 Send the status of your last activity to everyone who needs it.
  • 📓 Сlean up contact information about you (read about it in our feed).

As a result, it will return a response ⬇️ to you:

{
  response: {
    success: true,
    id: "delete_request"
  }
}

Search for users in the database

~ request name: user_search

Well, my friend is also registered here, how can I write to him?

This method will help you with this. You can send a request to the server with a partial (or full) username of the user you are looking for, and if you find such a user (or similar users), you will receive a list of them.

You can also specify:

  • 🔢 The limit of entries per return.
  • 🕐 Time of the last record update.
  • 🆔 User IDs that should not be in the list.

As a result, your request ⬆️ with all the parameters may look like this:

{
  request: {
    user_search: {
      login: "Sama",
      limit: 25,
      updated_at: {
        gt: "2022-10-13T13:11:04.447Z"
      },
      ignore_ids: [
        "63077ad836b78c3d82af0866",
        "63077ad836b78c3d82af0868"
      ]
    },
    id: "search_request"
  }
}

* You can also use the timestamp format for representing a time parameter.

And the response ⬇️ from the server will be a list of users:

{
  response: {
    users: [
      {
        _id: "64e4973ac0d3198d69c6de4b",
        login: "Samantha512"
      },
      {
        _id: "64e4972ec0d3198d69c6de48",
        login: "sama6a2"
      },
      ...
    ],
    id: "search_request"
  }
}

Conclusion

Do you want to build a powerful user database with the ability to easily manage and update it? Then use our tools 🛠, such as the SAMA Users API. Your users will be delighted with the speed, reliability, and flexibility of your product!

👀 Check out more posts on our page for fantastic improvements to your app!

Try SAMA 👇🏼

To run SAMA server locally — follow https://github.com/SAMA-Communications/sama-server. Frontend app is available at https://github.com/SAMA-Communications/sama-client

Discover, enjoy, and all feedback is welcome. We will be thankful a lot for every GitHub star, issue, or comment!

SAMA-Communications

SAMA-Communications has 5 repositories available. Follow their code on GitHub.

github.com

Chat
API
Nodejs
Messaging
Websocket

--

--

Oleksandr Chabaniuk
SAMA communications

Written by Oleksandr Chabaniuk

13 Followers
Editor for

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams