User methods

Chat User record

Is returned in may chat API objects. The own record has more fields as most user information is not disclosed to others.

{
  "user": {
    "id": 290,
    "nick": "test_user_1",
    "is_online":false,
    "status":nil,
    // private fields:
    "email": "[email protected]", 
    "searchable_nick": true,
    "confirmed_at": "2018-10-14T22:40:55Z"   
     "auth_token": "ZWuzrbsnXivG6J1wrhagWEhDDR_kfigGzIOCRbyLNA_ZiYBDepngE2Xv2",
     "avatar": {"full":<string_url>,"small":<string=_url>} // or null
  }

fields marked as private are only shown to the user in me call. The rest are public fields visible to anybody. If confirmed_at is null, the email confirmation should be passed as soon as possible. Avatar, if present, has always 2 images: full and probably reduced, could be the same if original image was too small.

You can use is_online attribute to check whether user is online or offline.

Available status attribute values: NULL, "away", "busy" and "do_not_disturb"

Registration

register(email:<string>,password:<string>) 
    -> {user: <chat user record>}

If email is invalid or already taken, returns error with code: 'invalid_email'. Any other registration error return code registration_error wil a text contained detailed error description. Also too weak password may cause errors.

It user is registered successfully, the chat user record is returned and an email with confirmation instruction is sent. User must be advised to confirm it as soon as possible as most methods required confirmed email.

Note that after confirming email user will be redirected to the root URL specified in the unichat application domain.

Resending confirmation instructions

In the case user has not received it, it is allowed to send instructions, not too often.

resend_confirmation(email: <email>) -> {}

returns empty hash on success. Could return error code: 'please_wait' if reconfirmation was sent recently.

Reset password

It is possible to reset the password using the email. The procedure contains following steps:

1. API requests password reset with request_password_reset(email: <user_email>).
2. Serive checks the email and send instructions to user by email
3. User visits the link in the received email
4. Client applications is called with the URL containing password_reset_token in a query part of the URL.
5. Client application extracts the link and calls reset_password(token:, new_password:)

Detailed step description follows.

Requesting password reset

request_password_reset(email: <strgin> ) -> {}

Email should be a valid email of existing account of the error will be reported.

Nothe the password reset can't be requested too often or the rate_exceeded error will be returned. The error text will contain time limit for the next password reset request call.

Password reset callback

The application can set the password reset callback separately from its root URL in the unichat application domain settings page. If it is not set, then the root URL will be used.

The reset callback will have query part containing password_reset_token parameter which should be extracted. For example, the callback can be:

https://acme.com/reset_password?password_reset_token=ulkjn5g4rkjbhweh67

in this example the password reset callback in the control panel is set to https://acme.com/reset_password, and the token is ulkjn5g4rkjbhweh67

Note that pasword reset callback URL presented in the unichat application domain control panel must not contain any query part.

Resetting the password

The application extracts the passwort reset token from the callback as described above. Havin this token it should ask user to enter and confirm new password, then call API to reset it:

reset_password(token: <string>,password: <string>) -> {}

After this, the client software can login as usual using the new password.

Logging in

Password login

login(email: <string>,password:<string>) -> { user: <chat_user_record> }

Typical error codes are auth_failed and please_wait if called too frequently.

Token login

It is possible to login also with the auth_token returend in own chat user record:

login(auth_token:<auth_token_string>) -> { user: <chat_user_record> }

The auth_token is returned in own iser record returned by login() and me() calls.

Logging out

If for some user application needs to leg out current user (logging in required)

logout() -> {}

Update self

Requires logged in user.

update_me(nick: <opt_string>,password: <opt_string>,
searchable_nick:<opt_boolean>,
          current_password: <opt_string>,
          avatar: <data_url>)
    -> { user: <user_record> }

Any parameter may be missing. Only and all fields presented in arguments and not null willbe changed. Any number of fields could be changed with the single call. If a null value will be passed or field will not be listed in arguments, it won't be changed.

For example, to set searchable_nick' to false, useseachable_nick: false, not null.

The password should _always_ be accompained withcurrentpasswordor error withinvalidcode` password will be returned.

Typical errors are: invalid_params if a not allowed field presented and invalid_nick if the new nick is bad or in use. If the error occurs, no data will be changed. Nick limitations as for now are:

• nick must start with a letter
• nick can not have spaces before or after (will be stripped if any)
• nick should be at least 5 characters long
• nick should not contain more than one consequent spaces

Please note that
Successful profile update sends notification

   {event:"changed",object_type:"user",object:{<user_record>}

to all relevant users including self, e.g. to all users that have groups in common with this one (and thus may require redraw on clients).

User status

Requires logged in user.

update_status(status:<string>)

Possible invalid_user_status error if the value is not NULL, "away", "busy", "do_not_disturb" or "invisible".

If the status is "invisible", then the user has information that he is offline and notifications about this user's activity in the chat are not transmitted.

Avatar format

The avatar optional parameter described above must be a data url string, containig all the fields, e.g. data:<mediatype>;base64,<data_base64>. No part could be omitted. mediatype should be image/..., we support png and jpeg for sure and many other formats that we do not reccomend to use.

It should not be too big, we will impose restrictions in near future, the avatar should be below 2M anyway.

Get self

Requires logged in user.

me() -> { user: <user_record> }

Get the SSE authorization code

This code is only needed to get SSE events, which could be used with HTTP REST endpoint. With Websock endpoint it is useless as events are already transmitted via same connection with API calls.

To create/get existing code:

api_create_sse_auth_code() -> { code: <string_code> }

The code then could be used with http rest unichat endpoint to subscribe to SSE events.

Delete SSE authorization code

When the clietn software does not want to be able to receive SSE events it could revoke the code by calling:

api_delete_sse_auth_code() -> {}

Push notifications

A push notification is a message that pops up on a mobile device. Push notifications provide convenience and value to app users. For example, users can receive new messages right on their lock screen

Add devise token

For the service to work, you must send the device token. Use this method when the user logs in.

devise_token(token: <string>, notification_service: <string>) -> { user_devise: <user_devise_record> }

Available values for the notification service:

• ios_app - use for the Apple mobile devises.

User must be logged in.

Typical errors are: invalid_params if a not allowed field presented and invalid notification_service if the notification service is bad or in use. If the error occurs, no data will be changed.

Remove devise token

To remove a token so that the device stops receiving notifications, use:

remove_devise_token(token: <string>, notification_service: <string>) -> { result: true }

User must be logged in. Use this method before the user logs out.

Typical errors are: invalid_params if a not allowed field presented and invalid notification_service if the notification service is bad or in use. If the error occurs, no data will be changed.

Get user

Use it to refresh other user public data. As for now, all this information is already included in contacts/subscriptions.

get_user(user_id:<long>) -> { user: <user_record> }

This method does not require authentication.