Новое сообщение

POST/messages

Отправляет сообщение в беседу или канал, личное сообщение пользователю или комментарий в тред.

С entity_type: "discussion" — это значение по умолчанию — в entity_id можно передать chat_id любого чата, так что для отправки достаточно знать идентификатор чата. Сообщение в тред можно адресовать и идентификатором самого треда, а личное — идентификатором пользователя, но тогда нужен соответствующий entity_type: thread или user.

Личный чат для этого создавать не требуется: он появится сам, если между вами ещё не было переписки. Между двумя пользователями может быть только один личный чат. Со своим собственным идентификатором сообщение уйдёт в чат с самим собой, где пишут заметки себе. С токеном бота это чат, где состоит только сам бот: его не видит ни один сотрудник.

Тред, в отличие от личного чата, сам не появляется: если у сообщения треда ещё нет, его сначала создают методом POSTНовый тред.

Подписчик канала пишет только в тредах его сообщений, а в сам канал метод отвечает ему 403. Кто где может писать — в разделе Права и роли.

Текст в поле content разбирается как markdown: жирный, курсив, зачёркнутый, строчный код, блок кода и ссылки. Списки и таблицы не разбираются — -, 1. и | остаются как есть, у цитаты пропадает >, а строка с решёткой и пробелом становится жирной. Таблицу, чек-лист или диаграмму приложите файлом .md: Пачка показывает такой файл оформленным, а если он единственный документ в сообщении, его начало видно прямо в чате. Подробности — в разделе Форматирование текста.

К сообщению можно приложить не больше 10 файлов. Превью ссылки строится, только если передать link_preview в корне тела запроса.

Действуют лимиты на частоту отправки и суточный предел на число сообщений в один чат от одного отправителя. При превышении любого из них метод отвечает 429, а в заголовке Retry-After приходит пауза до следующей попытки. Значения пределов — в разделе Лимиты.

Тело запроса

application/json

Собранный объект параметров создаваемого сообщения

Тип сущности. Регистр значения не учитывается. Значение вне списка возвращает 400 с кодом invalid.

Возможные значения

Пример:discussion

По умолчанию:

discussion

Идентификатор того, что названо в entity_type: беседы или канала, треда либо пользователя. У треда их два: id треда указывают с entity_type: "thread", а его chat_id — с discussion, как у любого чата.

Пример:334

Текст сообщения. Обязателен, если к сообщению не приложены файлы. Поддерживает упоминания: @nickname или <@user_id> (будет автоматически преобразовано в @nickname). @all упоминает всех участников чата, @here — тех, кто сейчас в сети, а @ с названием тега без пробелов — сотрудников этого тега. Имя без @ и упоминание внутри строчного кода или блока кода упоминанием не считаются. У мульти-гостя <@user_id> недоступного ему сотрудника остаётся в тексте как есть. До 40 000 байт в UTF-8, для кириллицы это около 20 000 символов. В пространстве с продвинутым шифрованием — до 27 000 байт. Сообщение уходит под именем владельца токена, у бота — с бейджем «Бот».

Пример:

Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)

Прикрепляемые файлы

Количество:

<= 10 элементов

Путь к файлу, полученный в методе POSTЗагрузка файла

Пример:attaches/files/93746/e354fd79-4f3e-4b5a-9c8d-1a2b3c4d5e6f/logo.png

Длина:

<= 1000 символов

Название файла, которое вы хотите отображать пользователю. Расширение должно совпадать с расширением файла в key, иначе ответ будет 422 с кодом wrong_params.

Пример:logo.png

Длина:

<= 255 символов

Тип файла

Возможные значения

Пример:image

Размер файла в байтах, отображаемый пользователю

Пример:12345

Ширина изображения в px (используется в случае, если file_type указан как image)

Пример:800

Высота изображения в px (используется в случае, если file_type указан как image)

Пример:600

Длительность в миллисекундах. Обязательно для голосовых сообщений (file_type — voice), для других типов не используется. Голосовое сообщение длиннее 30 минут (1 800 000 мс) отклоняется с 422.

Пример:5400

Диапазон:

>= 1

Форма волны для визуализации голосового сообщения. Обязательно для голосовых сообщений (file_type — voice), для других типов не используется.

Пример:4,8,12,20,16,10,6,3

Длина:

<= 256 символов

Массив строк, каждая из которых представлена массивом кнопок. Максимум 100 кнопок у сообщения, до 8 кнопок в строке. Кнопки показываются под текстом и работают только у сообщений, отправленных токеном бота: нажатие на кнопку с data приходит событием button_click тому самому боту, а вместе с ним trigger_id — на открытие формы по нему есть 3 секунды, метод POSTОткрытие представления. Кнопка с url просто ведёт по ссылке и события не создаёт. Подробности — в разделе Кнопки.

Пример:[[{"text":"Подробнее","url":"https://example.com/details"},{"text":"Отлично!","data":"awesome"}]]

Количество:

<= 32 элементов

Ряд кнопок

Количество:1 — 8 элементов

Текст, отображаемый на кнопке

Пример:Подробнее

Длина:

<= 255 символов

Ссылка, которая будет открыта по нажатию кнопки. У кнопки должно быть заполнено ровно одно из полей url и data.

Пример:https://example.com/details

Длина:

<= 1024 символов

Данные, которые будут отправлены в исходящем вебхуке по нажатию кнопки. У кнопки должно быть заполнено ровно одно из полей url и data.

Пример:awesome

Длина:

<= 255 символов

Идентификатор сообщения, на которое вы отвечаете с цитатой. Ответить можно на сообщение в любом чате, в том числе в треде: ответ отправляют в тот же чат или тред, где лежит это сообщение, иначе запрос вернёт ошибку 422. Чтобы написать в тред под сообщением, укажите entity_type: "thread" и id треда в entity_id.

Пример:194270

Ссылка на специальную аватарку отправителя для этого сообщения. Использование этого поля возможно только с access_token бота.

Пример:https://example.com/avatar.png

Длина:

<= 255 символов

Полное специальное имя отправителя для этого сообщения. Вместе с display_avatar_url бот подписывает сообщение чужим именем и аватаром, и только это сообщение. Бейдж «Бот» остаётся, а в профиле отправителя видно настоящего бота. Так показывают автора из другой системы, когда переносят в Пачку чужую переписку. С личным токеном поле недоступно, ответ 403. Подробности — в разделе Боты.

Пример:Бот Поддержки

Длина:

<= 255 символов

Пропуск добавления упомянутых сотрудников в тред. В треде упоминание работает ещё и как приглашение: упомянутого сотрудника, которого в треде нет, Пачка туда добавляет, и он получает доступ к треду и родительскому сообщению. В беседе и канале упоминание никого не добавляет, и этот параметр там ничего не меняет.

Пример:false

По умолчанию:

false

Отображение предпросмотра первой найденной ссылки в тексте сообщения

Пример:false

По умолчанию:

false

Ответ

201Created

The request has succeeded and a new resource has been created as a result.

Сообщение

Идентификатор сообщения

Пример:194275

Тип сущности, к которой относится сообщение

Возможные значения

Пример:discussion

Идентификатор сущности, к которой относится сообщение (беседы/канала, треда или пользователя)

Пример:334

Идентификатор чата, в котором находится сообщение

Пример:334

Идентификатор корневого чата. Для сообщений в тредах — идентификатор чата, в котором был создан тред. Для обычных сообщений совпадает с chat_id.

Пример:334

Текст сообщения

Пример:

Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)

Идентификатор пользователя, создавшего сообщение

Пример:12

Дата и время создания сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ

Пример:2021-08-28T15:57:23.000Z

Прямая ссылка на сообщение

Пример:https://app.pachca.com/chats/334?message=194275

Прикрепленные файлы

Идентификатор файла

Пример:3560

Путь к файлу

Пример:attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png

Название файла с расширением

Пример:congrat.png

Тип файла

Возможные значения

Пример:image

Ссылка на скачивание файла. Обычно ведёт прямо в хранилище и действует до 7 дней, а оставшийся срок может быть меньше — если такая ссылка вернула 403, запросите сообщение заново и получите свежую. Если в пространстве включено шифрование или задан безопасный контур, ссылка ведёт на GETСкачивание файла: забирать такой файл нужно с заголовком Authorization, а токену нужен скоуп files:read.

Пример:

https://files.example.com/attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png?X-Amz-Expires=604800&X-Amz-Signature=98765asgfadsfdSaDSd4sdfg35asdf67sadf8

Ширина изображения в пикселях. null для файлов, не являющихся изображением, а также если размер не был передан при загрузке.

Пример:1920

Высота изображения в пикселях. null для файлов, не являющихся изображением, а также если размер не был передан при загрузке.

Пример:1080

Длительность в миллисекундах у голосового, аудио- и видеофайла. null у остальных файлов и если длительность не была передана при загрузке.

Пример:5400

Данные голосового сообщения. Заполняется только для голосовых сообщений (file_type файла — voice), иначе null.

Длительность голосового сообщения в миллисекундах

Пример:5400

Форма волны (амплитуды) для визуализации голосового сообщения

Пример:4,8,12,20,16,10,6,3

Расшифровка голосового сообщения в текст. null, пока расшифровка не готова или недоступна.

Пример:Привет, посмотри пожалуйста последний отчёт

Массив строк, каждая из которых представлена массивом кнопок. null, если сообщение отправлено без кнопок.

Текст, отображаемый на кнопке

Пример:Подробнее

Длина:

<= 255 символов

Ссылка, которая будет открыта по нажатию кнопки. У кнопки должно быть заполнено ровно одно из полей url и data.

Пример:https://example.com/details

Длина:

<= 1024 символов

Пример:awesome

Длина:

<= 255 символов

Тред, созданный к этому сообщению. null, если тред не создан, а также у сообщений, которые сами находятся внутри треда.

Идентификатор треда. Чтобы написать в тред, передайте его в entity_id метода POSTНовое сообщение с entity_type: "thread".

Пример:265142

Идентификатор чата треда. По нему читают сообщения треда методом GETСписок сообщений чата.

Пример:2637266155

Информация о пересланном сообщении. null, если сообщение не является пересланным.

Идентификатор оригинального сообщения

Пример:194275

Идентификатор чата, в котором находится оригинальное сообщение

Пример:334

Идентификатор пользователя, создавшего оригинальное сообщение

Пример:12

Дата и время создания оригинального сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ

Пример:2025-01-15T10:30:00.000Z

Идентификатор треда, в котором находится оригинальное сообщение

Пример:null

Идентификатор сообщения, к которому был создан тред, в котором находится оригинальное сообщение. null, если оригинальное сообщение было не в треде или тред создан без привязки к сообщению.

Пример:null

Идентификатор чата сообщения, к которому был создан тред, в котором находится оригинальное сообщение. null, если оригинальное сообщение было не в треде или тред создан без привязки к сообщению.

Пример:null

Идентификатор сообщения, к которому написан ответ. null, если сообщение не является ответом на другое сообщение.

Пример:null

Ссылка на аватарку отправителя сообщения. Поле присутствует только у сообщений от ботов; у сообщений от сотрудников его в ответе нет. null, если бот не переопределял значение при отправке.

Пример:null

Полное имя отправителя сообщения. Поле присутствует только у сообщений от ботов; у сообщений от сотрудников его в ответе нет. null, если бот не переопределял значение при отправке.

Пример:null

Дата и время последнего изменения сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. У неотредактированного сообщения совпадает с датой создания. null у сообщений, отправленных до появления этого поля.

Пример:2021-08-28T16:10:00.000Z

Дата и время удаления сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. null у неудалённых сообщений. В списке сообщений удалённые не возвращаются.

Пример:null

Новое сообщение

pachca messages create \  --entity-id=334 \  --content='Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)' \  --files='[{"key":"attaches/files/93746/e354fd79-4f3e-4b5a-9c8d-1a2b3c4d5e6f/logo.png","name":"logo.png","file_type":"image","size":12345,"width":800,"height":600,"duration_ms":5400,"waveform":"4,8,12,20,16,10,6,3"}]' \  --buttons='[[{"text":"Подробнее","url":"https://example.com/details"},{"text":"Отлично!","data":"awesome"}]]' \  --parent-message-id=194270 \  --display-avatar-url=https://example.com/avatar.png \  --display-name='Бот Поддержки' \  --json \  --token YOUR_ACCESS_TOKEN

Ответ 201

{  "data": {    "id": 194275,    "entity_type": "discussion",    "entity_id": 334,    "chat_id": 334,    "root_chat_id": 334,    "content": "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)",    "user_id": 12,    "created_at": "2021-08-28T15:57:23.000Z",    "url": "https://app.pachca.com/chats/334?message=194275",    "files": [      {        "id": 3560,        "key": "attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png",        "name": "congrat.png",        "file_type": "image",        "url": "https://files.example.com/attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png?X-Amz-Expires=604800&X-Amz-Signature=98765asgfadsfdSaDSd4sdfg35asdf67sadf8",        "width": 1920,        "height": 1080,        "duration_ms": 5400      }    ],    "voice_content": {      "duration_ms": 5400,      "waveform": "4,8,12,20,16,10,6,3",      "transcript": "Привет, посмотри пожалуйста последний отчёт"    },    "buttons": [      [        {          "text": "Подробнее",          "url": "https://example.com/details",          "data": "awesome"        }      ]    ],    "thread": {      "id": 265142,      "chat_id": 2637266155    },    "forwarding": {      "original_message_id": 194275,      "original_chat_id": 334,      "author_id": 12,      "original_created_at": "2025-01-15T10:30:00.000Z",      "original_thread_id": null,      "original_thread_message_id": null,      "original_thread_parent_chat_id": null    },    "parent_message_id": null,    "display_avatar_url": null,    "display_name": null,    "changed_at": "2021-08-28T16:10:00.000Z",    "deleted_at": null  }}