Overview and Introduction

API Overview

The Chat API follows an RPC pattern.

RPC calls

The API endpoints can be reached via Websockets or HTTP

Events

The Websocket connection is also used to receive events from the server.

The events can also be received via HTTP longpolling. This is not recommended and not documented.

Websockets or HTTP?

If you want to implement a client and want to receive events, use a Websocket.

If you just want to fetch some information for an integration, use HTTP.

You can also combine both aproaches.

RPC Detail

We use WAMPv1

every RPC call has:

  • a namespace, e.g. organizations
  • an action, e.g. get_organization
  • a list of arguments. The arguments have names in the RPC documentation but are not named when doing the RPC call. They have to be in the right order. Sometimes it’s only one argument, a JSON objects with named attributes.

RPC Call via Websocket

Not documented yet. See WAMPv1 documentation

Call RPC via HTTP

Request

  • HTTP Method: POST
  • URL: /lp/rpc/
  • Authentication: See “Authentication” to find out how the Token authentication (and other methods) work
  • Body: JSON

Response

  • Body: JSON. See documentation for each call

Example

  • namespace: organizations
  • action: get_organization
  • arguments:
    • org_id = 1

Data, JSON: encoded:

{
  "ns": "organizations",
  "action": "get_organization",
  "args": [
    "1"
  ]
}

Example request with curl (with token authentication):

curl -X "POST" "https://chatgrape.com/lp/rpc/" \
    -H "Authorization: Token YOUR_TOKEN" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d "{\"ns\":\"organizations\",\"action\":\"get_organization\",\"args\":[\"1\"]}"

PUBSUB Call via Websocket

For websocket connections we implemented SUBSCRIBE and UNSUBSCRIBE from the WAMP v.1.

When calling Organizations.join with subscribe=False the client will not automatically subscribe to any pubsub channel of a chat room or private conversation (link). It will only listen to its own user and session pubsub channels which are implicitly subscribed when connecting over websocket.

Joining without subscriptions may be usefull for clients that are only interested in events from specific channels. The client can manually subscribe to events from a chat room by sending a SUBSCRIBE message.

Currently it is only allowed to subscribe to chat rooms or private conversations but as this might change in the future channel ids have to be send with there proper namespace “channel”. (e.g. "channel:12" for subscribing to events from the chat channel 12).

A WAMP SUBSCRIBE / UNSUBSCRIBE message has the format [SUBSCRIBE_TYPE_ID, CHANNEL] the according type ids are SUBSCRIBE: 5 and UNSUBSCRIBE: 6.

A full SUBSCRIBE message for the channel 18 would look like this:

[5, "channel:18"]