Skip to main content
Kinetic Community

Messaging

This resource describes how messaging is implemented in Kinetic Response and details how to consume and create messages.

Messages Explained

Kinetic Response uses Messages and System Messages to manage communication within an Issue. A Message is a string of text sent from a client. A System Message is a generated message that the system sends when events happen such as a Fact being created, a Participant being revoked or Issue details changing.

Example Message:

{
    "id": 7737,
    "issue_id": 360,
    "body": "This is a Message.",
    "created_at": "2015-04-06T15:01:50.632-05:00",
    "updated_at": "2015-04-06T15:01:50.632-05:00",
    "messageable_id": null,
    "messageable_type": null,
    "guid": "9d870f1a-fc5e-4d7a-b938-c70d96796109",
    "action": null,
    "type": "Message",
    "url": null,
    "frozen_messageable": null,
    "user": {
        "email": "dillon.hodapp@kineticdata.com",
        "name": "DJH",
        "guid": "971c294f-49b7-4a05-a25f-733ce678449a"
    },
    "issue": {
        "guid": "a9f34935-96de-486a-94f2-d491e1090559"
    }
}

The "type" field indicates that this is a Message (as opposed to a System Message). It can be seen that the "body" field of the message contains the user-supplied message. The user that sent the message is specified as well in the "user" object. This specific message can be referenced by using its guid specified in the "guid" field. The id and guid for the issue that this message was created in is also available as the "issue_id" field and "issue" : {"guid": "..."} object.

System Messages are more complex than Messages. Below is an example of a System Message with some of the fields ellipsized for brevity.

Example System Message:

{
    "id": 7735,
    "issue_id": 360,
    "body": "...",
    "created_at": "2015-04-06T13:37:03.649-05:00",
    "updated_at": "2015-04-06T13:37:03.649-05:00",
    "messageable_id": 514,
    "messageable_type": "Fact",
    "guid": "9ee7b201-47e2-4a38-9795-d692ef67e5e0",
    "action": "Delete",
    "type": "SystemMessage",
    "url": null,
    "frozen_messageable": {
        ...
    },
    "user": {
        "email": "dillon.hodapp@kineticdata.com",
        "name": "DJH",
        "guid": "971c294f-49b7-4a05-a25f-733ce678449a"
    },
    "issue": {
        "guid": "a9f34935-96de-486a-94f2-d491e1090559"
    },
    "messageable": {
        ...
    }
}

The "type" field indicates that this is a System Message. Unlike a Message, a System Message has a "body" field that should be ignored. The "messageable_type" field indicates what type of object this System Message is referring to (Options are Issue, Fact, ActionItem, Upload, and Invite). The "action" field can have a value of "Create", "Update" or "Delete" and indicates the operation being performed on the object that the System Message refers to.

The "messageable" field is a representation of an object in its current state. If a Fact was just created, a System Message will be generated to indicate this. Looking at the "messageable" field will show the current state of the Fact object that the System Message was generated for. For instance, if the System Message was generated because a Fact was created, then the "messageable" field would hold a Fact object that showing a currently active Fact. If the Fact was deleted a different System Message would be generated that would have a "messageable" field with a deleted Fact object.

Fetching Messages

This call will fetch a list of messages for a specific issue that occurred after a specified date.

HTTP Request

Method: GET

URL: /api/v1/issues/<issue_guid>/messages

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

Parameters

 

Route Parameter Name Description Required / Optional
last_received ISO date string indicating the point in time to start fetching messages from. 1970-01-01T00:00.00Z is the furthest date in the past that can be specified. Required

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body consisting of an array of Messages.

Example Response:

{
    "messages" :
    [
        ...
    ]
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

Response Codes

Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.

 

Fetching Messages with Presence

This call will fetch a list of messages and a list of User guids. The existence of a User guid in the list indicates that the User is currently "in the room" and working on the Issue.

HTTP Request

Method: GET

URL: /api/v1/issues/<issue_guid>/messages/presence

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

Parameters

 

Route Parameter Name Description Required / Optional
last_received ISO date string indicating the point in time to start fetching messages from. 1970-01-01T00:00.00Z is the furthest date in the past that can be specified. Required

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body consisting of an array of Messages and an array of Strings (User guids).

Example Response:

{
    "messages" :
    [
        ...
    ],
    "users" :
    [
        ...
    ]
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

Response Codes

Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.

Creating a Message

This call will create a message for a specific issue.

HTTP Request

Method: POST

URL: /api/v1/issues/<issue_guid>/messages

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

Example body:

{
  "message":{"body":"This is a message."}
}

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted message object.

Example Response:

{
    "id": 7820,
    "issue_id": 360,
    "body": "This is a message.",
    "created_at": "2015-04-09T13:02:45.673-05:00",
    "updated_at": "2015-04-09T13:02:45.673-05:00",
    "messageable_id": null,
    "messageable_type": null,
    "guid": "19256537-d015-40ca-9659-0e6fc30fe8da",
    "action": null,
    "type": "Message",
    "url": null,
    "frozen_messageable": null,
    "user": {
        "email": "dillon.hodapp@kineticdata.com",
        "name": "DJH",
        "guid": "971c294f-49b7-4a05-a25f-733ce678449a"
    },
    "issue": {
        "guid": "a9f34935-96de-486a-94f2-d491e1090559"
    }
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

Response Codes

Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.