WebSockets API overview

Versioning

The API is versioned via the WebSocket protocol:

var ws = new WebSocket('wss://websockets.layer.com/?session_token=keuIjkPoPlkxw==',
    'layer-3.0');

You must explicitly provide the “layer-3.0” parameter, and adjust it as needed if requesting a different version of the API.

Packets

To avoid confusion with Layer messages, events and notifications, we use the term Packet to describe data sent/received through the WebSocket.

Packets have a standard set of top-level fields:

  • type: The type of data contained in the packet. See below
  • timestamp: The time on the server when the packet was sent
  • body: The content and details of the packet
  • counter: An index used to detect missed packets (see Recovery)

Currently there are four possible values for the type field:

  • “change” (Change Packet): Notifies you of changes that have happened on the server
  • “request” (Request Packet): The client sends this to request an operation (create a conversation, send a message, etc)
  • “response” (Response Packet): The server sends this in response to a request packet
  • “signal” (Signal Packet): The packet contains data about an ephemeral event such as typing indicators

Change packets are documented in Receiving changes below. Request and response packets are documented below, and in more detail with the corresponding REST endpoints. Signal packets are documented in Typing indicators below.

Request packet overview

The body field of a request packet should have the following fields:

Name Type Description
request_id string An ID created by the client to identify a response
method string Possible values are “Message.create” or “Conversation.create”
object_id string (optional) If sending a message, this should be the ID of the target conversation
data object The data with which to create a conversation or message

When you sends a request packet, it should generate and include a request_id. Response to that request will contain the same request_id, so that you know which request the response is associated with. The request_id field can be in any format, as long as it matches the following regex:

/^[a-zA-Z0-9.-]+$/

Note

If you don’t provide a request_id, you will not receive a Response Packet.

Response Packet overview

The body field of a Response Packet will have the following fields:

Name Type Description
request_id string Echoes back the request_id sent by the client
method string The method provided in the request
data object The data returned from the request
success boolean true if the operation succeeded, false if there was an error

If there was an error, the data field will contain an error object as documented in Errors.