Users

As the name suggests, users are a core part of Protocol — the very reason Protocol exists is so you can have secure conversations with your users. On this page, we'll dive into the different users endpoints you can use to manage users programmatically. We'll look at how to query, create, update, and delete users.

The user model

The user model contains all the information about your users, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the user and information about when they were last active on Protocol.

Properties

Name
id
Type
string
Description
Unique identifier for the user.
Name
username
Type
string
Description
Credential for the user.
Name
password
Type
string
Description
Credential for the user.
Name
name
Type
string
Description
The name of user.
Name
avatar_url
Type
string
Description
The avatar of user.
Name
bio
Type
string
Description
The bio of user.
Name
last_active
Type
timestamp
Description
The last time when user login/active.
Name
created_at
Type
timestamp
Description
The time when user created.
Name
udpated_at
Type
timestamp
Description
The time when user update profile.
Name
status
Type
int
Description
The status of user (inactive/active/ban).

GET/users

List all users

This endpoint allows you to retrieve a paginated list of all your users. By default, a maximum of ten users are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of users returned.

Request

GET

/users

curl -G https://api.protocol.chat/users \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "status": true,
  "message": "Users Data",
  "data": [
   {
    "_id": "64dcc642991655cf02bde5b0",
    "username": "jhondoe",
    "password": "$2a$12$UaezhvOvFSSNWUpuJgUmFuEqctu2b6bJk2eWrffI17ychZ1xp/2yS",
    "name": "Jhon Doe",
    "avatar_url": "avatar.google.com",
    "bio": "Welcome",
    "last_active": 0,
    "created_at": 692233200,
    "udpated_at": 0
    },
    {
      "_id": "64de8da5db0cee40401769c6",
      // ........
    }
   ]
}

POST/users

Create a user

This endpoint allows you to add a new user to your user list in Protocol. To add a user, you must provide their Protocol username and phone number.

Required attributes

Name
username
Type
string
Description
The username for the user.
Name
phone_number
Type
string
Description
The phone number for the user.

Optional attributes

Name
avatar_url
Type
string
Description
The avatar image URL for the user.
Name
name
Type
string
Description
The user display name in the user list. By default, this is just the username.

Request

POST

/users

curl https://api.protocol.chat/users \
  -H "Authorization: Bearer {token}" \
  -d username="jhondoe" \
  -d phone_number="1-800-759-3000" \
  -d avatar_url="https://assets.protocol.chat/avatars/frank.jpg"

Response

{
  "message": "Successfully created user"
}

GET/users/:id

Retrieve a user

This endpoint allows you to retrieve a user by providing their Protocol id. Refer to the list at the top of this page to see which properties are included with user objects.

Request

GET

/users/64dcc642991655cf02bde5b0

curl https://api.protocol.chat/users/64dcc642991655cf02bde5b0 \
  -H "Authorization: Bearer {token}"

Response

{
    "_id": "64dcc642991655cf02bde5b0",
    "username": "jhondoe",
    "name": "Jhon Doe",
    "avatar_url": "avatar.google.com",
    "bio": "Welcome",
    "last_active": 0,
    "created_at": 692233200,
    "udpated_at": 0
  }

PUT/users/:id

Update a user

This endpoint allows you to perform an update on a user. Currently, the only attribute that can be updated on users is the display_name attribute which controls how a user appears in your user list in Protocol.

Optional attributes

Name
display_name
Type
string
Description
The user display name in the user list. By default, this is just the username.

Request

PUT

/users/64dcc642991655cf02bde5b0

curl -X PUT https://api.protocol.chat/users/64dcc642991655cf02bde5b0 \
  -H "Authorization: Bearer {token}" \
  -d display_name="Anderson"

Response

{
  "message": "User has been updated",
}

DELETE/users/:id

Delete a user

This endpoint allows you to delete users from your user list in Protocol.

Request

DELETE

/users/64dcc642991655cf02bde5b0

curl -X DELETE https://api.protocol.chat/users/64dcc642991655cf02bde5b0 \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "User has been deleted",
}