Attachments
Attachments are how you share things in Protocol — they allow you to send all sorts of files to your contacts and groups. On this page, we'll dive into the different attachment endpoints you can use to manage attachments programmatically. We'll look at how to query, upload, update, and delete attachments.
The attachment model
The attachment model contains all the information about the files you send to your contacts and groups, including the name, type, and size.
Properties
-
- Name
id- Type
- string
- Description
-
Unique identifier for the attachment.
-
- Name
message_id- Type
- string
- Description
-
Unique identifier for the message associated with the attachment.
-
- Name
filename- Type
- string
- Description
-
The filename for the attachment.
-
- Name
file_url- Type
- string
- Description
-
The URL for the attached file.
-
- Name
file_type- Type
- string
- Description
-
The MIME type of the attached file.
-
- Name
file_size- Type
- integer
- Description
-
The file size of the attachment in bytes.
-
- Name
created_at- Type
- timestamp
- Description
-
Timestamp of when the attachment was created.
List all attachments
This endpoint allows you to retrieve a paginated list of all your attachments (in a conversation if a conversation id is provided). By default, a maximum of ten attachments are shown per page.
Optional attributes
-
- Name
conversation_id- Type
- string
- Description
-
Limit to attachments from a given conversation.
-
- Name
limit- Type
- integer
- Description
-
Limit the number of attachments returned.
Request
curl -G https://api.protocol.chat/v1/attachments \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d limit=10
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.attachments.list()
from protocol_api import ApiClient
client = ApiClient(token)
client.attachments.list()
$client = new \Protocol\ApiClient($token);
$client->attachments->list();
Response
{
"has_more": false,
"data": [
{
"id": "l7cGNIBKZiNJ6wqF"
"message_id": "LoPsJaMcPBuFNjg1",
"filename": "Invoice_room_service__Plaza_Hotel.pdf",
"file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf",
"file_type": "application/pdf",
"file_size": 21352,
"created_at": 692233200
},
{
"id": "hSIhXBhNe8X1d8Et"
// ...
}
]
}
Create an attachment
This endpoint allows you to upload a new attachment to a conversation. See the code examples for how to send the file to the Protocol API.
Required attributes
-
- Name
file- Type
- string
- Description
-
The file you want to add as an attachment.
Request
curl https://api.protocol.chat/v1/attachments \
-H "Authorization: Bearer {token}" \
-F file="../Invoice_room_service__Plaza_Hotel.pdf"
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.attachments.create({ file })
from protocol_api import ApiClient
client = ApiClient(token)
client.attachments.create(file=file)
$client = new \Protocol\ApiClient($token);
$client->attachments->create([
'file' => $file,
]);
Response
{
"id": "l7cGNIBKZiNJ6wqF"
"message_id": "LoPsJaMcPBuFNjg1",
"filename": "Invoice_room_service__Plaza_Hotel.pdf",
"file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf",
"file_type": "application/pdf",
"file_size": 21352,
"created_at": 692233200
}
Retrieve an attachment
This endpoint allows you to retrieve an attachment by providing the attachment id. Refer to the list at the top of this page to see which properties are included with attachment objects.
Request
curl https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
-H "Authorization: Bearer {token}" \
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.attachments.get('Nc6yKKMpcxiiFxp6')
from protocol_api import ApiClient
client = ApiClient(token)
client.attachments.get("Nc6yKKMpcxiiFxp6")
$client = new \Protocol\ApiClient($token);
$client->attachments->get('Nc6yKKMpcxiiFxp6');
Response
{
"id": "l7cGNIBKZiNJ6wqF"
"message_id": "LoPsJaMcPBuFNjg1",
"filename": "Invoice_room_service__Plaza_Hotel.pdf",
"file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf",
"file_type": "application/pdf",
"file_size": 21352,
"created_at": 692233200
}
Update an attachment
This endpoint allows you to perform an update on an attachment. Currently, the only supported type of update is changing the filename.
Optional attributes
-
- Name
filename- Type
- string
- Description
-
The new filename for the attachment.
Request
curl -X PUT https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
-H "Authorization: Bearer {token}" \
-d filename="Invoice_room_service__Plaza_Hotel_updated.pdf"
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.attachments.update('Nc6yKKMpcxiiFxp6', {
filename: 'Invoice_room_service__Plaza_Hotel_updated.pdf',
})
from protocol_api import ApiClient
client = ApiClient(token)
client.attachments.update("Nc6yKKMpcxiiFxp6", filename="Invoice_room_service__Plaza_Hotel_updated.pdf")
$client = new \Protocol\ApiClient($token);
$client->messages->update('Nc6yKKMpcxiiFxp6', [
'filename' => 'Invoice_room_service__Plaza_Hotel_updated.pdf',
]);
Response
{
"id": "l7cGNIBKZiNJ6wqF"
"message_id": "LoPsJaMcPBuFNjg1",
"filename": "Invoice_room_service__Plaza_Hotel.pdf",
"file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf",
"file_type": "application/pdf",
"file_size": 21352,
"created_at": 692233200
}
Delete an attachment
This endpoint allows you to delete attachments. Note: This will permanently delete the file.
Request
curl -X DELETE https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
-H "Authorization: Bearer {token}"
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.attachments.delete('Nc6yKKMpcxiiFxp6')
from protocol_api import ApiClient
client = ApiClient(token)
client.attachments.delete("Nc6yKKMpcxiiFxp6")
$client = new \Protocol\ApiClient($token);
$client->attachments->delete('Nc6yKKMpcxiiFxp6');