Page: unichat API user methods
2019-11-21 11:11
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:
- API requests password reset with
request_password_reset(email: <user_email>)
. - Serive checks the email and send instructions to user by email
- User visits the link in the received email
- Client applications is called with the URL containing
password_reset_token
in a query part of the URL. - 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
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, use
seachable_nick: false, not
null.
The password should _always_ be accompained with
currentpasswordor error
with
invalidcode` 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.