Conversations

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 access token.

Create New Conversation

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
{
    "data": {
        "content_type": "message",
        "id": 3,
        "conversationId": 1,
        "message": "Dicta ea qui enim labore. Perspiciatis consequatur quia dolorum est quis nihil neque. Quidem qui aspernatur quidem.",
        "date": 1540365820,
        "is_new": true,
        "author": {
          "content_type": "user",
          "id": 6,
          "name": "Stella Donnelly",
          "first_name": "Stella",
          "last_name": "Donnelly",
          "title": "Engine Assembler",
          "avatar": null,
          "active": true,
          "unit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "physicalUnit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "url": "api/users/6"
        },
        "files": [],
        "uploading_files": 0,
        "url": "api/messages/3"
    }
}

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 with subsequent POSTs to /api/messages/ID/files

Get Conversations

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

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "content_type": "conversation",
      "title": "Sint quaerat ut est laborum.",
      "publish": {
        "created_at": 1540365820,
        "updated_at": 1540365820
      },
      "interaction": {
        "seen": true
      },
      "latestMessage": {
        "content_type": "message",
        "id": 3,
        "conversationId": 1,
        "message": "Dicta ea qui enim labore. Perspiciatis consequatur quia dolorum est quis nihil neque. Quidem qui aspernatur quidem.",
        "date": 1540365820,
        "is_new": true,
        "author": {
          "content_type": "user",
          "id": 6,
          "name": "Stella Donnelly",
          "first_name": "Stella",
          "last_name": "Donnelly",
          "title": "Engine Assembler",
          "avatar": null,
          "active": true,
          "unit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "physicalUnit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "url": "api/users/6"
        },
        "files": [],
        "uploading_files": 0,
        "url": "api/messages/3"
      },
      "participants": [
        {
          "content_type": "user",
          "id": 3,
          "name": "Else Considine",
          "first_name": "Else",
          "last_name": "Considine",
          "title": "Biochemist",
          "avatar": null,
          "active": true,
          "unit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "url": "api/users/3"
        }
      ],
      "url": "api/chat/1"
    }
  ]
}

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:

{
    "data": {
      "id": 1,
      "content_type": "conversation",
      "title": "Sint quaerat ut est laborum.",
      "publish": {
        "created_at": 1540365820,
        "updated_at": 1540365820
      },
      "interaction": {
        "seen": true
      },
      "latestMessage": {
        "content_type": "message",
        "id": 3,
        "conversationId": 1,
        "message": "Dicta ea qui enim labore. Perspiciatis consequatur quia dolorum est quis nihil neque. Quidem qui aspernatur quidem.",
        "date": 1540365820,
        "is_new": true,
        "author": {
          "content_type": "user",
          "id": 6,
          "name": "Stella Donnelly",
          "first_name": "Stella",
          "last_name": "Donnelly",
          "title": "Engine Assembler",
          "avatar": null,
          "active": true,
          "unit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "physicalUnit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "url": "api/users/6"
        },
        "files": [],
        "uploading_files": 0,
        "url": "api/messages/3"
      },
      "participants": [
        {
          "content_type": "user",
          "id": 3,
          "name": "Else Considine",
          "first_name": "Else",
          "last_name": "Considine",
          "title": "Biochemist",
          "avatar": null,
          "active": true,
          "unit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "url": "api/users/3"
        }
      ],
      "url": "api/chat/1"
    }
}

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:

{
    "data": [
        {
          "content_type": "user",
          "id": 3,
          "name": "Else Considine",
          "first_name": "Else",
          "last_name": "Considine",
          "title": "Biochemist",
          "avatar": null,
          "active": true,
          "unit": {
            "content_type": "unit",
            "id": 1,
            "name": "HQ",
            "level": 0,
            "unit_type": "unit",
            "url": "api/units/1"
          },
          "url": "api/users/3"
        }
    ]
}

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 participants for

Get Conversation Files

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

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "name": "testfile1.jpg",
      "mime": "video/vimeo",
      "size": 123456,
      "type": "video",
      "extension": "jpg",
      "processing": false,
      "date": 1540451427,
      "source": "https://vimeo.com/181630208",
      "stream": [],
      "versions": [],
      "screenshot": [],
      "created_at": {
        "date": "2018-10-25 07:10:27.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2018-10-25 07:10:27.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "created_formatted": "25 October 2018",
      "updated_formatted": "25 October 2018"
    }
  ],
  "links": {
    "first": "https://example.ziik.io/api/chat/1/files?page=1",
    "last": "https://example.ziik.io/api/chat/1/files?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://example.ziik.io/api/chat/1/files",
    "per_page": 3,
    "to": 1,
    "total": 1
  }
}

This endpoint retrieves files uploaded to any message in a chat conversation.

HTTP Request

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

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the chat conversation to retrieve files for

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

Add participants to conversation

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

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint adds participants to a given conversation.

HTTP Request

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

Request Parameters

ParameterTypeRequiredDescription
participantsarrayYesArray of one or more participants IDs.

Update group chat title

curl -i -X PATCH "https://example.ziik.io/api/chat/2"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an group chat title.

HTTP Request

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

ParameterTypeRequiredDescription
titleStringYesTitle for group chat

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