Attachments
When you want to send files through the API, such as when using the Create draft or similar API endpoints, you must set the Content-Type HTTP header set to multipart/form-data
. You then split the JSON data that you normally send in the request body into multiple form fields (one for each property) named after the property key.
Many but not all Core API endpoints support sending attachments. Refer to the Core API Reference documentation for details.
Basic example: make sure the Content-Type header is set to multipart/form-data
curl -X POST 'https://api2.frontapp.com/inboxes/inb_123/imported_messages' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: multipart/form-data' \
--form 'external_id=123456abcdef' \
--form 'created_at=1619656054' \
--form 'attachments[]=@/Users/me/Photos/cat.jpg' \
Arrays in multipart form data
Some API body parameters must be sent as an array. For example, the to
parameter or the attachments
array itself. In these cases, you split the array into multiple form fields. For example, {"to": [[email protected], [email protected]]}
would be split in two fields named to[][email protected]
and to[][email protected]
).
curl -X POST 'https://api2.frontapp.com/channels/FRONT_CHANNEL_ID/messages' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: multipart/form-data' \
--form 'author_id=AUTHOR_ID' \
--form 'to[][email protected]' \
--form 'to[][email protected]' \
--form 'attachments[]=@/Users/me/Photos/cat.jpg' \
--form 'attachments[]=@/Users/me/Photos/dog.jpg' \
--form 'body=MESSAGE_BODY'
Nested objects in multipart form data
Some API body parameters are nested within objects, such as name
and handle
in the sender
object:
"sender": {
"name": "Lucy",
"handle": "[email protected]"
}
In these cases, split the parameters into multiple form fields and use the syntax, objectName[propertyName]
for the name of the form field. In our sender
example, the fields would be named sender[handle]
and sender[name]
.
curl -X POST 'https://api2.frontapp.com/inboxes/inb_123/imported_messages' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: multipart/form-data' \
--form 'external_id=lj19hkjjlsd9893d' \
--form 'created_at=1619656054' \
--form 'sender[handle][email protected]' \
--form 'sender[name]=Lucy' \
--form 'metadata[is_inbound]=true' \
--form 'metadata[is_archived]=false' \
--form 'to[][email protected]' \
--form 'to[][email protected]' \
--form 'body=MESSAGE_BODY' \
--form 'attachments[]=@/Users/me/Photos/cat.jpg' \
--form 'attachments[]=@/Users/me/Photos/dog.jpg'
Node examples
The following provides an example for Node. We also have examples in GitHub for sending an attachment when creating a new message and for receiving messages in a custom channel.
const FRONT_API_TOKEN = 'YOUR FRONT API TOKEN GOES HERE';
const CHANNEL_ID = 'YOUR FRONT CHANNEL ID GOES HERE';
const FormData = require('form-data');
const fs = require('fs');
// abstract and promisify actual network request
async function makeRequest(formData, options) {
return new Promise((resolve, reject) => {
const req = formData.submit(options, (err, res) => {
if (err)
return reject(new Error(err.message))
if (res.statusCode < 200 || res.statusCode > 299)
return reject(new Error(`HTTP status code ${res.statusCode}`))
const body = [];
res.on('data', (chunk) => body.push(chunk));
res.on('end', () => {
const resString = Buffer.concat(body).toString();
resolve(resString);
})
})
})
}
const formData = new FormData()
// Set your data here: (See full options at https://dev.frontapp.com/reference/messages-1#post_channels-channel-id-messages)
formData.append('subject', 'Message subject');
formData.append('to[]', '[email protected]');
formData.append('to[]', '[email protected]');
formData.append('sender_name', 'Support');
formData.append('body', '<p>Message body</p>');
formData.append('attachments[]', fs.createReadStream('./photo.jpg'));
const options = {
host: 'api2.frontapp.com',
path: `/channels/${CHANNEL_ID}/messages`,
method: 'POST',
protocol: 'https:', // note : in the end
headers: {
Authorization: `Bearer ${FRONT_API_TOKEN}`
},
}
async function run() {
const res = await makeRequest(formData, options);
console.log(res);
}
run()
Download an attachment from the API
For information about downloading attachments received in API responses, refer to the reference topic and the Download attachment endpoint.
Updated 5 months ago