Chat

The chat is a conversation involving two or more users.

Any user can contact any other user through the chat, to quickly inform or request information - or just say hi.

TIP

In the following, "Current user" means the user that has authenticated with the API, identified by the API token.

Get Conversations

curl "https://example.ziik.io/api/chat"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

{
    "hits":
    [
      {
        "id": 1,
        "updated": 123456789,
        "started": 234567890,
        "participants":
        [
            {
                "id": 123,
                "name": "Test User",
                "avatar": { "See User Service ..." },
                "userType": { "See User Service ..." },
                "url": "api/users/123"                
            },
            {
                "id": 234,
                "name": "Other User",
                "avatar": { "See User Service ..." },
                "userType": { "See User Service ..." },
                "url": "api/users/234"
            }
        ],
        "latestMessage": {
            "id": 2,
            "author": {
              "id": 234,
              "name": "Other User",
              "avatar": { "See User Service ..." },
              "userType": { "See User Service ..." },
              "url": "api/users/234"
            },
            "conversationId": 1,
            "message": "This is a message",
            "files": [ 
                {
                    "id": 101,
                    "name": "Filename.pdf",
                    "mime": "application/pdf",
                    "size": 123456,
                    "type": "document",
                    "source": "https://example.ziik.io/api/path/to/filename.pdf"
                }
            ],
            "is_new": false,
            "url": "api/messages/2"
        },
        "url": "api/chat/1"
      },
      {
          "id": 2,
          "updated": 123456790,
          "started": 234567899,
          "participants":
          [
              {
                  "id": 123,
                  "name": "Test User",
                  "avatar": { "See User Service ..." },
                  "userType": { "See User Service ..." },
                  "url": "api/users/123"                
              },
              {
                  "id": 234,
                  "name": "Other User",
                  "avatar": { "See User Service ..." },
                  "userType": { "See User Service ..." },
                  "url": "api/users/234"
              }
          ],
          "latestMessage": {
              "id": 5,
              "author": {
                "id": 234,
                "name": "Other User",
                "avatar": { "See User Service ..." },
                "userType": { "See User Service ..." },
                "url": "api/users/234"
              },
              "conversationId": 2,
              "message": "This is another message",
              "files": [ ],
              "is_new": true,
              "url": "api/messages/5"
          },
          "url": "api/chat/2"
      }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "count": 3,
            "per_page": 50,
            "current_page": 1,
            "total_pages": 1,
            "links": []
        }
    }
}

This endpoint retrieves chat conversations for the current user.

HTTP Request

GET https://example.ziik.io/api/chat

Query Parameters

ParameterTypeDefaultDescription
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.
userIntegernullif provided, only return conversation(s) with that user as only other participant

Get Single Conversation

curl "https://example.ziik.io/api/chat/2"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns JSON structured like this:

{
  "id": 2,
  "updated": 123456790,
  "started": 234567899,
  "participants":
  [
      {
          "id": 123,
          "name": "Test User",
          "avatar": { "See User Service ..." },
          "userType": { "See User Service ..." },
          "url": "api/users/123"                
      },
      {
          "id": 234,
          "name": "Other User",
          "avatar": { "See User Service ..." },
          "userType": { "See User Service ..." },
          "url": "api/users/234"
      }
  ],
  "messages": [
    {
      "id": 4,
      "author": {
        "id": 123,
        "name": "Test User",
        "avatar": { "See User Service ..." },
        "userType": { "See User Service ..." },
        "url": "api/users/123"
      },
      "conversationId": 2,
      "message": "This is a message",
      "files": [ ],
      "is_new": false,
      "url": "api/messages/4"
    },
    {
      "id": 5,
      "author": {
        "id": 234,
        "name": "Other User",
        "avatar": { "See User Service ..." },
        "userType": { "See User Service ..." },
        "url": "api/users/234"
      },
      "conversationId": 2,
      "message": "This is another message",
      "files": [ ],
      "is_new": false,
      "url": "api/messages/5"
    }
  ],
  "latestMessage": {
      "id": 5,
      "author": {
        "id": 234,
        "name": "Other User",
        "avatar": { "See User Service ..." },
        "userType": { "See User Service ..." },
        "url": "api/users/234"
      },
      "conversationId": 2,
      "message": "This is another message",
      "files": [ ],
      "is_new": false,
      "url": "api/messages/5"
  },
  "url": "api/chat/2"
}

This endpoint retrieves a specific chat conversation.

HTTP Request

GET https://example.ziik.io/api/chat/ID

URL Parameters

ParameterTypeDescription
idIntegerThe ID of the chat conversation to retrieve

Get Conversation Participants

curl "https://example.ziik.io/api/chat/2/participants"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns JSON structured like this:

[
  {
      "id": 123,
      "name": "Test User",
      "avatar": { "See User Service ..." },
      "userType": { "See User Service ..." },
      "url": "api/users/123"                
  },
  {
      "id": 234,
      "name": "Other User",
      "avatar": { "See User Service ..." },
      "userType": { "See User Service ..." },
      "url": "api/users/234"
  }
]

This endpoint retrieves all participants in a specific chat conversation.

HTTP Request

GET https://example.ziik.io/api/chat/ID/participants

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the chat conversation to retrieve

Create New Message

curl -i -X POST "https://example.ziik.io/api/chat"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{\"recipients\": {123, 234, 345}, \"message\": \"This message is for all of you\"}"

The above command returns 201 Created with a Location header for where to find the new message. Additionally, the created message is returned

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/messages/1234
{
  "id": 2,
  "author": {
    "id": 123,
    "name": "Test User",
    "avatar": { "See User Service ..." },
    "userType": { "See User Service ..." },
    "url": "api/users/123"
  },
  "conversationId": 2,
  "message": "This is a message",
  "files": [ ],
  "is_new": true,
  "url": "api/messages/2"
}

This endpoint creates a new message to a number of recipients from the current user.

HTTP Request

POST https://example.ziik.io/api/chat

Request Parameters

ParameterTypeRequiredDescription
recipientsArrayYesArray of user IDs to send the message to.
messageStringYesMessage string.
fileCountIntegerNoNumber of files that will be uploaded (type 'upload') in total, including subsequent POSTs to /api/messages/ID/files
filesArrayNoFile data for files to accompany the debate. If provided, existing files are cleared. Must be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Reply To Conversation

curl -i -X POST "https://example.ziik.io/api/chat/1234/reply"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{\"message\": \"This message is for all of you\"}"

The above command returns 201 Created with a location header for where to find the new message

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/chat/1234
{
    "message": "Message created"
}

This endpoint creates a new message in an existing conversation.

HTTP Request

POST https://example.ziik.io/api/chat/ID/reply

Request Parameters

ParameterTypeRequiredDescription
messageStringYesMessage string.
fileCountIntegerNoNumber of files that will be uploaded (type 'upload') in total, including subsequent POSTs to /api/messages/ID/files
filesArrayNoFile data for files to accompany the debate. If provided, existing files are cleared. Must be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Delete a Conversation

curl -i -X DELETE "https://example.ziik.io/api/chat/2"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes an entire chat conversation for the current user. The conversation with all the messages will still be visible to other participants who have not deleted it, yet.

HTTP Request

DELETE https://example.ziik.io/api/chat/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the chat conversation to delete

Mark Conversation Read

curl -i -X POST "https://example.ziik.io/api/chat/2/seen"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint marks all messages in a given conversation read by the current user.

HTTP Request

POST https://example.ziik.io/api/chat/ID/seen

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the chat conversation to mark read