Messages API Calls


Create a message

POST /projects/{project_id}/posts.json

This will create a new message. Also, you have the option of sending a notification to a list of people you specify.

Request

{
  "post": {
    "title": "Yet another task for tomorrow",
    "category-id": "",
    "notify": [""],
    "private": "0",
    "body": "Yet another message content goes here",
    "attachments": "",
    "pendingFileAttachments": "",
    "tags": "tag1,tag2,tag3"
  }
}

Link to Coldfusion Code Sample

Response

HTTP status code 201 (“Created”) on success. The Location header will then be set to the “Get message” URL for your new message. using that URL, you can get the new message ID.

If unsuccessful, a non-200 status code will be returned, possibly with error information in json format.

Attaching Files

You can attach existing files using the attachments option. This is a comma-separated list of existing File ID's

To attach new files use the pendingFileAttachments option (see the uploading files section for more info). 

The pendingFileAttachments field is a comma-separated list of pendingFileRef's

Message Categories

View "Message Categories" to see how to list and create message categories.


 

Retrieve a Single Message

GET /posts/{id}.json

Uses the given messsage ID to retrieve a message

Response

{
    "post": {
        "project-id": "999",
        "author-first-name": "Demo",
        "milestone-id": "",
        "numNotified": "0",
        "isRead": "1",
        "private": "0",
        "comments-count": "0",
        "author-avatar-url": "https://s3.amazonaws.com/TWFiles/2/users/999.avatar",
        "author-last-name": "User",
        "id": "999",
        "last-changed-on": "2014-03-31T16:40:56Z",
        "use-textile": false,
        "content-type": "HTML",
        "isOriginal": "1",
        "user-display-posted-date": "Mon, 31 Mar 2014",
        "user-display-posted-time": "5:38PM",
        "message-status": "active",
        "attachments-count": "0",
        "post-id": "999",
        "category-id": "",
        "html-body": "Message content goes here",
        "posted-on": "2014-03-31T17:38:58Z",
        "body": "Message content goes here",
        "attachments": [],
        "author-id": "999",
        "post-status": "active",
        "display-body": "Message content goes here",
        "title": "Message title",
        "category-name": ""
    },
    "STATUS": "OK"
}


 

Retrieve Latest Messages

GET /projects/{project_id}/posts.json

For the project ID supplied, will return the 25 most recent messages

Response

{
    "posts": [
        {
            "user-display-posted-time": "6:01PM",
            "project-id": "999",
            "author-first-name": "Demo",
            "attachments-count": "0",
            "milestone-id": "",
            "isRead": "1",
            "private": "0",
            "comments-count": "0",
            "author-avatar-url": "https://s3.amazonaws.com/TWFiles/2/users/999.avatar",
            "category-id": "",
            "author-last-name": "User",
            "posted-on": "2014-03-31T18:01:17Z",
            "body": "Yet another message content goes here",
            "id": "999",
            "last-changed-on": "2014-03-31T18:01:17Z",
            "content-type": "TEXT",
            "last-comment-date": "2014-03-31T18:01:17Z",
            "user-display-posted-date": "Mon, 31 Mar 2014",
            "author-id": "999",
            "title": "Yet another task for tomorrow",
            "category-name": ""
        }
    ],
    "STATUS": "OK"
}



 

Retrieve Messages by Category

GET /projects/{project_id}/cat/{category_id}/posts.json

As before, will return you the most recent 25 messages, this time limited by project and category.

Response

{
    "posts": [
        {
            "user-display-posted-time": "6:11PM",
            "project-id": "999",
            "author-first-name": "Demo",
            "attachments-count": "0",
            "milestone-id": "",
            "isRead": "1",
            "private": "0",
            "comments-count": "0",
            "author-avatar-url": "https://s3.amazonaws.com/TWFiles/2/users/999.avatar",
            "category-id": "999",
            "author-last-name": "User",
            "html-body": "Docs need to be updated",
            "posted-on": "2014-03-31T18:11:03Z",
            "body": "Docs need to be updated",
            "id": "999",
            "last-changed-on": "2014-03-31T18:11:03Z",
            "content-type": "HTML",
            "last-comment-date": "2014-03-31T18:11:03Z",
            "user-display-posted-date": "Mon, 31 Mar 2014",
            "author-id": "999",
            "title": "Reg: Docs",
            "category-name": "Demo Category 3"
        }
    ],
    "STATUS": "OK"
}


 

Update message

PUT /posts/{id}.json

Updates an existing message, optionally sending notifications to a selected list of people.

Request

{
  "post": {
    "title": "Message Title",
    "category-id": "",
    "notify": ["999"],
    "private": "0",
    "body": "Message content goes here",
    "attachments": "",
    "pendingFileAttachments": ""
  }
}

Link to ColdFusion code Sample
 

Response

Returns HTTP status code 200 on success, or any other code (and possibly error information in json format) on error.



Get archived messages

GET /projects/{project_id}/posts/archive.json

Rather than the full message, this returns a summary record for each message in the specified project.

Response

{
    "posts": [
        {
            "user-display-posted-time": "6:01PM",
            "project-id": "999",
            "author-first-name": "Demo",
            "attachments-count": "0",
            "milestone-id": "",
            "isRead": "1",
            "private": "0",
            "comments-count": "0",
            "author-avatar-url": "https://s3.amazonaws.com/TWFiles/2/users/999.avatar",
            "category-id": "",
            "author-last-name": "User",
            "posted-on": "2014-03-31T18:01:17Z",
            "body": "Yet another message content goes here",
            "id": "999",
            "last-changed-on": "2014-03-31T18:01:17Z",
            "content-type": "TEXT",
            "last-comment-date": "2014-03-31T18:01:17Z",
            "user-display-posted-date": "Mon, 31 Mar 2014",
            "author-id": "999",
            "title": "Yet another task for tomorrow",
            "category-name": ""
        }
    ],
    "STATUS": "OK"
}


 

Get archived messages by category

GET /projects/{project_id}/cat/{category_id}/posts/archive.json

As above, but returns only the posts in the given category

Response

{
    "posts": [
        {
            "user-display-posted-time": "5:59PM",
            "project-id": "999",
            "author-first-name": "Demo",
            "attachments-count": "0",
            "milestone-id": "",
            "isRead": "1",
            "private": "0",
            "comments-count": "0",
            "author-avatar-url": "https://s3.amazonaws.com/TWFiles/2/users/999.avatar",
            "category-id": "999",
            "author-last-name": "User",
            "html-body": "Another message content goes here<br>",
            "posted-on": "2014-03-31T17:59:49Z",
            "body": "Another message content goes here\r\n",
            "id": "999",
            "last-changed-on": "2014-03-31T17:31:45Z",
            "content-type": "HTML",
            "last-comment-date": "2014-03-31T17:59:49Z",
            "user-display-posted-date": "Mon, 31 Mar 2014",
            "author-id": "999",
            "title": "Another task for tomorrow",
            "category-name": "Demo Category 3"
        }
    ],
    "STATUS": "OK"
}


Archive a message

PUT /messages/{id}/archive.json

Archives the message including all replies etc

Response

Returns HTTP status code 200 on success.

Un-archive a message

PUT /messages/{id}/unarchive.json

Restores the message from the Archive including all replies etc

Response

Returns HTTP status code 200 on success.

Destroy message

DELETE /posts/{id}.json

Deletes the message including all comments etc

Response

Returns HTTP status code 200 on success.


Mark Message Read

PUT /messages/{id}/markread.json

Marks a specific message as read by the current authenticated user

Response

Returns HTTP status code 200 on success.