Для разработчиков

Список закреплённых сообщений

GET/chats/{id}/pinned_messages

Сообщения, закреплённые в шапке беседы, канала или личной переписки, от последних закреплённых к ранним, как в шапке чата в интерфейсе. Закрепляют и открепляют методами POSTЗакрепление сообщения и DELETEОткрепление сообщения.

Сообщения приходят в том же виде, что в методе GETСписок сообщений чата. Удалённое сообщение из списка пропадает. Архивный чат тоже отдаёт свои закреплённые сообщения. В тредах сообщения не закрепляют, поэтому для треда список всегда пустой.

Доступ такой же, как к ленте чата: чаты, где владелец токена состоит, и открытые чаты пространства. Мульти-гостю открыты только чаты, где он состоит. Владелец пространства в закрытый чат без членства не попадает. Закрытый чат и недоступный тред отвечают 403, а чат другого пространства и неизвестный идентификатор отвечают 404.

Параметры пути

id
integer, (int32)
*
Идентификатор чата (беседы, канала или личного чата)
Пример:334

Параметры строки запроса

limit
integer, (int32)
Количество возвращаемых сущностей за один запрос. Целое число вне допустимых значений заменяется ближайшей границей.
Пример:25
По умолчанию:
50
Диапазон:
1 — 50
cursor
string
Курсор для пагинации (из meta.paginate.next_page или meta.paginate.prev_page)
Пример:eyJpZCI6MTAsImRpciI6ImFzYyJ9

Ответ

200OK
The request has succeeded.
data[]
array of objects
*
id
integer, (int32)
*
Идентификатор сообщения
Пример:194275
entity_type
string
*
Тип сущности, к которой относится сообщение
Возможные значения
Пример:discussion
entity_id
integer, (int32)
*
Идентификатор сущности, к которой относится сообщение (беседы/канала, треда или пользователя)
Пример:334
chat_id
integer, (int32)
*
Идентификатор чата, в котором находится сообщение
Пример:334
root_chat_id
integer, (int32)
*
Идентификатор корневого чата. Для сообщения в треде — идентификатор чата, где находится родительское сообщение треда. У самостоятельного треда родительского сообщения нет, и root_chat_id совпадает с chat_id, как у обычных сообщений. Сообщение треда узнают по entity_type: "thread".
Пример:334
content
string
*
Текст сообщения. Пустая строка, если текста нет: например, у сообщения из одних вложений или у стикера. Сам стикер API не отдаёт, такое сообщение приходит с пустым files, а отправить стикер через API нельзя.
Пример:Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)
user_id
integer, (int32)
*
Идентификатор пользователя, создавшего сообщение
Пример:12
created_at
string, (date-time)
*
Дата и время создания сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ
Пример:2021-08-28T15:57:23.000Z
url
string
*
Прямая ссылка на сообщение
Пример:https://app.pachca.com/chats/334?message=194275
files[]
array of objects
*
Прикрепленные файлы
id
integer, (int32)
*
Идентификатор файла
Пример:3560
key
string
*
Путь к файлу
Пример:attaches/files/12/21zu7934-02e1-44d9-8df2-0f970c259796/congrat.png
name
string
*
Название файла с расширением
Пример:congrat.png
file_type
string
*
Тип файла
Возможные значения
Пример:image
url
string
*
Ссылка на скачивание файла. Обычно ведёт прямо в хранилище и действует до 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
width
nullableinteger, (int32)
Ширина изображения в пикселях. null для файлов, не являющихся изображением, а также если размер не был передан при загрузке.
Пример:1920
height
nullableinteger, (int32)
Высота изображения в пикселях. null для файлов, не являющихся изображением, а также если размер не был передан при загрузке.
Пример:1080
duration_ms
nullableinteger, (int32)
Длительность в миллисекундах у голосового сообщения и видеофайла. null у остальных файлов и если длительность не была передана при загрузке.
Пример:5400
voice_content
nullableobject
*
Данные голосового сообщения. Заполняется только для голосовых сообщений (file_type файла — voice), иначе null.
duration_ms
integer, (int32)
*
Длительность голосового сообщения в миллисекундах
Пример:5400
waveform
string
*
Форма волны (амплитуды) для визуализации голосового сообщения
Пример:4,8,12,20,16,10,6,3
transcript
nullablestring
*
Расшифровка голосового сообщения в текст. null, пока расшифровка не готова или недоступна.
Пример:Привет, посмотри пожалуйста последний отчёт
transcript_status
nullablestring
*
Статус расшифровки. null, если расшифровка не запрашивалась: она выключена в пространстве, файл зашифрован, это черновик или сообщение отправлено до появления этого поля и расшифровки у него нет. При success текст лежит в transcript, а пустая строка в нём означает, что речи в записи нет. Пока расшифровка идёт, статус pending, и у расшифровки, которая не завершилась, он может держаться долго. failed означает, что расшифровка не удалась.
Возможные значения
Пример:success
buttons[][]
nullablearray of arrays of objects
*
Массив строк, каждая из которых представлена массивом кнопок. null, если при отправке поле buttons не передавали, и у удалённого сообщения. Пустые buttons при отправке или правке приходят как []: сообщение без кнопок узнают и по null, и по пустому массиву.
text
string
*
Текст, отображаемый на кнопке
Пример:Подробнее
Длина:
<= 255 символов
url
string
Ссылка, которая будет открыта по нажатию кнопки. У кнопки должно быть заполнено ровно одно из полей url и data.
Пример:https://example.com/details
Длина:
<= 1024 символов
data
string
Данные, которые будут отправлены в исходящем вебхуке по нажатию кнопки. У кнопки должно быть заполнено ровно одно из полей url и data.
Пример:awesome
Длина:
<= 255 символов
thread
nullableobject
*
Тред, созданный к этому сообщению. null, если тред не создан, а также у сообщений, которые сами находятся внутри треда.
id
integer, (int64)
*
Идентификатор треда. Чтобы написать в тред, передайте его в entity_id метода POSTНовое сообщение с entity_type: "thread".
Пример:265142
chat_id
integer, (int64)
*
Идентификатор чата треда. По нему читают сообщения треда методом GETСписок сообщений чата.
Пример:2637266155
forwarding
nullableobject
*
Информация о пересланном сообщении. null, если сообщение не является пересланным.
original_message_id
integer, (int32)
*
Идентификатор оригинального сообщения
Пример:194275
original_chat_id
integer, (int32)
*
Идентификатор чата, в котором находится оригинальное сообщение
Пример:334
author_id
integer, (int32)
*
Идентификатор пользователя, создавшего оригинальное сообщение
Пример:12
original_created_at
string, (date-time)
*
Дата и время создания оригинального сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ
Пример:2025-01-15T10:30:00.000Z
original_thread_id
nullableinteger, (int32)
*
Идентификатор треда, в котором находится оригинальное сообщение
Пример:null
original_thread_message_id
nullableinteger, (int32)
*
Идентификатор сообщения, к которому был создан тред, в котором находится оригинальное сообщение. null, если оригинальное сообщение было не в треде или тред создан без привязки к сообщению.
Пример:null
original_thread_parent_chat_id
nullableinteger, (int32)
*
Идентификатор чата сообщения, к которому был создан тред, в котором находится оригинальное сообщение. null, если оригинальное сообщение было не в треде или тред создан без привязки к сообщению.
Пример:null
parent_message_id
nullableinteger, (int32)
*
Идентификатор сообщения, к которому написан ответ. null, если сообщение не является ответом на другое сообщение.
Пример:null
display_avatar_url
nullablestring
Ссылка на аватарку отправителя сообщения. Поле присутствует только у сообщений от ботов; у сообщений от сотрудников его в ответе нет. null, если бот не переопределял значение при отправке.
Пример:null
display_name
nullablestring
Полное имя отправителя сообщения. Поле присутствует только у сообщений от ботов; у сообщений от сотрудников его в ответе нет. null, если бот не переопределял значение при отправке.
Пример:null
changed_at
nullablestring, (date-time)
*
Дата и время последнего изменения сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. Заполняется уже при создании сообщения и обычно отличается от created_at на доли секунды или больше: у created_at доли секунды всегда нулевые. null у сообщений, отправленных до появления этого поля.
Пример:2021-08-28T16:10:00.000Z
deleted_at
nullablestring, (date-time)
*
Дата и время удаления сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ. null у неудалённых сообщений. В списке сообщений удалённые не возвращаются.
Пример:null
important
boolean
*
Сообщение в разделе «Важное» владельца токена. У токена бота всегда false.
Пример:false
source
nullablestring
*
Через что отправлено сообщение токеном сотрудника, как в значке «Отправлено через …» на аватаре. null у сообщения, которое отправили из приложения Пачки, в том числе из черновика, у сообщений ботов, у отложенного сообщения, которое ушло по расписанию, и у сообщений, отправленных до появления значка. Подробнее в разделе Как выглядят сообщения.
Возможные значения
Пример:application
application
nullableobject
*
Программа, через которую отправлено сообщение, при source: "application". В остальных случаях null.
id
integer, (int32)
*
Идентификатор программы
Пример:4812
name
string
*
Название программы, как в подсказке «Отправлено через …» на аватаре: «Pachca CLI», название клиента MCP или имя бота. У старых сообщений тоже приходит текущее название. Клиент MCP задаёт название сам в документе, который публикует на своём домене, поэтому программу узнают по id.
Пример:Pachca CLI
meta
object
*
Метаданные пагинации
paginate
object
*
Вспомогательная информация
next_page
string
*
Курсор пагинации следующей страницы
Пример:eyJxZCO2MiwiZGlyIjomSNYjIn3
prev_page
string
Курсор пагинации предыдущей страницы. Используется для polling новых записей «сверху» списка.
Пример:eyJxZCO2MiwiZGlyIjoiYXNjIn0
has_next
boolean
Есть ли ещё данные на следующей странице. На последней странице — false.
Пример:true
has_prev
boolean
Есть ли ещё данные на предыдущей странице. На первом запросе без курсора — false.
Пример:false
Список закреплённых сообщений
# Добавьте --all для автоматической пагинацииpachca messages list-pinned 334 \  --limit=25 \  --json \  --token YOUR_ACCESS_TOKEN
Ответ 200
{  "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": "Привет, посмотри пожалуйста последний отчёт",        "transcript_status": "success"      },      "buttons": [        [          {            "text": null          }        ]      ],      "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,      "important": false,      "source": "application",      "application": {        "id": 4812,        "name": "Pachca CLI"      }    }  ],  "meta": {    "paginate": {      "next_page": "eyJxZCO2MiwiZGlyIjomSNYjIn3",      "prev_page": "eyJxZCO2MiwiZGlyIjoiYXNjIn0",      "has_next": true,      "has_prev": false    }  }}