HTTP REST Unichat Endpoint


Allows access to every unichat API method with a single HTTP JSON call on

POST https://chat.universa.io/api/<method_name>

Where <method_name> is a name of the unichat API method to call, and args data parameter should contain any method arguments if any.

Use Content-Type: application/json and the JSON encoding for parameters and returned value.

On success, it returns status: 'OK' and whatever data API method returned:

{
    status: 'OK',
    // any data API method has returned
}

On error, the 400 result code will be returned and the data will contain following structure:

{status: "error", error_code: error_code, error_text: error_text}

The error_code is a constant per-error string value that always same and should be used by caller to react to the error. error_text instead is a varying description that is intended only to be read by human (user or developer) but must not be used to interpret the error.

Specifying domain token

The application domain token should be specified in the request header APP_DOMAIN_TOKEN. The "test_token1" could be used for testing.

Authenticating user

Most API methods, as explained in unichat API, requires user authenticaion. When loggin in with some login method, callint party gets the extended chat user record, which includes auth_token fields.

The application must then set the request header USER_AUTH_TOKEN to this value with each request that needs user authentication. Please note that you should explicitely use this request header field, do not mistake it with other authentication headers. Always use USER_AUTH_TOKEN in api calls.

Logging out

Just clear the saved auth_token value and do not add the header. Do not pass this header with empty or improper value as it will cause error.

Receiving events

Events are available with SSE, see SSE server events article for details.

To subscribe to SSE, the client has to obtain the SSE authenitcation code using create_sse_auth_code() call, see unichat API. With this code, subscribe to the SSE events with the following URL: https://chat.universa.io/api/events?auth_code=<code>, for example:

var evtSource = new EventSource("https://chat.universa.io/api/events?auth_code="+sse_token, { withCredentials: true } );
evtSource.addEventListener("unichat_notification", function(e) {
    console.log("got notification: ");
    console.log(e.data)
},false);

This code receives unichat API notifications in unichat_notification events. This is generally all the client software need.

Additionaly, application might find handy to process other SSE events the endpoint provides. Notice that to receive these special SSE events one need to add separate event listener, the listener in the sample above receives only unichat notifications.

event_source_ready event

This event is send once per established connection, what means that after this event applicaiton will receive events stream.

ping event

This event is sent periodically by the service to check the connection is not closed or lost. Application does not need to process it in any way.