Chatter REST API Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Using Chatter REST API Inputs

Using POST, PATCH, or PUT for Input

When you make a request using the HTTP POST, PATCH, and PUT methods, you can use request parameters or a request body. The request body can contain JSON or XML. If you pass request parameters and a request body, the request parameters are usually ignored. However, if you pass both a request body and a text parameter, you’ll receive a 400 error.

To submit a request using request parameters, use a Content-Type header field with the value application/x-www-form-urlencoded.

To submit a request using a request body, use one of the following values in a Content-Type header field and in an Accept header field:
  • application/json
  • application/xml

Uploading Binary Files

To upload a binary file, you must send it as a body part in a multipart/form-data request. You can send information such as the text of a post or comment as a JSON or XML rich input body part in the same multipart/form-data request. Alternately, you can choose to send that information in request parameters. If you pass both a rich input request body and request parameters, the request parameters are ignored.

To create a multipart/form-data request, in the head of the request, set the Content-Type HTTP header to multipart/form-data.

For information about additional HTTP headers, see W3C Form content types, and RFC 2388, which defines the multipart/form-data internet media type.

The following table describes the HTTP headers and parameters required in the rich input body part of a multipart/form-data request:

HTTP Headers for Rich Input Body Part Header Value and Parameters Description
Content-Disposition form-data; name="json"

form-data; name="xml"

 The request body for a post or comment.

For JSON, the value of name must be "json".

For XML, the value of name must be "xml".
Content-Type application/json; charset=UTF-8

application/xml; charset=UTF-8

 The data format and character set of the request body.

For JSON, the value must be application/json.

For XML, the value must be application/xml.

The following table describes the HTTP headers and parameters required in the binary upload body part of a multipart/form-data request:

HTTP Headers for Binary Upload Body Part Header Value and Parameters Description
Content-Disposition form-data; name="feedItemFileUpload"; filename=string

form-data; name="fileUpload" filename=string

form-data; name="fileData" filename=string

 To upload a binary file to a post or comment, the value of name must be "feedItemFileUpload".

To upload a user or group photo, the value of name must be "fileUpload".

To upload a file to the File list, the value of name must be "fileData".

You must specify a filename parameter and value. However, please note that Chatter uses the value of the Attachment Input: New File Upload title property as the file name, not the value of the filename parameter.

Note
Content-Type application/octet-stream; charset=ISO-8859-1 The media type and character set of the binary file.
The following example posts a new feed item, uploads a binary file, and attaches it to the new feed item. The multipart request in this example includes a part for the request body that has a Content-Type of application/json.
1POST /services/data/v30.0/chatter/feeds/user-profile/005x0000001T9PwAAK/feed-items HTTP/1.1
2Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.
3OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyae
4User-Agent: Jakarta Commons-HttpClient/3.0.1
5Host: instance_name
6Content-Length: 845
7Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
8Accept: application/json
9
10--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
11Content-Disposition: form-data; name="json"
12Content-Type: application/json; charset=UTF-8
13
14{ "body":
15   {
16      "messageSegments" : [
17      {
18         "type" : "Text", 
19         "text" : "High priority content "
20      }, {
21         "type" : "Hashtag", 
22         "tag" : "important"
23      }, {
24         "type" : "Text", 
25         "text" : "Please review this as soon as possible."
26      }
27      ]
28   }, 
29   "attachment": 
30   {
31      "attachmentType" : "NewFile",
32      "description": "Quarterly review",
33      "title" : "2012_q1"
34   }
35}
36
37--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
38Content-Disposition: form-data; name="feedItemFileUpload"; filename="foo"
39Content-Type: application/octet-stream; charset=ISO-8859-1
40
41This is the content of the file.
42--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

The following is the same example using XML instead of JSON:

1POST /services/data/v30.0/chatter/feeds/user-profile/005x0000001TBMVAA4/feed-items HTTP/1.1
2Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.
3OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyae
4User-Agent: Jakarta Commons-HttpClient/3.0.1
5Host: instance_name
6Content-Length: 897
7Content-Type: multipart/form-data; boundary=0HWq8x4y4DSQ4fqjXt6MinVMyqbf1r
8Accept: application/xml
9
10--0HWq8x4y4DSQ4fqjXt6MinVMyqbf1r
11Content-Disposition: form-data; name="xml"
12Content-Type: application/xml; charset=UTF-8
13
14<feedItem>
15   <body>
16      <messageSegments>
17         <segment>
18            <text>High priority content </text>
19            <type>Text</type>
20         </segment>
21         <segment>
22             <tag>important</tag>
23            <type>Hashtag</type>
24         </segment>
25         <segment>
26            <text>Please review this as soon as possible</text>
27            <type>Text</type>
28         </segment>
29      </messageSegments>
30   </body>
31   <attachment attachmentType="NewFile">
32      <description>Quarterly review 2012 Q1</description>
33      <title>2012_q1</title>
34   </attachment>
35</feedItem>
36
37--0HWq8x4y4DSQ4fqjXt6MinVMyqbf1r
38Content-Disposition: form-data; name="feedItemFileUpload"; filename="foo"
39Content-Type: application/octet-stream; charset=ISO-8859-1
40
41This is the content of the file.
42--0HWq8x4y4DSQ4fqjXt6MinVMyqbf1r--

The following example posts a comment to a feed item and uploads a binary attachment:

1POST /services/data/v30.0/chatter/feed-items/0D5x00000000RryCAE/comments HTTP/1.1
2Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.
3OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyae
4Accept: application/json
5User-Agent: Jakarta Commons-HttpClient/3.0.1
6Host: instance_name
7Content-Length: 978
8Content-Type: multipart/form-data; boundary=F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI
9
10--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI
11Content-Disposition: form-data; name="json"
12Content-Type: application/json; charset=UTF-8
13
14{ "body":
15   {
16      "messageSegments" : [
17      {
18         "type" : "Text", 
19         "text" : "Here's another file for review."
20      }, {
21         "type" : "Hashtag", 
22         "tag" : "important"
23      }, {
24         "type" : "Text", 
25         "text" : "Again, please review this as soon as possible."
26      }
27      ]
28   }, 
29   "attachment": 
30   {
31      "attachmentType" : "NewFile",
32      "description": "Quarterly review 2012 Q2",
33      "title" : "2012_q2"
34   }
35}
36
37--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI
38Content-Disposition: form-data; name="feedItemFileUpload"; filename="foo"
39Content-Type: application/octet-stream; charset=ISO-8859-1
40
41This is the content of the file.
42
43--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI--

Spacing and carriage returns and line feeds (CRLF) are important. For example, the following line requires spaces: Content-Disposition: form-data; name="feedItemFileUpload"; title="2012_q1_review.ppt" If you had used CRLF instead of spaces, you would have received an error.

Note