Contacts

Contacts are represented by <contact_record>:

{
  "contact": {
    "blocked_at": null,         // not null if blocked
    "confirmed_at": null,       // not null if confirmed
    "created_at": "2018-10-14 23:10:10 UTC",
    "updated_at": "2018-10-14 23:10:10 UTC",
    "user": {
      "id": 517,
      "nick": "test_user_2"
    }
  }

Adding contact

add_contact(email: <opt_string>,nick: <opt_string>,user_id: <opt_long>) 
    -> {contact: <contact_record>}

Only one of email, user_id or nick must be presented.

On success, return contact record. If no contact found returns code: not_found error.

The just added contact is in "unconfirmed state". It will become confirmed when other party will confirm it by adding it to contacts.

Other party will see the nick of the party which has called add_contact first and therefore could use it to add it back. When both perties have added each other, the contact state will turn to confirmed.

Unconfirmed contacts should be shown differently and could have different notifications policy from confirmed ones.

Another way of adding contact is creating a provate chat to it. It will add the contact automatically.

Deleting contact

delete_contact(email: <opt_string>,nick: <opt_string>,user_id: <opt_long>)

Only one of email, user_id or nick must be presented.

On success, return true. If no contact found returns code: not_found error.

List contacts

get_contacts() -> { contacts: [<contact_reocrd>,...] }

deprecated form also works:

contacts() -> { contacts: [<contact_reocrd>,...] }

but we ask to remove it from code, as it will be removed soon.

Get last activity time

get_last_active_at(user_id: <long>) -> { last_active_at: <time_string> }

returns last known activity time of the user, or null of current user has no access to this information.

Searching known users

Known usrers are these to whom currently logged in user has at least one group in common, e.g. where both are participants.

To seacrh for a nick knowning it part (not ncecessarily the beginning):

search_knwon(nick_part: <string>) 
    -> { users: [<user_record>,..], overflow: <bool> }

nick_part should not be too short (right now the limit is at least 5 characters). invalid_parameter api error is reported if it is too short.

  • users: array of chat user record, possibly empty
  • overflow: true means that there are more matches that are presented. Narrow the search.

It is possible to search for nicks with at least 5 first characters:

search_user(nick_prefix: <string>) 
    -> { users: [<user_record>,...], overflow:<boolean> }
  • users: array of chat user record, possibly empty
  • overflow: true means that there are more matches that are presented. Narrow the search.