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 resource-specific request parameters and a request body, the request parameters are ignored. Request parameters that aren’t specific to a resource, such as parameters in a bearer token URL and the _HttpMethod parameter, are processed along with the request body. Use bearer token parameters as they are. Don’t add or remove parameters.

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 up to 2 GB (including headers), 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 HTTP headers, see W3C Form content types, and RFC 2388, which defines the multipart/form-data internet media type.

This 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` use `"json"`. For XML, the value of `name` use `"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`.

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 use "json".

For XML, the value of name use "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.

Web browsers are typically incapable of making multipart requests when the non-binary parts, such as rich input bodies, have their own Content-Type. To work around this issue, specify a certain Content-Disposition name and Salesforce can read the Content-Type of the rich input part. (You don’t need to specify a Content-Type for the rich input body.)

Tip

This table describes the HTTP headers and parameters required in the rich input body part of a multipart/form-data request from a Web browser:

HTTP Headers for Rich Input Body Part from Web browser	Header Value and Parameters	Description
`Content-Disposition`	`form-data; name="feedElement"` `form-data; name="comment"` `form-data; name="photo"` `form-data; name="file"`	To post a feed element with a binary file, the value of `name` must be `"feedElement"`. To post a comment with a binary file, the value of `name` must be `"comment"`. To post a user or group photo, the value of `name` must be `"photo"`. To post a file to the Files list, the value of `name` must be `"file"`.

HTTP Headers for Rich Input Body Part from Web browser

Header Value and Parameters

Description

Content-Disposition

form-data; name="feedElement"

form-data; name="comment"

form-data; name="photo"

form-data; name="file"

To post a feed element with a binary file, the value of name must be "feedElement".

To post a comment with a binary file, the value of name must be "comment".

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

To post a file to the Files list, the value of name must be "file".

This 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="feedElementFileUpload"; filename=string` `form-data; name=name="feedElementFileUpload"; filename=string` `form-data; name="fileUpload" filename=string` `form-data; name="fileData" filename=string`	To post a feed element with a binary attachment, the value of `name` must be `"feedElementFileUpload"`. To post a comment with a binary file, the value of `name` must be `"feedElementFileUpload"`. To post a user or group photo, the value of `name` must be `"fileUpload"`. To post a file to the Files 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 `title` property of the Content Capability Input 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.

HTTP Headers for Binary Upload Body Part

Header Value and Parameters

Description

Content-Disposition

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

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

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

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

To post a feed element with a binary attachment, the value of name must be "feedElementFileUpload".

To post a comment with a binary file, the value of name must be "feedElementFileUpload".

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

To post a file to the Files 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 title property of the Content Capability Input 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.

Spacing and carriage returns and line feeds (CRLF) are important. For example, this 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

Post a feed element with a binary file

This example uses the /chatter/feed-elements resource to post a new feed item (which is a type of feed element), upload a binary file, and attach it to the new feed item. This example uses cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={ "body":{ "messageSegments":[ { "type":"Text", "text":"Please accept this receipt." } ] }, 
2"capabilities":{ "content":{ "description":"Receipt for expenses", "title":"receipt.pdf" } }, "feedElementType":"FeedItem", "subjectId":"005RR000000DmOb" };
3type=application/json' -F "feedElementFileUpload=@receipt.pdf;type=application/octet-stream"
4 -X POST https://instance_name/services/data/v35.0/chatter/feed-elements 
5-H 'Authorization: OAuth 00DRR0000000N0g!...' --insecure

This is the same example in a different format so you can see the request body parts:

1POST /services/data/v35.0/chatter/feed-elements HTTP/1.1
2Authorization: OAuth 00DRR0000000N0g!...
3User-Agent: Jakarta Commons-HttpClient/3.0.1
4Host: instance_name
5Content-Length: 845
6Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
7Accept: application/json
8
9--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
10Content-Disposition: form-data; name="json"
11Content-Type: application/json; charset=UTF-8
12
13{
14   "body":{
15      "messageSegments":[
16         {
17            "type":"Text",
18            "text":"Please accept this receipt."
19         }
20      ]
21   },
22   "capabilities":{
23      "content":{
24         "description":"Receipt for expenses",
25         "title":"receipt.pdf"
26      }
27   },
28   "feedElementType":"FeedItem",
29   "subjectId":"005RR000000DmOb"
30}
31
32--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
33Content-Disposition: form-data; name="feedElementFileUpload"; filename="receipt.pdf"
34Content-Type: application/octet-stream; charset=ISO-8859-1
35
36...contents of receipt.pdf...
37
38--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

Post a batch of feed elements with binary files

This example uses the /chatter/feed-elements/batch resource to post a batch of feed elements, uploads two binary files, and attach them to the feed elements in the batch. You must include the information about the binary parts in the request body. This example uses cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={"inputs":[{"binaryPartNames":["bin1"], "richInput":{"subjectId":"me","body":{
2"messageSegments":[{"type":"Text","text":"Please accept this receipt"}]},"capabilities": {"content" : {"description": "Receipt for expenses", "title":"receipt.pdf"}},"feedElementType":"FeedItem"}},
3{"binaryPartNames":["bin2"],"richInput":{"subjectId":"me","body":{"messageSegments":[{"type":"Text","text":"Post Number 2"}]},
4"capabilities": {"content" : {"description": "Receipt for expenses", "title":"receipt2.pdf"}},"feedElementType":"FeedItem"}}]};type=application/json' 
5-F "bin1=@/Users/jsmith/Desktop/receipt.pdf;type=application/octet-stream" -F "bin2=@/Users/jsmith/Desktop/receipt2.pdf;type=application/octet-stream" 
6-X POST https://instance_name/services/data/v35.0/chatter/feed-elements/batch 
7-H 'Authorization: OAuth 00DD00000007HoR44QATPNzhzYEJBfU' --insecure

This is the same example formatted to show the request body parts:

1POST /services/data/v35.0/chatter/feed-elements/batch HTTP/1.1
2Authorization: OAuth 00DRR0000000N0g!...
3User-Agent: Jakarta Commons-HttpClient/3.0.1
4Host: instance_name
5Content-Length: 845
6Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
7Accept: application/json
8
9--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
10Content-Disposition: form-data; name="json"
11Content-Type: application/json; charset=UTF-8
12
13{
14  "inputs": [
15    {
16      "binaryPartNames": [
17        "bin1"
18      ],
19      "richInput": {
20        "subjectId": "me",
21        "body": {
22          "messageSegments": [
23            {
24              "type": "Text",
25              "text": "Please accept this receipt"
26            }
27          ]
28        },
29        "capabilities": {
30          "content": {
31            "description": "Receipt for expenses",
32            "title": "receipt.pdf"
33          }
34        },
35        "feedElementType": "FeedItem"
36      }
37    },
38    {
39      "binaryPartNames": [
40        "bin2"
41      ],
42      "richInput": {
43        "subjectId": "me",
44        "body": {
45          "messageSegments": [
46            {
47              "type": "Text",
48              "text": "Post Number 2"
49            }
50          ]
51        },
52        "capabilities": {
53          "content": {
54            "description": "Receipt for expenses",
55            "title": "receipt2.pdf"
56          }
57        },
58        "feedElementType": "FeedItem"
59      }
60    }
61  ]
62}
63
64--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
65Content-Disposition: form-data; name="bin1"; filename="receipt.pdf"
66Content-Type: application/octet-stream; charset=ISO-8859-1
67
68...contents of receipt.pdf...
69
70
71--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
72Content-Disposition: form-data; name="bin2"; filename="receipt2.pdf"
73Content-Type: application/octet-stream; charset=ISO-8859-1
74
75...contents of receipt2.pdf...
76
77--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

The binary part names in the binaryPartNames properties must match the binary part names in the name properties of the binary request parts.

Note

Post a comment with a binary file

This example posts a comment to a feed item and uploads a binary attachment using cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={ "body":{ "messageSegments":[ { "type":"Text", "text":"Here's another receipt." } ] }, "capabilities":{ "content":{ "title":"receipt2" } } };
2type=application/json' -F "feedElementFileUpload=@receipt2.txt;type=application/octet-stream" 
3-X POST https://instance_name/services/data/v35.0/chatter/feed-elements/0D5RR0000004Grx/capabilities/comments/items 
4-H 'Authorization: OAuth 00DRR0000000N0g!ARoAQB...' --insecure

This is the sample example formatted to see the request body parts.

1POST /services/data/v35.0/chatter/feed-elements/0D5RR0000004Grx/capabilities/comments/items  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{
15   "body":{
16      "messageSegments":[
17         {
18            "type":"Text",
19            "text":"Here's another receipt."
20         }
21      ]
22   },
23   "capabilities":{
24      "content":{
25         "title":"receipt2"
26      }
27   }
28}
29
30--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI
31Content-Disposition: form-data; name="feedElementFileUpload"; filename="receipt2.txt"
32Content-Type: application/octet-stream; charset=ISO-8859-1
33
34...contents of receipt2.txt...
35
36--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI--

Post multiple comments with binary files

This example is a generic batch request to https://instance_name/services/data/v35.0/connect/batch that contains two subrequests. Each subrequest comments on a feed item and uploads a binary file to the comment.

You must include the request body of each subrequest in the richInput properties.

You must also include information about the binary parts in the binaryPartName and binaryPartNameAlias properties.

This is the cURL example:

1curl -H "X-PrettyPrint: 1" -F 'json={ "haltOnError":true, "batchRequests":[ { "url":"/v33.0/chatter/feed-elements/0D5D0000000YG0N/capabilities/comments/items", 
2"method":"Post", "binaryPartName":"binaryPart1", "binaryPartNameAlias":"feedElementFileUpload", "richInput":{ "body":{ "messageSegments":[ { "type":"Text", "text":"Check out this file, it may help." } ] },
3 "capabilities":{ "content":{ "title":"Presentation1.txt" } } } }, { "url":"/v33.0/chatter/feed-elements/0D5D0000000YG0M/capabilities/comments/items", 
4"method":"Post", "binaryPartName":"binaryPart2", "binaryPartNameAlias":"feedElementFileUpload", "richInput":{ "body":{ "messageSegments":[ { "type":"Text", "text":"Check out this file, it may help." } ] },
5 "capabilities":{ "content":{ "title":"Presentation2.txt" } } } } ] };type=application/json' -F "binaryPart1=@/Users/jbleyle/Desktop/Presentation1.txt;type=application/octet-stream" 
6-F "binaryPart2=@/Users/jbleyle/Desktop/Presentation2.txt;type=application/octet-stream" 
7-X POST https://instance_name/services/data/v35.0/connect/batch 
8-H 'Authorization: OAuth 00DD00000007HoR!...' --insecure

This is the multipart/form-data request body:

1https://instance_name/services/data/v35.0/connect/batch
2
3Authorization: OAuth 00DD0000000Jhd2!...
4Accept: application/json
5Host: instance_name
6Content-Type: multipart/form-data; boundary=123123
7
8--123123
9Content-Disposition: form-data; name="json"
10Content-Type: application/json
11
12{
13   "haltOnError":true,
14   "batchRequests":[
15      {
16         "url":"/v35.0/chatter/feed-elements/0D5D0000000YG0D/capabilities/comments/items",
17         "method":"Post",
18         "binaryPartName":"binaryPart1",
19         "binaryPartNameAlias":"feedElementFileUpload",
20         "richInput":{
21            "body":{
22               "messageSegments":[
23                  {
24                     "type":"Text",
25                     "text":"Check out this file, it may help."
26                  }
27               ]
28            },
29            "capabilities":{
30               "content":{
31                  "title":"Presentation1.txt"
32               }
33            }
34         }
35      },
36      {
37         "url":"/v35.0/chatter/feed-elements/0D5D0000000YG0H/capabilities/comments/items",
38         "method":"Post",
39         "binaryPartName":"binaryPart2",
40         "binaryPartNameAlias":"feedElementFileUpload",
41         "richInput":{
42            "body":{
43               "messageSegments":[
44                  {
45                     "type":"Text",
46                     "text":"Check out this file, it may help."
47                  }
48               ]
49            },
50            "capabilities":{
51               "content":{
52                  "title":"Presentation2.txt"
53               }
54            }
55         }
56      }
57   ]
58}
59
60
61--123123
62Content-Disposition: form-data; name="binaryPart1"; filename="Presentation1.txt"
63Content-Type: application/octet-stream; charset=ISO-8859-1
64Content-Transfer-Encoding: binary
65
66This is the content of file 1
67--123123
68Content-Disposition: form-data; name="binaryPart2"; filename="Presentation2.txt"
69Content-Type: application/octet-stream; charset=ISO-8859-1
70Content-Transfer-Encoding: binary
71
72This is the content of file 2
73--123123--

Post and crop a user photo

This example uploads a user profile photo and crops it using cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={"cropX": "0", "cropY": "0", "cropSize": "200"};type=application/json'
2 -F "fileUpload=@myPhoto.jpg;type=application/octet-stream" 
3-X POST https://instance_name/services/data/v35.0/chatter/users/me/photo
4 -H 'Authorization: OAuth 00DRR0000000N0g!ARoAQFRi_gBqZhajAX22MNuLrrE2Xk...'
5 --insecure

This is the same example formatted to see the request body parts.

1POST /services/data/v35.0/chatter/users/me/photo 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: 543
7Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
8Accept: application/json
9
10--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
11Content-Type: application/json; charset=UTF-8
12Content-Disposition: form-data; name="json"
13
14{
15   "cropX" : "0",
16   "cropY" : "0",
17   "cropSize" : "200"
18}
19
20--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
21Content-Disposition: form-data; name="fileUpload"; filename="myPhoto.jpg"
22Content-Type: application/octet-stream; charset=ISO-8859-1
23
24...contents of myPhoto.jpg...
25
26--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

Post a file to the Files list

This example uploads a file to the Files list using cURL.

1curl -H "X-PrettyPrint: 1" -F 'json={"title":"BoatPrices"};type=application/json' 
2-F "fileData=@BoatPrices.pdf;type=application/octet-stream" 
3-X POST https://instance_name/services/data/v35.0/chatter/users/me/files 
4-H 'Authorization: OAuth 00DRR0000000N0g!...' --insecure

This is the same example formatted to see the request body parts.

1POST /services/data/v35.0/chatter/users/me/files
2
3Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.
4OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyae
5User-Agent: Jakarta Commons-HttpClient/3.0.1
6Host: instance_name
7Content-Length: 489
8Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
9Accept: application/json
10
11--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
12Content-Type: application/json; charset=UTF-8
13Content-Disposition: form-data; name="json"
14
15{
16   "title":"BoatPrices"
17}
18
19--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
20Content-Disposition: form-data; name="fileData"; filename="BoatPrices.txt"
21Content-Type: application/octet-stream; charset=ISO-8859-1
22
23...contents of BoatPrices.txt...
24
25--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--

Chatter REST API Developer's Guide

Using Chatter REST API Inputs

Using POST, PATCH, or PUT for Input

Uploading Binary Files