API Version: Development

User

Permissions

Requires System-Admin or ChatApi-Admin permissions.

command 'create'

Path: /rest/ops/create/

Create a new temporary/external user on the system. 'name' is the minimum required parameter.

{
    "type": "extuser",
    "values": {
        "name": "Real Name",
        "email": "Optional email address",
        "autodelete": bool default true,
        "expiretime": minutes default 15,
        "application": "optional app-spcific token, default 'none'"
    }
}

Note: By default a temporary/external user will be deleted 15 minutes after creation if unused, unless it has become active, and stays active (logged-in and in rooms.) This behaviour may be modified by either changing the expiretime to shorten or extend the time a login will be left idle before starting expiry checks, or by setting autodelete to false to prevent auto deletion entirely.

Return value:

{
    "result": "success",
    "values": {
        "contact_id": new_contact_id,
        "uname": "unique-login-name",
        "name": "Real Name",
        "email": "Optional email address",
        "data": {
            "isTmp": true,
            "datestamp": creation-stamp,
            "used": bool,
            "autodelete": bool,
            "expiretime": 15,
            "application": "none"
        }
    }
}

For example:

{
    "type": "extuser",
    "values": {
        "name": "Mr New User"
    }
}

{
    "result": "success",
    "values": {
        "contact_id": 1206,
        "uname": "VwZaI0CuCKXgfoeP7LJgDX2N5AQuhu8",
        "name": "Mr New User",
        "email": "",
        "data": {
            "isTmp": true,
            "datestamp": 1464087388780,
            "used": false,
            "autodelete": true,
            "expiretime": 15,
            "application": "none"
        }
    },
    "numrows": 1
}

command 'read'

Path: /rest/ops/read/

Query temporary/external users by specifying a 'scope' object. A missing/empty scope object returns all rows. Only one of contact_id or uname should be specified. 'columns' may optionally be specified, limiting the result to the dataset specified; subsets of the 'data' object are not filterable.

{
    "type": "extuser",
    "scope": {
        "contact_id": "contact-id",
        "uname": "unique-login-name", /* if contact_id not provided */
        "application": "may be specified as filter"
    },
    "columns": [        /* optional */
        'contact_id',
        'uname',
        'name',
        'email',
        'data'
    ]
}

The return value is of the form:

{
    "result": "success",
    "values": [
        {
            "column": "column-value",
            ...
        },
        ...
    ],
    "numrows": number-of-rows
}

For example:

{
    "type": "extuser",
    "scope": {
        "contact_id": 1206
    }
}

{
    "result": "success",
    "values": [{
        "contact_id": 1206,
        "uname": "VwZaI0CuCKXgfoeP7LJgDX2N5AQuhu8",
        "name": "Mr New User",
        "email": "",
        "data": {
            "isTmp": true,
            "datestamp": 1464087388780,
            "used": false,
            "autodelete": true,
            "expiretime": 15,
            "application": "none"
        }]
    },
    "numrows": 1
}

command 'update'

Path: /rest/ops/update/

This is a slightly mis-named call as it is better described as a 'refresh' or 'reuse' command. Rather than delete and re-create a user, this command allows an existing extuser to be refreshed so it can be re-used. The uname will be changed, invalidating the old one as if deleted, and autodelete and expiretime will be reset and must be re-specified if defaults are not wanted.

Name and email are optional and if not provided, previous values will be retained.

'Application' is optional and if not provided, previous value will be retained.

{
    "type": "extuser",
    "scope": {
        "contact_id": "contact-id",
        "uname": "unique-login-name" /* if contact_id not provided */
    },
    "values": {
        "name": "Real Name",
        "email": "Optional email address",
        "autodelete": bool default true,
        "expiretime": minutes default 15,
        "application": "app-spcific token, default unchanged"
    }
}

Return value:

{
    "result": "success",
    "values": {
        "contact_id": new_contact_id,
        "uname": "unique-login-name",
        "name": "Real Name",
        "email": "Optional email address",
        "data": {
            "isTmp": true,
            "datestamp": creation-stamp,
            "used": bool,
            "autodelete": bool,
            "expiretime": 15,
            "application": "none"
        }
    }
}

For example:

{
    "type": "extuser",
    "scope": {
        "contact_id": 1206,
        "application": "myApp"
    }
}

{
    "result": "success",
    "values": {
        "contact_id": 1206,
        "uname": "RGOGbl1GaHFAHli0V0Qa7gQIklww6vc",
        "name": "Mr New User",
        "email": "",
        "data": {
            "isTmp": true,
            "datestamp": 1464088961272,
            "used": false,
            "autodelete": true,
            "expiretime": 15,
            "application": "myApp"
        }
    },
    "numrows": 1
}

command 'delete'

Path: /rest/ops/delete/

Using either contact_id or uname of a user, delete the record of the external/temporary user, and disconnect them from all rooms. A logoff will be enforced within a few seconds where necessary.

{
    "type": "extuser",
    "scope": {
        "contact_id": "contact-id",
        "uname": "unique-login-name" /* if contact_id not provided */
    }
}

For example:

{
    "type": "extuser",
    "scope": {
        "uname": "RGOGbl1GaHFAHli0V0Qa7gQIklww6vc"
    }
}

{
        "result": "success",
        "numrows": 1
}