Skip to content

Latest commit

 

History

History
3901 lines (2686 loc) · 106 KB

api.md

File metadata and controls

3901 lines (2686 loc) · 106 KB

Ninchat API Reference

This document describes version 2 of the open Ninchat API. It will be extended over time, without breaking conforming client applications. However, specific functionality that is available only to a limited set of users may be changed or disabled in controlled manner. If a new, backward-incompatible API version is released, it will be accessible using new network endpoints.

Copyright © Somia Reality Oy. All rights reserved.

Contents

Associated documents

Changes

Version 2

Backward-incompatible changes from version 1:

  • WebSocket clients must be prepared to handle text and binary frames. (Previously only text frames were sent to clients.)

  • The initial value of the action_id parameter must be 1 (instead of any positive integer), and it must be reset to 1 when a new session is created and there are no action retries queued from previous sessions. (See the Interface section.)

  • The ninchat.com/info message type is split into multiple ninchat.com/info/* types.

  • Message content must consist of at least one part. (See the send_message action.)

  • The message_received event might not include the message content.

  • The message_time parameter type changed from integer to float. (See the message_received event.)

  • The search_results event's "users" and "channels" objects were modified to accommodate more parameters.

  • The session_created event might not include the session_host parameter.

  • The WebSocket-Protocol header is now unversioned; the API version is included in the WebSocket endpoint URL.

See the commit log for incremental changes.

Interface

Clients send actions to the server, which sends events to clients. Action and event parameter values are represented as JSON types.

Most actions support or require the action_id parameter, which may be used to detect success or failure of the action. The action reference indicates the exceptions when it is not supported. When the client receives (at least) one event with the corresponding action_id, the action has succeeded, unless the event was error. The values should be ascending integers, starting at 1, over the lifetime of the client instance's state (even across sessions). If no response event is received, the client may retry the action (e.g. after reconnecting) with the same action_id value.

Most actions support the puppet_id parameter. The action reference indicates the exceptions when it is not supported. See the Ninchat Puppets document for more information.

In addition to the parameters listed below, most events contain the monotonically ascending event_id integer parameter (starting at 1). Such events are buffered by the server until they are acknowledged by the client, so that they can be retransmitted if the network connection is lost during a session. (Events without an event_id are connection-specific.) The acknowledgement procedure is transport-specific (see Streaming Transports). Failure to acknowledge events results in session buffer overflow.

Instead of the reply events listed below, any action may cause an error event.

Undefined action, event and parameter names must not be used in communication and you should not rely on their nonexistence. Enumerations (e.g. access_type, error_type and identity_type) may gain new options, so clients should be able to cope with events with unknown values for such parameters.

When a newer API version is available, a client accessing an old API endpoint may receive an unsolicited error event with error_type set to deprecated. (It's purely informational, and doesn't necessarily imply immediate service degradation.)

Actions

Action types

create_session

  • user_id : string (optional)
  • user_auth : string (optional)
  • user_attrs : object (optional)
  • user_settings : object (optional)
  • user_metadata : object (optional)
  • identity_type : string (optional)
  • identity_name : string (optional)
  • identity_auth : string (optional)
  • identity_type_new : string (optional)
  • identity_name_new : string (optional)
  • identity_auth_new : string (optional)
  • identity_attrs : object (optional)
  • access_key : string (optional)
  • master_key_type : string (optional)
  • master_sign : string (optional)
  • puppet_attrs : object (optional)
  • message_types : string array

Exceptions:

Reply event: session_created

There are five modes of operation:

  1. If user_id and user_auth are specified, a new session for an existing user is created.

  2. If identity_type, identity_name and identity_auth are specified, a new session for an existing user is created. The identity type and name must be verified for a user.

    If identity_type is set to "facebook", identity_name is set to a Facebook user id and identity_auth contains a matching signed request, a session is created for the existing Ninchat user with the associated Facebook identity.

  3. If access_key is specified, a new session is created for the user determined by the access key.

  4. If user_id and master_sign are specified, a new session for an existing user is created. master_key_type specifies the signature type (defaults to "ninchat"). An access_expired error type is returned if the signature has expired. See Action signatures.

  5. Otherwise a new user is created.

    The user will be a guest unless the guest user attribute is explicitly set as false.

    identity_type_new, identity_name_new, identity_auth_new and/or identity_attrs may be used to create an identity for the user.

    If identity_type_new is set to "facebook", identity_name_new is set to a Facebook user id and identity_auth_new contains a matching signed request from the Facebook SDK, the Facebook identity is associated with the created Ninchat user.

Accepted message types are specified as a list of strings to compare against incoming message types. If a string ends with an asterisk (*), the substring preceding the asterisk is used to match prefixes instead of whole strings. The "*" string accepts all messages. An empty array rejects all messages.

If the authentication token or access key is invalid or has been revoked, the error type will be access_denied. This condition is permanent: create_session won't succeed later with the same parameters.

resume_session

Exceptions:

  • puppet_id is not supported

Receive or acknowledge events of an existing session. See Streaming Transports for details.

update_session

  • session_idle : boolean (optional)
  • channel_id : string (optional)
  • user_id : string (optional)
  • message_id : string (optional)

Exceptions:

  • puppet_id is not supported.

Client-assisted idle user and unread message tracking.

close_session

Exceptions:

  • puppet_id is not supported.

See Streaming Transports for details.

create_user

  • action_id : integer
  • user_attrs : string (optional)
  • user_settings : string (optional)
  • puppet_attrs : object (optional)

Reply event: user_created

Like create_session, but doesn't create a session. Useful with the sessionless API.

If called by an existing user (e.g. there is a session, or the caller is authenticated), the created user will become a puppet of the calling (master) user. The user_created event won't include the user_auth parameter; instead, the puppet user may be logged in and manipulated using the master key mechanism.

If called without a session or authentication credentials, a standalone user is created. The user_created event will include the user_auth parameter.

The created user will be a guest unless the guest user attribute is explicitly set as false.

describe_user

  • action_id : integer
  • user_id : string (optional)

Reply event: user_found

update_user

  • action_id : integer
  • user_attrs : object (optional)
  • user_settings : object (optional)
  • payload_attrs : string array (optional)

Reply event: user_updated

The iconurl attribute may be set by uploading image data in the payload: the index of the payload frame is determined by the index of the "icon" string in the payload_attrs array. WebSocket example:

First frame:

{
  "action":        "update_user",
  "action_id":     3,
  "payload_attrs": ["icon"],
  "frames":        1
}

Second frame:

\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x01\x03
\x00\x00\x00%\xdbV\xca\x00\x00\x00\x03PLTE\x93c+\xbaC\xfaW\x00\x00\x00\nIDA
T\x08\xd7c`\x00\x00\x00\x02\x00\x01\xe2!\xbc3\x00\x00\x00\x00IEND\xaeB`\x82

If the uploaded image data cannot be converted to an icon, the file_not_supported error is returned.

delete_user

  • action_id : integer
  • user_auth : string (optional)

Reply event: user_deleted

The user_auth token must be repeated here to avoid accidents and mischief, except for guest users, or when this action is invoked with puppet_id.

create_identity

  • action_id : integer
  • identity_type : string
  • identity_name : string
  • identity_attrs : object (optional)
  • identity_auth_new : string (optional)

Reply event: identity_created

Associates an identity with the session user. The identity is pending verification until futher action is taken.

Identity types:

  • "email" sends an email with a verification link. identity_name specifies the email address.
  • "facebook" creates an identity to be used for authentication with the help of the Facebook SDK. See create_session.
  • "gcm" registers a GCM id. identity_name specifies the GCM registration id.
  • "apns" registers an APNs id. identity_name specifies the APNs device id.

A secret authentication token (password) is associated with the identity if identity_auth_new is specified.

create_identity_with_auth_reset_access

  • action_id : integer
  • identity_type : string
  • identity_name : string
  • identity_attrs : object (optional)

Reply event: identity_created

Combines the create_identity and request_identity_auth_reset_access actions: password is not set by the action, but via a link received in an email. The identity will be verified when a password is set (via the link).

request_identity_verify_access

  • action_id : integer (optional)
  • identity_type : string
  • identity_name : string

Exceptions:

Reply event: access_created (without access_key)

Resend an email identity verification link if the identity is still pending verification. (In other words, identity_type must be "email" for now.)

verify_identity

  • action_id : integer (optional)
  • access_key : string
  • identity_accept : boolean

Exceptions:

Reply event: identity_updated

Accepts or rejects a pending user identity.

describe_identity

  • action_id : integer
  • identity_type : string
  • identity_name : string

Reply event: identity_found

update_identity

  • action_id : integer
  • identity_type : string
  • identity_name : string
  • identity_attrs : object

Reply event: identity_updated

update_identity_auth

  • action_id : integer
  • identity_type : string
  • identity_name : string
  • identity_auth : string (optional)
  • identity_auth_new : string (optional)

Reply event: identity_updated

Sets or changes the secret authentication token (password).

identity_auth (the old authentication token) must be specified if the identity already has one. It will be replaced with identity_auth_new. If identity_auth_new is not specified, the password will be removed.

request_identity_auth_reset_access

  • action_id : integer (optional)
  • identity_type : string
  • identity_name : string

Exceptions:

Reply event: access_created (without access_key)

Create and send an access key to the specified email address if it's a verified email identity. (In other words, identity_type must be "email" for now.) The access key may be used to reset the password associated with the identity.

reset_identity_auth

  • access_key : string
  • identity_auth_new : string

Exceptions:

Reply event: identity_updated

Resets the authentication token (password) associated with an identity (specified by the access_key).

delete_identity

  • action_id : integer
  • identity_type : string
  • identity_name : string
  • identity_auth : string (optional)

Reply event: identity_deleted

identity_auth must be specified if the identity has one.

update_dialogue

  • action_id : integer
  • user_id : string
  • member_attrs : object (optional)
  • dialogue_status : string (optional)

Reply event: dialogue_updated

Update your own member attributes in your dialogue with user_id, or your perceived status of the dialogue. Valid values for dialogue_status are "visible" (not hidden, not highlighted) and "hidden".

create_channel

  • action_id : integer
  • channel_attrs : object (optional)
  • realm_id : string (optional)

Reply event: channel_joined

If realm_id is specified, the realm owner will become the channel owner. Otherwise the session user will become the owner.

describe_channel

  • action_id : integer
  • channel_id : string

Reply event: channel_found

update_channel

  • action_id : integer
  • channel_id : string
  • channel_attrs : object

Reply event: channel_updated

delete_channel

  • action_id : integer
  • channel_id : string

Reply event: channel_deleted

The channel must be suspended before it can be deleted.

follow_channel

  • action_id : integer
  • channel_id : string
  • master_key_type : string (optional)
  • master_sign : string (optional)

Reply event: channel_found

Like join_channel, but:

  • May only be used with channels with the disclosed_since and followable attributes set, and without the private attribute set. Note: channels in realms may be followable even when the public attribute is not set!
  • The user won't appear on the channel's member list.
  • The user won't be able to send messages to the channel.
  • Only the session which invoked this action will receive message_received events for this channel.
  • The user will stop following the channel when the session is closed.

join_channel

  • action_id : integer
  • channel_id : string (optional)
  • access_key : string (optional)
  • master_key_type : string (optional)
  • master_sign : string (optional)
  • member_attrs : object (optional)

Reply events: channel_joined and realm_joined (if applicable)

There are three modes of operation:

  1. channel_id specifies the channel to be joined. It must not be in a realm or it must be in one of the user's realms.

  2. access_key grants permission to join a channel in a realm. The access key configuration determines the channel to be joined. The realm_joined event indicates that the user was granted access to the channel's realm in addition to the channel (depending on the access key configuration).

  3. master_sign grants permission to join the channel. master_key_type specifies the signature type (defaults to "ninchat"). See Action signatures.

member_attrs can only be specified in conjunction with master_sign, when master_key_type is "ninchat" (see Ninchat Master Keys). It can only be used to disable the "silenced" member attribute, when the channel has "autosilence" attribute enabled.

part_channel

  • action_id : integer
  • channel_id : string

Reply event: channel_parted

If the parting user was the last member and the channel is not associated with an audience queue, the channel will be deleted immediately.

If the parting user was the last member of an audience channel, the channel will be suspened. The channel will persit without members until delete_channel is called, or it is deleted automatically according to a schedule.

create_realm

  • action_id : integer
  • realm_attrs : object (optional)
  • realm_settings : object (optional)
  • channel_attrs : object (optional)

Reply events: realm_joined and channel_joined (if applicable)

Creates a realm, and an optional initial channel if channel_attrs is defined. The session user will become the owner of both.

describe_realm

  • action_id : integer
  • realm_id : string

Reply event: realm_found

describe_realm_queues

  • action_id : integer
  • realm_id : string
  • queue_ids : string array (optional)
  • track_stage : string (optional)
  • track_metadata : object (optional)

Reply event: realm_queues_found

Describe some or all audience queues of a realm. The session will continue to receive additional queue_updated events if there are changes to the queues. The updates will cease after an audience is requested through one of the queues.

If specified, queue_ids indicates a subset of the realm's queues which the user is interested in. Unknown queue ids are silently ignored. (The user may still receive spurious queue_updated events concerning the realm's other queues.)

update_realm

  • action_id : integer
  • realm_id : string
  • realm_attrs : object (optional)
  • realm_settings : object (optional)

Reply event: realm_updated

delete_realm

  • action_id : integer
  • realm_id : string

Reply event: realm_deleted

create_queue

  • action_id : integer
  • realm_id : string
  • queue_attrs : object

Reply event: queue_created

Create a new audience queue. Caller must be a realm operator.

update_queue

  • action_id : integer
  • queue_id : string
  • queue_attrs : object (optional)
  • queue_settings : object (optional)

Reply event: queue_updated

Update audience queue attributes and/or settings. Caller must be a realm operator.

delete_queue

  • action_id : integer
  • queue_id : string

Reply event: queue_deleted

Delete an audience queue. Caller must be a realm operator.

get_queue_stats

  • action_id : integer
  • queue_id : string
  • stats_hour : string (optional)
  • stats_length : integer

Reply events: queue_stats_contents

stats_hour specifies the start of the time range as "YYYYMMDDHH"; if omitted, the range ends at the latest occurrence of available data. stats_length specifies the number of hours to load. No more than one month of data may be requested at a time (does NOT need to be aligned to start or end of month).

describe_queue

  • action_id : integer
  • queue_id : string

Reply event: queue_found

Describe an audience queue.

create_audience

  • action_id : integer
  • queue_id : string
  • user_id : string
  • channel_attrs : object (optional)

Reply event: channel_created

Create an audience channel. Caller must be a member of the queue.

Initial agent user must be specified via the user_id parameter. The target user must be a member of the queue's realm.

Attributes disclosed_since and private are set, and upload and video are inherited from the queue, unless overridden.

request_audience

  • action_id : integer
  • queue_id : string
  • audience_metadata : object (optional)

Reply event: audience_enqueued

Go to the end of the queue.

The audience_metadata object may contain arbitrary properties, but the "secure" property is special: if set to a string value, it will be decrypted using the queue owner's master key, and the contents will be set as the value of the property. Other value types for "secure" property are rejected. A permission_expired error type is returned if the encrypted metadata has expired. See Secure metadata.

When the audience is accepted, the user will automatically join a channel or a dialogue will start, depending on queue configuration. audience_id and queue_id will be set either as channel attributes, or as dialogue member attributes for the session user.

accept_audience

  • action_id : integer
  • queue_id : string
  • audience_id : string (optional)

Reply event: channel_joined or dialogue_updated

Take the next user or the specific audience (if audience_id is specified) from the queue. Caller must be a queue member.

Either a channel or a dialogue will be created, depending on queue configuration. The channel attributes or the accepted user's dialogue membership attributes will contain audience_id and queue_id.

transfer_audience

  • action_id : integer
  • audience_id : string
  • queue_id : string

Reply event: channel_parted

End a previously accepted audience, and enqueue the customer to another queue.

add_member

  • action_id : integer
  • realm_id : string (optional)
  • queue_id : string (optional)
  • channel_id : string (optional)
  • user_id : string
  • member_attrs : object (optional)

Reply event: realm_member_joined, queue_member_joined or channel_member_joined

Causes a specific user to join a realm, an audience queue, or an audience channel. Caller must be a realm operator.

Members can't be added to arbitrary channels, only audience channels. Only agent users can be added: the operator and/or moderator membership attribute must be set. The target user must be a member of the channel's realm.

update_member

  • action_id : integer
  • channel_id : string (optional)
  • realm_id : string (optional)
  • user_id : string
  • member_attrs : object
  • interval_end : float (optional)

Reply event: channel_member_updated or realm_member_updated

Sets or clears a channel or realm membership attributes for a user.

If interval_end is specified with a channel membership attribute, the set attribute will be automatically unset at that time. (An update_member call with an interval can set only one attribute at a time.)

remove_member

  • action_id : integer
  • channel_id : string (optional)
  • realm_id : string (optional)
  • queue_id : string (optional)
  • user_id : string

Reply event: channel_member_parted, realm_member_parted or queue_member_parted

Kicks a user out of a channel, a realm or an audience queue. Caller must be the target user, a channel operator or moderator (if removing from a channel) or a realm operator (if removing from a realm or a queue).

send_message

  • action_id : integer (optional)
  • channel_id : string (optional)
  • user_id : string (optional)
  • identity_type : string (optional)
  • identity_name : string (optional)
  • message_type : string
  • message_recipient_ids : string array (optional)
  • message_fold : boolean (optional)
  • message_ttl : float (optional)

Reply event: message_received or none (if action_id is not specified)

Message content is provided in the payload (see Streaming Transports). The content may not be empty: it must contain one or more parts (but the individual parts may be zero-length).

Exactly one of channel_id, user_id and identity_name must be specified. user_id specifies a private conversation party. identity_type and identity_name specify a private conversation party without an established user account.

If message_ttl is specified, restrictions are placed on message delivery: the message may not be stored in the channel/dialogue history and messages may be dropped by unresponsive sessions. message_ttl specifies the minimum time in seconds to buffer the message (which should be the upper limit for the usefulness of the content). Sending such a message to an identity doesn't make sense.

update_message

  • action_id : integer
  • channel_id : string
  • message_id : string
  • message_hidden : boolean

Reply event: message_updated

Available for channel operators and moderators. Affects a single message on the channel.

update_user_messages

  • action_id : integer
  • channel_id : string
  • message_user_id : string
  • message_id : string (optional)
  • interval_end : float (optional)
  • message_hidden : boolean

Reply event: message_updated

Available for channel operators and moderators. Affects all messages up to and including message_id which have been sent by message_user_id to the channel. interval_end may be used instead of message_id to specify the (inclusive) end of time range.

load_history

  • action_id : integer
  • channel_id : string (optional)
  • user_id : string (optional)
  • message_types : string array (optional)
  • message_id : string (optional)
  • message_fold : boolean (optional)
  • history_length : integer (optional)
  • history_order : integer (optional)
  • filter_property : string
  • filter_substring : string

Reply events: history_results and message_received multiple times (with history_length set)

Exactly one of channel_id and user_id must be specified. user_id specifies a private conversation party.

message_types defaults to the value passed to create_session.

message_id makes it possible to fetch additional messages if you already have some. It specifies the exclusive first or last message identifier (depending on the history_order parameter). The latest messages are returned by default. Empty string indicates the beginning of history.

If message_fold is set, only folded messages are returned.

The meaning of history_length is as follows:

  1. In the load_history action it specifies the number of requested messages.
  2. In the history_results event it specifies the number of available messages.
  3. In the message_received event it specifies the number of remaining messages.

history_order specifies the order in which the messages will be received. When used in combination with message_id, its value also determines if we are fetching older or newer messages:

  • -1 requests newer messages first (descending). message_id specifies the exclusive end of range. This is the default.
  • 1 requests older messages first (ascending). message_id specifies the exclusive start of range.

If filter_property and filter_substring are specified, only messages which contain the filter_substring in the value of their filter_property are returned (if supported for the message type). message_types should contain only supported message types (see Message Types); other messages are ignored. history_length specifies the number of returned messages.

discard_history

  • action_id : integer (optional)
  • user_id : string
  • message_id : string

Reply event: history_discarded (without history_length set) or none (if action_id is not specified)

user_id specifies a private conversation party. message_id specifies the latest message to be discarded.

create_access

  • action_id : integer
  • access_type : string
  • channel_id : string (optional)
  • channel_unsilence : boolean (optional)
  • realm_member : boolean (optional)
  • user_id : string (optional)
  • user_attrs : object (optional)
  • user_settings : object (optional)
  • member_metadata : object (optional)

Reply event: access_created

Creates an access key for use with create_session or join_channel.

Access types:

  • "session" keys may be used in create_session actions.
  • "channel" keys may be used in a single join_channel action. If channel_unsilence is true, the invited user will not be silenced even if the channel has the autosilence attribute set. If realm_member is true, the invited user will also join the realm of the channel (if any). If user_id is specified, the invite can only be used by that user, and an info message is sent to that user (see Message types).
  • "audience" keys may be used in create_session actions. An audience channel must be specified via the channel_id parameter. A customer user account is created; user_attrs, user_settings and member_metadata are supported. The access key may be used multiple times, each time logging in the same user. The lifetime of the access key and the user account depend on the audience's lifetime.

The member_metadata object can be used to supply audience channel membership metadata. The trustworthiness of the metadata can be indicated via its placement: placing it at the top-level means that it is user-supplied information; placing it inside the "secure" object means that the information can be relied on by the agent users. For this action, the "secure" property must not be encrypted. (The placement convention is intended to be analoguous with metadata supplied via request_audience action: top-level metadata may originate from the customer's browser, but "secure" metadata can't be fabricated by the customer.)

send_access

  • action_id : integer
  • access_key : string (optional)
  • user_id : string (optional)
  • identity_type : string (optional)
  • identity_name : string (optional)

Reply event: access_found

Send a pre-created channel access key to a user (= invite). There are three modes of operation:

  1. If access_key and user_id are specified, a ninchat.com/info/* message is sent to the user in a dialogue.
  2. If access_key, identity_type and identity_name are specified, an email is sent. (In other words, identity_type must be "email" for now.)
  3. If identity_type and identity_name are specified without access_key, the (undisclosed) access key associated with the user's identity is used, if any. (This is the verification-link-resend feature.)

describe_access

  • action_id : integer (optional)
  • access_key : string

Exceptions:

Reply event: access_found

describe_master_keys

  • action_id : integer
  • realm_id : string (optional)

Reply event: master_keys_found

describe_master (deprecated)

  • action_id : integer

Reply event: master_found

This action has been superseded by describe_master_keys.

create_master_key

  • action_id : integer
  • realm_id : string (optional)
  • master_key_type : string (optional)
  • master_key_id : string (optional)

Reply event: master_key_created

If realm_id is not specified, the created key can be used with any resource owned by the creator (to the extent supported by the API). In particular, puppet users can be created and controlled with such keys.

If realm_id is specified, the created key can only be used with resources associated with that realm (e.g. channels and audience metadata). Such keys can be created and deleted by realm operators.

If master_key_type is "ninchat" or left unspecified, an id and a secret key are generated automatically.

If master_key_type is "jwt", master_key_id must be specified, and the key material must be provided in the payload.

delete_master_key

  • action_id : integer
  • realm_id : string (optional)
  • master_key_type : string (optional)
  • master_key_id : string
  • master_key_secret : string (optional)
  • user_auth : string (optional)

Reply event: master_key_deleted

realm_id must be specified if the key is associated with a realm.

If the key is not associated with a realm (= it's a personal key), either master_key_secret or user_auth must be specified for extra safety.

master_key_type defaults to "ninchat".

send_file

  • action_id : integer
  • file_attrs : object
  • user_id : string (optional)
  • channel_id : string (optional)

Reply event: message_received

File contents are uploaded in the first payload part. A ninchat.com/file message is sent to the specified user or channel.

describe_file

  • action_id : integer
  • file_id : string

Reply event: file_found

get_transcript

  • action_id : integer
  • channel_id : string (optional)
  • dialogue_id : string array (optional)
  • audience_id : string (optional)
  • interval_begin : float (optional)
  • interval_end : float (optional)
  • message_id : string (optional)

Reply event: transcript_contents

Dump the "ninchat.com/*" messages sent on a channel, in a dialogue, or during an audience. dialogue_id holds a pair of user ids (the order doesn't matter).

Specifying a time interval may make sense when targetting a long-lived channel. By default the interval is the whole history.

There is an unspecified technical limit on the number of messages returned at once. message_id may be used to get more messages if an earlier call didn't return everything.

delete_transcript

  • action_id : integer
  • channel_id : string (optional)
  • dialogue_id : string array (optional)
  • audience_id : string (optional)

Reply event: transcript_deleted

describe_queue_transcripts

  • action_id : integer
  • queue_id : string
  • interval_begin : float
  • interval_end : float (optional)
  • interval_ongoing : boolean (optional)

Reply event: queue_transcripts_found

List all dialogues which have started from the specified audience queue and completed during the specified interval. The interval may be open-ended, but by default it will only return time slots which have already ended. The interval_ongoing parameter can be used to include unfinished transcripts of the ongoing time slot.

delete_queue_transcripts

  • action_id : integer
  • queue_id : string
  • interval_begin : float
  • interval_end : float

Reply event: queue_transcripts_deleted

Discard all dialogues which have started from the specified audience queue and completed during the specified interval. The interval length must not exceed one month.

create_tag

  • action_id : integer
  • realm_id : string
  • tag_attrs : object

Reply event: tag_created

describe_tag

  • action_id : integer
  • tag_id : string

Reply event: tag_found

describe_tags

  • action_id : integer
  • realm_id : string (optional)
  • tag_id : string (optional)
  • tag_depth : integer (optional)

Reply event: tags_found

Either realm_id or tag_id must be specified. If tag_depth is specified, it must be between 1 and 10 (inclusive).

update_tag

  • action_id : integer
  • tag_id : string
  • tag_attrs : object

Reply event: tag_updated

delete_tag

  • action_id : integer
  • tag_id : string

Reply event: tag_deleted

begin_ice

  • action_id : integer

Reply event: ice_begun

Request temporary STUN and TURN servers and credentials for WebRTC.

search

  • action_id : integer
  • realm_id : string (optional)
  • search_term : string

Reply events: search_results multiple times

Searches users and channels by name or realname prefixes.

search_users

  • action_id : integer
  • realm_id : string (optional)
  • search_term : string

Reply events: search_results multiple times

Searches users by name or realname prefixes.

search_channels

  • action_id : integer
  • realm_id : string (optional)
  • search_term : string

Reply events: search_results multiple times

Searches channels by name prefixes.

track

  • action_id : integer
  • realm_id : string
  • queue_ids : string array (optional)
  • track_stage : string
  • track_metadata : object

Reply event: ack

ping

  • action_id : integer (optional)

Reply events: pong

Events

Event types

error

  • error_type : string
  • error_reason : string (optional)
  • session_id : string (if applicable)
  • action_id : integer (if applicable)
  • user_id : string (if applicable)
  • identity_type : string (if applicable)
  • identity_name : string (if applicable)
  • channel_id : string (if applicable)
  • realm_id : string (if applicable)
  • queue_id : string (if applicable)
  • tag_id : string (if applicable)
  • message_type : string (if applicable)

session_created

  • session_id : string
  • session_host : string (optional)
  • user_id : string
  • user_auth : string (if a new authentication token was created)
  • user_attrs : object
  • user_settings : object
  • user_account : object
  • user_identities : object
  • user_dialogues : object
  • user_channels : object
  • user_realms : object
  • user_realms_member : object (optional)
  • user_queues : object (optional)
  • puppet_masters : object (optional)

If specified, session_host contains a hostname which should be used in subsequent connections for this session.

If a new user was created, then user_auth contains a generated password which may be used in future create_session actions by the client.

The user_account object contains information about channel, realm, queue and file upload quota and service subscription (optional):

"user_account": {
	"channels": {
		"quota":             10,
		"available":         3
	},
	"realms": {
		"quota":             3,
		"available":         2
	},
	"queues": {
		"quota":             5,
		"available":         4
	},
	"queue_members": {
		"quota":             5
	},
	"uploads": {
		"quota":             1073741824,
		"available":         917187592
	},
	"subscriptions": [
		{
			"active":        true,
			"plan":          "medium_free",
			"expiration":    1351776933
		},
		{
			"plan":          "small",
			"renewal":       1362888044,
			"channels": {
				"quota":     5,
				"suspended": 2
			},
			"realms": {
				"quota":     1,
				"suspended": 0
			},
			"queues": {
				"quota":     0,
				"suspended": 1
			},
			"queue_members": {
				"quota":     0
			},
			"uploads": {
				"quota":     1048576
			}
		}
	]
}

The user_identities object consists of identity types mapped to objects containing identity names mapped to identity attributes:

"user_identities": {
	"email": {
		"user@example.com": { "attr": "value", ... },
		...
	},
	...
}

The user_dialogues object consists of user identifiers (of users with whom there are ongoing private conversations) mapped to objects containing the optional dialogue_members object, dialogue_status string, audience_metadata object, and dialogue_metadata object:

"user_dialogues": {
	"12345": {
		"dialogue_members": {
			"23456": { "attr": "value", ... },
			"65432": { "attr": "value", ... }
		},
		"dialogue_status": "highlight",
		"audience_metadata": { "attr": "value", ... },
		"dialogue_metadata": { "attr": "value", ... }
	},
	...
}

The user_channels object consists of channel identifiers mapped to objects containing the channel_attrs object and the optional channel_status and realm_id strings:

"user_channels": {
	"12345": {
		"channel_attrs":  { "attr": "value", ... },
		"channel_status": "unread",
		"realm_id":       "67890"
	},
	...
}

The user_realms object consists of realm identifiers mapped to objects containing realm attributes:

"user_realms": {
	"12345": { "attr": "value", ... },
	...
}

The user_realms_member object consists of realm identifiers mapped to objects containing the session user's realm membership attributes (if any):

"user_realms_member": {
	"12345": { "operator": true, ... },
	...
}

The user_queues object consists of queue identifiers mapped to objects containing the queue_attrs object, the queue_position integer (optional) and the realm_id string.

"user_queues": {
	"12345": {
		"queue_attrs":    { "attr": "value", ... },
		"queue_position": 1,
		"realm_id":       "67890"
	},
	...
}

If the queue_position property is present, it means that the user is currently queuing. Otherwise the user is a member of the queue.

The puppet_masters object consists of master user identifiers mapped to objects containing the puppet_attrs object:

"puppet_masters": {
	"12345": {
		"puppet_attrs": { "attr": "value", ... }
	},
	...
}

session_status_updated

  • channel_id : string (if applicable)
  • user_id : string (if applicable)
  • message_id : string

Another session indicated that it has read channel or dialogue messages up to the specified message.

user_created

  • action_id : integer (if applicable)
  • user_id : string
  • user_auth : string (if a standalone user was created)
  • user_attrs : object
  • user_settings : object
  • puppet_masters : object (optional)

user_found

  • action_id : integer (if applicable)
  • user_id : string
  • user_attrs : object
  • user_settings : object (if the user is the session user)
  • user_account : object (if the user is the session user)
  • user_identities : object
  • user_dialogues : object (if the user is the session user)
  • user_channels : object (if the user is the session user)
  • user_realms : object (if the user is the session user)
  • user_realms_member : object (optional)
  • user_queues : object (if the user is the session user)
  • dialogue_members : object (if the session user has a dialogue with the user)
  • dialogue_status : string (if the session user has a dialogue with the user and there are unread messages)
  • message_time : float (if the session user has a dialogue with the user)
  • audience_metadata : object (if the session user has accepted an audience from the user)
  • puppet_masters : object (optional)

The dialogue_members object consists of two user identifiers mapped to dialogue membership attributes:

"dialogue_members": {
	"12345": { "attr": "value", ... },
	"54321": { "attr": "value", ... }
}

The dialogue membership attributes objects will be empty unless the user is the session user.

If set, the value of dialogue_status will be "highlight", "unread" or "hidden". The message_time is the time of the latest message between the users.

user_updated

  • action_id : integer (if applicable)
  • user_id : string
  • user_attrs : object
  • user_settings : object (if the user is the session user)
  • user_account : object (if the user is the session user)
  • puppet_masters : object (optional)

user_deleted

  • action_id : integer (if applicable)
  • user_id : string

identity_found

  • action_id : integer (if applicable)
  • user_id : string
  • identity_type : string
  • identity_name : string
  • identity_attrs : object (if belonging to the session user)

identity_created

  • action_id : integer (if applicable)
  • user_id : string
  • identity_type : string
  • identity_name : string
  • identity_attrs : object

identity_updated

  • action_id : integer (if applicable)
  • user_id : string
  • identity_type : string
  • identity_name : string
  • identity_attrs : object

identity_deleted

  • action_id : integer (if applicable)
  • user_id : string
  • identity_type : string
  • identity_name : string

dialogue_updated

  • action_id : integer (if applicable)
  • user_id : string
  • dialogue_members : object
  • dialogue_status : string (if applicable)
  • message_time : float (if applicable)
  • audience_metadata : object (if the session user has accepted an audience from the user)
  • dialogue_metadata : object (if the session user has accepted an audience from the user)

channel_created

  • action_id : integer (if applicable)
  • channel_id : string
  • channel_attrs : object
  • realm_id : string

channel_found

  • action_id : integer (if applicable)
  • channel_id : string
  • channel_attrs : object
  • channel_members : object (if the session user is a member)
  • channel_members_metadata : object (if applicable)
  • channel_member_count : integer (if the session user is owner or realm operator)
  • channel_status : string (if the session user is a member and there are unread messages)
  • message_time : float (if applicable)
  • realm_id : string (if applicable)
  • audience_metadata : object (if applicable)
  • member_message_metadata : object (if applicable)

The channel_members object consists of user identifiers mapped to objects containing the user_attrs object, the member_attrs object (the channel-specific attributes of the user) and the optional puppet_attrs object (if the channel owner is a puppet master):

"channel_members": {
	"12345": {
		"user_attrs": { "attr": "value", ... },
		"member_attrs": { "attr": "value", ... },
		"puppet_attrs": { "attr": "value", ... }
	},
	...
}

The audience_metadata object contains metadata that was supplied at the time of audience request. It doesn't change after that (it doesn't include message metadata).

The channel_members_metadata object consists of user identifiers mapped to objects containing metadata. It may include metadata for some, but not necessary all current and past members of the channel. The per-member metadata doesn't change after it appears (it doesn't include message metadata).

The member_message_metadata object consists of user identifiers mapped to objects containing metadata. It may include metadata for some, but not necessary all current and past members of the channel. It is summary of the latest metadata keys sent via ninchat.com/metadata messages (it doesn't include audience_metadata or channel_members_metadata). It doesn't get updated in real time as messages are received.

If set, the value of channel_status will be "unread" or "highlight". The message_time is the time of the latest message.

channel_joined

  • action_id : integer (if applicable)
  • channel_id : string
  • channel_attrs : object
  • channel_members : object
  • channel_members_metadata : object (if applicable)
  • message_time : float (if applicable)
  • realm_id : string (if applicable)
  • audience_metadata : object (if applicable)
  • member_message_metadata : object (if applicable)

The session user created a new channel or joined an existing channel, or an audience request was accepted.

channel_parted

  • action_id : integer (if applicable)
  • event_cause : string (optional)
  • channel_id : string

The session user left or was removed from a channel.

channel_updated

  • action_id : integer (if applicable)
  • event_cause : string (optional)
  • channel_id : string
  • channel_attrs : object
  • realm_id : string (if applicable)

channel_deleted

  • action_id : integer (if applicable)
  • channel_id : string

channel_member_joined

  • channel_id : string
  • user_id : string
  • user_attrs : object
  • member_attrs : object
  • member_metadata : object (optional)
  • puppet_attrs : object (optional)

Someone else joined a channel.

channel_member_parted

  • action_id : integer (if applicable)
  • event_cause : string (optional)
  • channel_id : string
  • user_id : string

Someone else left or was removed from a channel.

The event_cause is "member_remove" if the event was caused by a remove_member action.

channel_member_updated

  • action_id : integer (if applicable)
  • channel_id : string
  • user_id : string
  • member_attrs : object

realm_found

  • action_id : integer (if applicable)
  • realm_id : string
  • realm_attrs : object
  • realm_settings : object
  • realm_members : object (if the session user is a member)

realm_members is analogous to channel_members described above.

realm_queues_found

  • action_id : integer
  • realm_id : string
  • realm_queues : object

The realm_queues object consists of queue identifiers mapped to objects containing queue_attrs (object) and optionally queue_position (integer):

"realm_queues": {
	"12345": {
		"queue_attrs": {
			"name": "First World Problems",
			"length": 3
		},
		"queue_position": 1
	},
	...
}

realm_joined

  • action_id : integer (if applicable)
  • realm_id : string
  • realm_attrs : object
  • realm_settings : object
  • realm_members : object

The session user created a new or joined an existing realm.

realm_parted

  • action_id : integer (if applicable)
  • event_cause : string (optional)
  • realm_id : string

The session user left or was removed from a realm.

realm_updated

  • action_id : integer (if applicable)
  • realm_id : string
  • realm_attrs : object
  • realm_settings : object

realm_deleted

  • action_id : integer (if applicable)
  • realm_id : string

realm_member_joined

  • action_id : integer (if applicable)
  • realm_id : string
  • user_id : string
  • user_attrs : object
  • member_attrs : object
  • puppet_attrs : object (optional)

Someone else joined a realm.

realm_member_parted

  • action_id : integer (if applicable)
  • event_cause : string (optional)
  • realm_id : string
  • user_id : string

Someone else left or was removed from a realm.

The event_cause is "member_remove" if the event was caused by a remove_member action.

realm_member_updated

  • action_id : integer (if applicable)
  • realm_id : string
  • user_id : string
  • member_attrs : object

queue_created

  • action_id : integer (if applicable)
  • queue_id : string
  • queue_attrs : object
  • queue_settings : object
  • queue_members : object
  • realm_id : string (if applicable)

queue_members is analogous to channel_members (see the channel_found event).

queue_found

  • action_id : integer (if applicable)
  • queue_id : string
  • queue_attrs : object
  • queue_settings : object (if applicable)
  • queue_members : object (if applicable)
  • queue_position : integer (if applicable)
  • queue_time : float (if applicable)
  • realm_id : string (if applicable)

queue_position is defined if the viewer (a customer) is currently in the queue. It is 1-based.

queue_time is defined if the viewer is a queue member and the queue is not empty. It indicates the number of seconds the next customer (at position 1) has been waiting.

queue_updated

  • action_id : integer (if applicable)
  • event_cause : string (optional)
  • queue_id : string
  • queue_attrs : object
  • queue_settings : object
  • queue_position : integer (if applicable)
  • queue_time : float (if applicable)
  • realm_id : string (if applicable)

See queue_found for details.

queue_deleted

  • action_id : integer (if applicable)
  • queue_id : string
  • realm_id : string (if applicable)

queue_joined

  • queue_id : string
  • queue_attrs : object
  • queue_settings : object
  • realm_id : string (if applicable)

You were added to an audience queue.

queue_parted

  • event_cause : string (optional)
  • queue_id : string
  • realm_id : string (if applicable)

You were removed from an audience queue.

queue_member_joined

  • action_id : integer (if applicable)
  • queue_id : string
  • user_id : string
  • user_attrs : object
  • member_attrs : object

Someone was added to an audience queue.

queue_member_parted

  • action_id : integer (if applicable)
  • event_cause : string (optional)
  • queue_id : string
  • user_id : string

Someone was removed from an audience queue.

The event_cause is "member_remove" if the event was caused by a remove_member action.

audience_enqueued

  • action_id : integer (if applicable)
  • queue_id : string
  • queue_attrs : object
  • queue_position : integer
  • audience_id : string

queue_stats_contents

  • action_id : integer
  • queue_stats : object

Example queue stats:

"queue_stats": {
	"2013091812": {
		"describe_count": 67,
		"request_count": 10,
		"audiences": [
			{
				"agent_id": "12345",
				"accept_count": 3,
				"finish_count": 2,
				"finish_duration_avg": 257.3,
				"ratings": {
					"-1": 1,
					"1": 1
				}
			},
			{
				"agent_id": "23456",
				"tag_ids": [
					"76543"
				],
				"vars": {
					"xyz": "100",
					"abcdef": "ghijkl"
				},
				"accept_count": 1,
				"finish_count": 2,
				"finish_duration_avg": 130.01,
				"ratings": {
					"0": 2
				}
			},
			...
		],
		"accept_delay_avg": 41.7,
		"drop_count": 6,
		"drop_delay_avg": 237.13
	},
	...
}

The timestamp keys of the queue_stats object are composed of year, month, day and hour (UTC).

The "audiences" array contains groups of statistics. Each group is identified by "agent_id", optional "tag_ids" and optional "vars". See Audience metadata for information about setting tag identifiers and custom variables.

message_received