Файлы и альбомы

Собеседник прислал фото, видео, документ, голосовое, аудио или стикер. Gratio сразу забирает файл к себе и даёт на него постоянную ссылку downloadUrl: ссылки самих мессенджеров временные.

Пример

Мария прислала в MAX заполненную анкету:

{
  "typeWebhook": "incomingMessageReceived",
  "instanceData": {"idInstance": 7100000001, "wid": "79990000001@c.us", "typeInstance": "v3", "channel": "max"},
  "timestamp": 1791823745,
  "idMessage": "117428960974949548",
  "eventId": "msg:8695836:117428960974949548",
  "senderData": {
    "chatId": "8695836", "chatName": "Мария", "chatType": "user",
    "sender": "8695836", "senderName": "Мария", "senderType": "user",
    "senderContactName": "", "senderPhoneNumber": 0
  },
  "messageData": {
    "typeMessage": "documentMessage",
    "fileMessageData": {
      "downloadUrl": "https://api.gratio.net/media/7100000001/8695836/117428960974949548/0/d8f9…",
      "caption": "Заполнила анкету",
      "fileName": "Анкета.pdf",
      "jpegThumbnail": "",
      "isAnimated": false,
      "mimeType": "application/pdf",
      "forwardingScore": 0,
      "isForwarded": false
    }
  }
}

Поля

Ссылка не истекает, ответ — сам файл с его Content-Type; неверная подпись — 404. Важные файлы сохраняйте у себя. Подробно — в статье Файлы и ссылки на них.

Остальные поля конверта — в статье Формат уведомления.

Виды файлов

Голосовое — это audioMessage. Отдельного вида для голосовых нет: у голосового обычно тип audio/ogg и нет своего имени файла.

Голосовое

Мария записала голосовое в Telegram:

"messageData": {
  "typeMessage": "audioMessage",
  "fileMessageData": {
    "downloadUrl": "https://api.gratio.net/media/7100000001/8617393401/4815/0/7c2e…",
    "caption": "", "fileName": "4815.ogg", "jpegThumbnail": "", "isAnimated": false,
    "mimeType": "audio/ogg", "forwardingScore": 0, "isForwarded": false
  }
}

Альбом

Несколько файлов в одном сообщении: первый — в fileMessageData, остальные — в additionalFiles, у каждого свой typeMessage и своя ссылка. Номер файла — в ссылке после idMessage: /0/, /1/, /2/. Мария прислала в MAX два фото и видео с занятия:

"messageData": {
  "typeMessage": "imageMessage",
  "fileMessageData": {
    "downloadUrl": "https://api.gratio.net/media/7100000001/8695836/117428961523847166/0/41b7…",
    "caption": "Фото с занятия", "fileName": "117428961523847166.jpg", "jpegThumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD…",
    "isAnimated": false, "mimeType": "image/jpeg", "forwardingScore": 0, "isForwarded": false
  },
  "additionalFiles": [
    {
      "typeMessage": "imageMessage",
      "downloadUrl": "https://api.gratio.net/media/7100000001/8695836/117428961523847166/1/9be0…",
      "caption": "Фото с занятия", "fileName": "117428961523847166.jpg", "jpegThumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD…",
      "isAnimated": false, "mimeType": "image/jpeg", "forwardingScore": 0, "isForwarded": false
    },
    {
      "typeMessage": "videoMessage",
      "downloadUrl": "https://api.gratio.net/media/7100000001/8695836/117428961523847166/2/3a61…",
      "caption": "Фото с занятия", "fileName": "117428961523847166.mp4", "jpegThumbnail": "",
      "isAnimated": false, "mimeType": "video/mp4", "forwardingScore": 0, "isForwarded": false
    }
  ]
}

Подпись альбома повторяется у каждого файла. Альбомы одним сообщением присылают MAX и почта (письмо с несколькими вложениями). В Telegram и WhatsApp каждый файл альбома — отдельное сообщение и отдельное уведомление.

В других каналах

В группе chatId — группа, sender — участник, как у текстового сообщения (см. Текст). В ссылке на файл — адрес чата во внутренней форме: у WhatsApp без суффикса @c.us.

Как обработать

Скачать все файлы сообщения, в том числе альбом:

import requests


def files_of(data: dict) -> list[dict]:
    """Все файлы сообщения: первый и остальные файлы альбома."""
    first = data.get("fileMessageData")
    if first is None:
        return []
    return [{"typeMessage": data["typeMessage"], **first}, *data.get("additionalFiles", [])]


def save_files(body: dict) -> None:
    for i, f in enumerate(files_of(body["messageData"])):
        r = requests.get(f["downloadUrl"], timeout=120)  # без токена: ссылка подписанная
        r.raise_for_status()
        with open(f"{body['idMessage']}-{i}-{f['fileName']}", "wb") as out:
            out.write(r.content)

Что дальше

• Файлы и ссылки на них — хранение, пределы, типы.
• sendFileByUpload — отправить файл в ответ.
• downloadFile — ссылка на файл старого сообщения.