Files & Attachments

A message carries up to 10 attachments of any type, each up to 10 MiB. The bot needs AttachFiles in the channel on top of SendMessages. There are two ways to hand the files over:

Only IMessages/Send takes attachments; IInteractions/Reply does not. Sticker and emoji files go through the same IFiles/Upload with another purpose — see Stickers & Custom Emoji → Files.

POST /IFiles/v1/Upload is a multipart/form-data request with a file part and purpose=attachment. Any type is taken, up to 10 MiB. The part's file name and Content-Type are kept as the attachment's fileName and contentType (application/octet-stream when the part declares none).

curl -X POST \
     -H "Authorization: Bot YOUR_TOKEN" \
     -F "purpose=attachment" \
     -F "[email protected];type=application/pdf" \
     https://gateway.argon.zone/IFiles/v1/Upload

{
  "fileId": "5f1d0c3a-...",
  "size": 482113,
  "contentType": "application/pdf",
  "url": ".../files/5f1d0c3a-...",
  "fileName": "report.pdf"
}

Name the uploads in the attachments list of an ordinary JSON IMessages/v1/Send. Only uploads of this bot with purpose attachment are taken; a sticker or emoji upload is 404 not_found here.

curl -X POST \
     -H "Authorization: Bot YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"channelId":"c0ffee00-...","text":"Weekly report","randomId":7311,"attachments":["5f1d0c3a-..."]}' \
     https://gateway.argon.zone/IMessages/v1/Send

{
  "messageId": 42,
  "attachments": [
    {
      "fileId": "5f1d0c3a-...",
      "url": ".../files/5f1d0c3a-...",
      "fileName": "report.pdf",
      "size": 482113,
      "contentType": "application/pdf",
      "width": null,
      "height": null
    }
  ]
}

The response describes every attachment in the order given (BotAttachmentV1), so the bot has the file URLs without reading the message back.

IMessages/v1/Send also takes multipart/form-data with the same fields. Every field is a text part; entities and controls are one field holding their JSON. The attachments field is repeated once per file, and each file can be given three ways:

curl -X POST \
     -H "Authorization: Bot YOUR_TOKEN" \
     -F "channelId=c0ffee00-..." \
     -F "text=Chart, report and raw data" \
     -F "randomId=7312" \
     -F "attachments=attach://chart" \
     -F "attachments=5f1d0c3a-..." \
     -F "[email protected];type=image/png" \
     -F "[email protected];type=text/csv" \
     https://gateway.argon.zone/IMessages/v1/Send

The text fields come first in the message, in their order, then the parts named attachments: the example sends chart.png, the uploaded report and data.csv. A part sent this way does not count against the 100 unused uploads.

Messages carry their files as attachments — in GET /IMessages/v1/History, in the messageCreate event and in the Send response — whoever sent them. On a message without files it is null (an empty list in the Send response).

{
  "spaceId": "aaaabbbb-...",
  "channelId": "c0ffee00-...",
  "message": {
    "messageId": 44,
    "text": "This week's chart",
    "attachments": [
      {
        "fileId": "9e8d7c6b-...",
        "url": ".../files/9e8d7c6b-...",
        "fileName": "chart.png",
        "size": 48211,
        "contentType": "image/png",
        "width": 1200,
        "height": 800
      }
    ]
  }
}

The message's attachment entities describe the same files and carry the same url — see Message Entities. Read attachments; it is the simpler of the two.

Besides the refusals every message can get (cannot_send, slow_mode, …), a message with files, or an upload, can be refused with these. Nothing is sent when one of them comes back.

Branch on the error code, not the status — see Error Handling.