API & Web Sockets

The Natterly web socket service is predominently used for receiving live data. For writing data, you will mostly use the HTTP API.

There are two routes to working with the web socket API. You can either be a user or you can be a session. A user is an agent that wishes to accept chats and interact with mulitple chats simultanouesly. A session is a single person who is browsing a website with the Natterly Chatbox embedded on it - a session is generated when they first visit and maintained until they have been inactive for an hour.

Regardless of whether you're a user or a session, there is some key methodology that applies to both.

Messaging philosophy

All messages between server & client are encoded as JSON.

Actions

An action is sent from the client to the server. For example, when a client wants to subscribe to an object, they will send an action message along with details of the object they want to subscribe to. This can also be used for authenticating a user to an established web socket connection. A standard action JSON hash looks like this:

{"action":"Subscribe","payload":{"exchange":"accounts","routing_key":12345678}}

Events

An event is sent from the server to the client. You will receive events on a regular basis from the server. A standard event JSON hash looks like this:

{"event":"Authenticated","payload":{"username":"johnsmith","user_id":12345678}}

You may receive events with the name Error. You should handle this as appropriate for your application as they may be in response to an action you have just sent. In the case of an error you will find an error parameter with a code for the error, for example:

{"event":"Error","payload":{"error":"InvalidUserAPIToken"}}

Connecting

When using Natterly, you will be provided with the endpoint URL for the web socket authentication from the HTTP API when you obtain your authentication token. The method for doing this depends on whether you're authenticating as a user or a session. You will obtain this from the authentication/get_api_token for users and from sessions_for_session/register for sessions.

Once you have a URL you should establish a connection to the URL provided exactly as shown.

As soon as you connect, the server will send a Welcome event.

Subscriptions

In order to receive events you need to subscribe to one or more exchanges. For example, if you wanted to receive all messages for a chat, you will subscribe to the chats exchange and provide the UUID for the chat you wish to receive messages for. Once subscribed, you will receive all events until you unsubscribe. You can subscribe to as many exchanges as you wish however we recommend not subscription to more than 20 in a session.

The exchanges which are available to you depend on whether you're authenticated as a user or a session.

To subscribe to an exchange you need to send a Subscribe action with values for exchange & routing_key in the payload. If successful, you'll receive a Subscribed event, otherwise you'll receive an error.

To unsubscribe from an exchange, just do the same as subscribing but change the action name to Unsubscribe.

In some cases, you might find that you are automatically subscribed to exchanges by the server. In these cases you'll receive your Subscribed event as normal. It usually happens immediately after authentication.

Actions

The following actions are available across the web socket serivce. All actions that are prefixed with U_ are designed for use when working as a user and those with C_ are for use when working as a session.

User actions

  • U_AuthenticateWithAPIToken - authenticates your connection as your desired user. It should receive a token attribute in the payload with the user's API token.

    • An Authenticated event will be emitted if successful.
    • If the API token is invalid a InvalidAPIToken error will be emitted.
  • U_Ping - tells the server you're still there to keep the connection alive. No attributes are supported in the payload.

    • The server will respond with a Pong event.
  • U_Typing - tells the server the user is currently typing a message for a given chat. It should receive a chat attribute in the payload with the UUID of the chat the user is typing within.

    • The server will not respond at all if successful
    • If no chat can be found with the UUID provided, a NoChatFound error will be emitted.

Session actions

  • C_JoinSession - authenticates your connection as the desired session. It should receive a token attribute in the payload with the session's UUID.

    • You will receive a SessionJoined event if successful.
    • If the session has visitor details associated with it, a VisitorDetailsAdded event will also be emitted.
    • If there is a chat in progress on the session, a RestoreChat event will be emitted.
    • If the session token is invalid a InvalidSessionToken error will be emitted.
  • C_Ping - tells the server you're still there to keep the connection alive. No attributes are supported in the payload.

    • The server will respond with a Pong event.
  • C_SetPendingMessage - tells the server the visitor is currently typing a message for an active chat. It should receive a message attribute in the payload with text the user is currently typing.

    • The server will not respond at all if successful.
    • If no chat is initated on the session, a NoChatInitiated error will be emitted.

Exchanges

The following exchanges are available to you to subscribe to. You must authenticate before attempting to subscribe to any of these exchanges and you must have access to the exchange you're attempting to subscribe to.

The list below shows the exchanges that are available plus a list of events that you may receive on each exchange once subscribed.

  • accounts - this exchange receives events that are appropriate to all users on an account. All users are subscribed to this automatically when they authenticate.

    • DepartmentCreated - when a department is created
    • DepartmentUpdated - when a department is updated
    • DepartmentDeleted - when a department is deleted
    • SiteCreated - when a site is created
    • SiteUpdated - when a site is updated
    • SiteDeleted - when a site is deleted
    • UserCreated - when a user is created
    • UserStatusChanged - when a user changes from online/invisible/offline.
    • UserUpdated - when a user is updated
    • UserDeleted - when a user is deleted
  • departments - this exchange receives events for all chats in a given department. Users can only subscribe to departments that they have access to.

    • ChatAccepted - a chat is accepted
    • ChatAssigned - a chat is assigned to a user (or unassigned)
    • ChatClosed - a chat is closed
    • ChatEvent - a new chat event
    • ChatEventChanged - a chat event has been updated
    • ChatEventRemoved - a chat event has been removed
    • ChatInitiated - a new chat has been initiated by a visitor
    • ChatPendingMessageUpdated - the pending message for a chat has been updated (i.e. a visitor is typing)
    • Message - a new message has been received
    • MessageChanged - a message has been updated
    • MessageRemoved - a message has been removed
    • SessionHistory - the user has browsed to a new page
    • VisitorDetailsAddedToChat - visitor information has been associated with a chat
  • sessions - this exchange is used by sessions to receive any information about chats on their. Sessions are automatically subscribed to this exchange when authenticating.

    • ChatAccepted - a chat is accepted
    • ChatAssigned - a chat is assigned to a user (or unassigned)
    • ChatClosed - a chat is closed
    • ChatEvent - a new chat event
    • ChatEventChanged - a chat event has been updated
    • ChatEventRemoved - a chat event has been removed
    • ChatInitiated - a chat has been initiated by the user on this session
    • Message - a new message has been received
    • MessageChanged - a message has been updated
    • MessageRemoved - a message has been removed
    • SessionExpired - the session has expired and can no longer be used
    • VisitorDetailsAdded - visitor information has been added to this session
    • VisitorDetailsAddedToChat - visitor information has been added to the chat on this session
  • sites - this exchange is used by users to receive information about a site.

    • SessionExpired - a session has expired is no longer valid
    • SessionJoined - a new session has been created OR a session has been updated
    • SiteAvailability - the availability status for a site has changed due to a user going online/offline
  • sites_public - this exchange is subscribed to by sessions for the site that they are embedded in. Sessions are automatically subscribed to this exchange when authenticating.

    • SiteAvailability - the availability status for a site has changed due to a user going online/offline
  • users - this exchange receives events that are specific to a certain user. Users can only subscribe to their own exchange. Users are automatically subscribed to this exchange when authenticating.

    • There are currently no events sent here.
Car left 1 Car left 2 Car left 3 Car left 4 Car right 1 Car right 2 Car right 3
Windmill Windmill Windmill