Attachments

Attachments are how you share things in CityPay — 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

    Attributes

GET/v1/attachments

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

    Attributes

Request

GET
/v1/attachments
curl -G https://api.protocol.chat/v1/attachments \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "Nc6yKKMpcxiiFxp6",
      "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"
      // ...
    }
  ]
}
POST/v1/attachments

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 CityPay API.

Required attributes

    Attributes

Request

POST
/v1/attachments
curl https://api.protocol.chat/v1/attachments \
  -H "Authorization: Bearer {token}" \
  -F file="../Invoice_room_service__Plaza_Hotel.pdf"

Response

{
  "id": "Nc6yKKMpcxiiFxp6",
  "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
}
GET/v1/attachments/:id

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

GET
/v1/attachments/Nc6yKKMpcxiiFxp6
curl https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "Nc6yKKMpcxiiFxp6",
  "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
}
PUT/v1/attachments/:id

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

    Attributes

Request

PUT
/v1/attachments/Nc6yKKMpcxiiFxp6
curl -X PUT https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
  -H "Authorization: Bearer {token}" \
  -d filename="Invoice_room_service__Plaza_Hotel_updated.pdf"

Response

{
  "id": "Nc6yKKMpcxiiFxp6",
  "message_id": "LoPsJaMcPBuFNjg1",
  "filename": "Invoice_room_service__Plaza_Hotel.pdf",
  "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel_updated.pdf",
  "file_type": "application/pdf",
  "file_size": 21352,
  "created_at": 692233200
}
DELETE/v1/attachments/:id

Delete an attachment

This endpoint allows you to delete attachments. Note: This will permanently delete the file.

Request

DELETE
/v1/attachments/Nc6yKKMpcxiiFxp6
curl -X DELETE https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
  -H "Authorization: Bearer {token}"