Skip to content

Latest commit

 

History

History
150 lines (117 loc) · 4.54 KB

messages.md

File metadata and controls

150 lines (117 loc) · 4.54 KB
Raw

Messages

What a lot we lost when we stopped writing letters. You can't reread a phone call. - Liz Carpenter

Get messages

Messages are listed alongside all the other topics, so there is no individual index for them.

Get message

  • GET /projects/1/messages/1.json will return the specified message.
{
  "id": 936075699,
  "subject": "Welcome!",
  "created_at": "2012-03-22T16:56:51-05:00",
  "updated_at": "2012-03-22T16:56:51-05:00",
  "content": "This is a new message",
  "private": false,
  "trashed": false,
  "creator": {
    "id": 149087659,
    "name": "Jason Fried",
    "avatar_url": "https://asset0.37img.com/global/4113d0a133a32931be8934e70b2ea21efeff72c1/avatar.96.gif?r=3",
    "fullsize_avatar_url": "https://asset0.37img.com/global/4113d0a133a32931be8934e70b2ea21efeff72c1/original.gif?r=3"
  },
  "comments": [
    {
      "id": 1028592764,
      "content": "Yeah, really, welcome!",
      "created_at": "2012-03-22T16:56:48-05:00",
      "updated_at": "2012-03-22T16:56:48-05:00",
      "creator": {
        "id": 149087659,
        "name": "Jason Fried",
        "avatar_url": "https://asset0.37img.com/global/4113d0a133a32931be8934e70b2ea21efeff72c1/avatar.96.gif?r=3",
        "fullsize_avatar_url": "https://asset0.37img.com/global/4113d0a133a32931be8934e70b2ea21efeff72c1/original.gif?r=3"
      }
    }
  ],
  "subscribers": [
    {
      "id": 149087659,
      "name": "Jason Fried"
    },
    {
      "id": 1071630348,
      "name": "Jeremy Kemper"
    }
  ]
}

Create message

  • POST /projects/1/messages.json will create a new message from the parameters passed. The subscribers array is an optional list of people IDs that you want to notify about this comment (see Get accesses on how to get the people IDs for a given project).
{
  "subject": "Hello everyone",
  "content": "This is going to be a GREAT Saturday!",
  "subscribers": [1, 5, 6]
}

To "loop-in" outside email addresses for users without an account, include a new_subscriber_emails array with the parameters.

{
  "subject": "Hello everyone",
  "content": "This is going to be a GREAT Saturday!",
  "new_subscriber_emails": ["example@example.com"]
}

This will return 201 Created, with the location of the new project in the Location header along with the current JSON representation of the message if the creation was a success. See the Get message endpoint for more info.

Attaching files

Attaching files to a message requires both the token and the name of the attachment. The token is returned from the Create attachments endpoint, which you must hit first before creating an upload.

The name parameter must be a valid filename with an extension. Multiple attachments are allowed.

{
  "subject": "Totally done!",
  "content": "I finished the reports, check them out!",
  "attachments": [
    {
      "token": "4f73595a-39a6fd18317b1eeffb9c4734e95a179aa4b1b7c8",
      "name": "cover_page.pdf"
    },
    {
      "token": "4f73595f-78efbe63c77a4f5c752ce7d113d0361220f70b69",
      "name": "final_draft.pdf"
    }
  ]
}

Update message

  • PUT /projects/1/messages/1.json will update the message from the parameters passed.
{
  "subject": "This is a new subject for the message!",
  "content": "And new content..."
}

This will return 200 OK if the update was a success, along with the current JSON representation of the message in the response body. If the user does not have access to update the message, you'll see 403 Forbidden. See the Get message endpoint for more info.

Delete message

  • DELETE /projects/1/messages/1.json will delete the message specified and return 204 No Content if that was successful. If the user does not have access to delete the message, you'll see 403 Forbidden.

Private messages

To hide a message from clients, set its private attribute to true.

{
  "subject": "Hello everyone",
  "content": "This is going to be a GREAT Saturday!",
  "subscribers": [1, 5, 6],
  "private": true
}

To reveal a message to clients, set its private attribute to false.

Comments and attachments on a message inherit its privacy. If a message is made public or private, so are all of its comments and attachments.