pachca-messages

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pachca-messages

Base URL:

https://api.pachca.com/api/shared/v1

Авторизация:

Authorization: Bearer <ACCESS_TOKEN>

Токен: бот (Автоматизации → Интеграции → API) или пользователь (Автоматизации → API).

Base URL:

https://api.pachca.com/api/shared/v1

授权方式:

Authorization: Bearer <ACCESS_TOKEN>

令牌来源：机器人令牌（自动化→集成→API）或用户令牌（自动化→API）。

Когда использовать

适用场景

отправить сообщение
ответить в тред
прикрепить файл
загрузить файл
вложения сообщения
добавить реакцию
история сообщений
закрепить сообщение
редактировать сообщение
удалить сообщение
подписаться на тред
разослать уведомление
упомянуть пользователя
кнопки
прочтения
личное сообщение

发送消息
回复线程
附加文件
上传文件
消息附件
添加表情反应
消息历史
置顶消息
编辑消息
删除消息
订阅线程
批量发送通知
提及用户
消息按钮
已读状态查询
私聊消息

Когда НЕ использовать

不适用场景

получить профиль, мой профиль, установить статус → pachca-profile
найти сотрудника, создать пользователя, список сотрудников → pachca-users
создать канал, создать беседу, создать чат → pachca-chats
настроить бота, вебхук, webhook → pachca-bots
показать форму, интерактивная форма, модальное окно → pachca-forms
создать задачу, список задач, напоминание → pachca-tasks
аудит, журнал событий, безопасность → pachca-security

获取个人资料、我的资料、设置状态 → pachca-profile
查找员工、创建用户、员工列表 → pachca-users
创建频道、创建群组、创建聊天 → pachca-chats
配置机器人、Webhook → pachca-bots
展示表单、交互式表单、模态窗口 → pachca-forms
创建任务、任务列表、提醒 → pachca-tasks
审计、事件日志、安全 → pachca-security

Пошаговые сценарии

分步操作场景

Найти чат по имени и отправить сообщение

按名称查找聊天并发送消息

GET /chats — перебери результаты, найди нужный по полю
```
name
```
Отправь POST /messages с
```
"entity_id": chat.id
```

bash

curl "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"entity_id":12345,"content":"Текст сообщения"}}'

entity_type
по умолчанию
"discussion"
, можно не указывать. GET /chats не поддерживает поиск по имени — перебирай страницы.

调用GET /chats — 遍历结果，通过
```
name
```
字段找到目标聊天
调用POST /messages，传入
```
"entity_id": chat.id
```

bash

curl "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"entity_id":12345,"content":"Текст сообщения"}}'

entity_type
默认值为
"discussion"
，可省略。GET /chats不支持按名称搜索 — 需要分页遍历结果。

Отправить сообщение в канал или беседу (если chat_id известен)

向频道或群组发送消息（已知chat_id时）

Отправь POST /messages с
```
"entity_id": chat_id
```

"entity_type": "discussion"
используется по умолчанию, можно не указывать

调用POST /messages，传入
```
"entity_id": chat_id
```

"entity_type": "discussion"
为默认值，可省略

Отправить личное сообщение пользователю

向用户发送私聊消息

Определи
```
user_id
```
получателя (GET /users или из контекста)

Отправь POST /messages с

"entity_type": "user"

"entity_id": user_id

bash

curl "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"entity_type":"user","entity_id":186,"content":"Привет!"}}'

Создавать чат не требуется — он создаётся автоматически

确定接收方的
```
user_id
```
（通过GET /users或上下文获取）

调用POST /messages，传入

"entity_type": "user"

"entity_id": user_id

bash

curl "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"entity_type":"user","entity_id":186,"content":"Привет!"}}'

无需提前创建聊天 — 系统会自动创建

Ответить в тред (комментарий к сообщению)

回复消息线程（评论消息）

Получи или создай тред: POST /messages/{id}/thread (
```
id
```
— id родительского сообщения)
Из ответа возьми id треда (
```
thread.id
```
)

Отправь POST /messages с

"entity_type": "thread"

"entity_id": thread.id

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686/thread" \
  -H "Authorization: Bearer $TOKEN"

创建或获取线程：调用POST /messages/{id}/thread（
```
id
```
为父消息的ID）
从返回结果中获取线程ID（
```
thread.id
```
）

调用POST /messages，传入

"entity_type": "thread"

"entity_id": thread.id

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686/thread" \
  -H "Authorization: Bearer $TOKEN"

Ответ: {"data":{"id":265142,"chat_id":2637266155,"message_id":154332686,...}}

返回结果: {"data":{"id":265142,"chat_id":2637266155,"message_id":154332686,...}}

curl "https://api.pachca.com/api/shared/v1/messages"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"message":{"entity_type":"thread","entity_id":265142,"content":"Ответ в тред"}}'


> Если тред уже существует, POST /messages/{id}/thread вернёт существующий. Альтернативно можно использовать `"entity_type": "discussion"` + `"entity_id": thread.chat_id`. `skip_invite_mentions: true` — не добавлять упомянутых пользователей в тред автоматически.


> 如果线程已存在，POST /messages/{id}/thread会返回已有的线程。也可以使用`"entity_type": "discussion"` + `"entity_id": thread.chat_id`。`skip_invite_mentions: true` — 不会自动将被提及的用户添加到线程中。

Ответить пользователю, который написал боту

回复给向机器人发消息的用户

Вебхук содержит
```
entity_type
```
— он однозначно определяет контекст:
```
"user"
```
— личное сообщение боту,
```
"thread"
```
— сообщение в треде,
```
"discussion"
```
— сообщение в канале или беседе

DM (

entity_type: "user"

): ответь POST /messages с

"entity_type": "user"

"entity_id"

user_id

из вебхука

Тред (
```
entity_type: "thread"
```
): вложенных тредов нет — ответь в тот же тред: POST /messages с
```
"entity_type": "thread"
```
,
```
"entity_id"
```
:
```
entity_id
```
из вебхука,
```
"parent_message_id"
```
:
```
id
```
сообщения пользователя из вебхука
Беседа/канал (
```
entity_type: "discussion"
```
): выбери стратегию — inline-ответ (POST /messages c
```
"parent_message_id"
```
:
```
id
```
сообщения) или тред (POST /messages/{id}/thread → ответ в тред)

parent_message_id
визуально привязывает ответ к конкретному сообщению (показывается как «в ответ на…»). В треде обязателен для цепочки диалога. В обычном чате — альтернатива треду.

Webhook中包含
```
entity_type
```
字段，可明确上下文：
```
"user"
```
表示用户给机器人发私聊消息，
```
"thread"
```
表示线程中的消息，
```
"discussion"
```
表示频道或群组中的消息
私聊（
```
entity_type: "user"
```
）：调用POST /messages，传入
```
"entity_type": "user"
```
,
```
"entity_id"
```
为Webhook中的
```
user_id
```
线程（
```
entity_type: "thread"
```
）：不支持嵌套线程 — 直接回复到当前线程：调用POST /messages，传入
```
"entity_type": "thread"
```
,
```
"entity_id"
```
为Webhook中的
```
entity_id
```
，
```
"parent_message_id"
```
为Webhook中用户消息的
```
id
```
群组/频道（
```
entity_type: "discussion"
```
）：选择回复策略 — 内联回复（调用POST /messages，传入
```
"parent_message_id"
```
为用户消息的
```
id
```
）或线程回复（调用POST /messages/{id}/thread → 回复到线程）

parent_message_id
会将回复与指定消息关联（显示为“回复自…”）。在线程中是对话链的必填项。在普通聊天中是线程回复的替代方案。

Отправить сообщение с файлами

发送带文件的消息

Для каждого файла: POST /uploads → получи
```
key
```
(с
```
$filename
```
),
```
direct_url
```
,
```
policy
```
, подпись
Для каждого файла: подставь имя файла вместо
```
$filename
```
в
```
key
```
, затем загрузи файл POST на
```
direct_url
```
(
```
multipart/form-data
```
, без авторизации)
Собери массив
```
files
```
из всех загруженных файлов (
```
key
```
,
```
name
```
,
```
file_type
```
,
```
size
```
)
Отправь POST /messages с массивом
```
files
```
— одно сообщение со всеми файлами

bash

curl "https://api.pachca.com/api/shared/v1/uploads" \
  -H "Authorization: Bearer $TOKEN"

每个文件需先调用POST /uploads → 获取
```
key
```
（包含
```
$filename
```
）、
```
direct_url
```
、
```
policy
```
和签名
每个文件：将
```
key
```
中的
```
$filename
```
替换为实际文件名，然后通过POST请求将文件上传到
```
direct_url
```
（使用
```
multipart/form-data
```
格式，无需授权）
收集所有已上传文件的信息组成
```
files
```
数组（包含
```
key
```
、
```
name
```
、
```
file_type
```
、
```
size
```
）
调用POST /messages并传入
```
files
```
数组 — 一条消息可包含多个文件

bash

curl "https://api.pachca.com/api/shared/v1/uploads" \
  -H "Authorization: Bearer $TOKEN"

Ответ: {"key":".../$filename","direct_url":"https://...","policy":"...","x-amz-signature":"...",...}

返回结果: {"key":".../$filename","direct_url":"https://...","policy":"...","x-amz-signature":"...",...}

curl -X POST <direct_url>
-F "Content-Disposition=attachment" -F "acl=private"
-F "policy=<policy>" -F "x-amz-credential=<credential>"
-F "x-amz-algorithm=<algorithm>" -F "x-amz-date=<date>"
-F "x-amz-signature=<signature>"
-F "key=<key_с_подставленным_именем>" -F "file=@report.pdf"

curl "https://api.pachca.com/api/shared/v1/messages"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"message":{"entity_id":12345,"content":"Смотри файл","files":[{"key":"uploads/.../report.pdf","name":"report.pdf","file_type":"file","size":12345}]}}'


> Файлы не передаются inline. Загрузка двухшаговая: сначала POST /uploads (параметры), затем POST на `direct_url` (сам файл на S3). Шаги 1-2 повторяются для каждого файла отдельно, а сообщение отправляется один раз со всеми файлами.


> 文件不支持内联传递。上传分为两步：先调用POST /uploads获取参数，再上传文件到`direct_url`（S3存储）。步骤1-2需为每个文件单独执行，然后一次性发送包含所有文件的消息。

Отправить сообщение с кнопками

发送带按钮的消息

Сформируй массив
```
buttons
```
— массив строк, каждая строка — массив кнопок:
```
[[{кнопка1, кнопка2}, ...], ...]
```
Каждая кнопка:
```
{"text": "Текст"}
```
+ либо
```
url
```
(ссылка), либо
```
data
```
(callback для вебхука)
Отправь POST /messages с полем
```
buttons
```
Нажатия кнопок приходят в исходящий вебхук (событие "Нажатие кнопок")

bash

curl "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"entity_id":12345,"content":"Выбери действие","buttons":[[{"text":"Подробнее","url":"https://example.com"},{"text":"Отлично!","data":"awesome"}]]}}'

buttons
— массив массивов (строки × кнопки). Максимум 100 кнопок, до 8 в строке. Кнопка с
url
открывает ссылку, с
data
— отправляет событие на вебхук.

构造
```
buttons
```
数组 — 外层数组为行，内层数组为每行的按钮：
```
[[{按钮1, 按钮2}, ...], ...]
```
每个按钮需包含
```
"text": "按钮文本"
```
，以及
```
url
```
（跳转链接）或
```
data
```
（Webhook回调数据）
调用POST /messages并传入
```
buttons
```
字段
按钮点击事件会通过Webhook推送（事件类型为“按钮点击”）

bash

curl "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"entity_id":12345,"content":"Выбери действие","buttons":[[{"text":"Подробнее","url":"https://example.com"},{"text":"Отлично!","data":"awesome"}]]}}'

buttons
是二维数组（行×按钮）。最多支持100个按钮，每行最多8个。带
url
的按钮会打开链接，带
data
的按钮会向Webhook发送事件。

Получить историю сообщений чата

获取聊天的消息历史

GET /messages?chat_id={id}
Пагинация:
```
limit
```
(1-50, по умолчанию 50) и
```
cursor
```
(из
```
meta.paginate.next_page
```
)
Сортировка:
```
sort[id]=asc
```
или
```
sort[id]=desc
```
(по умолчанию
```
"desc"
```
)

bash

curl "https://api.pachca.com/api/shared/v1/messages?chat_id=12345&limit=50&sort[id]=asc" \
  -H "Authorization: Bearer $TOKEN"

Для сообщений треда используй
chat_id
треда (
thread.chat_id
). Пагинация cursor-based, не page-based.

调用GET /messages?chat_id={id}
分页参数：
```
limit
```
（取值1-50，默认50）和
```
cursor
```
（来自
```
meta.paginate.next_page
```
）
排序参数：
```
sort[id]=asc
```
或
```
sort[id]=desc
```
（默认
```
"desc"
```
）

bash

curl "https://api.pachca.com/api/shared/v1/messages?chat_id=12345&limit=50&sort[id]=asc" \
  -H "Authorization: Bearer $TOKEN"

要获取线程的消息历史，需使用线程的
chat_id
（
thread.chat_id
）。分页采用cursor-based方式，而非page-based。

Получить вложения из сообщения

获取消息中的附件

GET /messages/{id} — в поле
```
files[]
```
каждый объект содержит
```
url
```
(прямая ссылка),
```
name
```
,
```
file_type
```
,
```
size
```
Скачай нужные файлы по
```
files[].url
```
— ссылка прямая, авторизация не требуется

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686" \
  -H "Authorization: Bearer $TOKEN"

调用GET /messages/{id} —
```
files[]
```
数组中的每个对象包含
```
url
```
（直接下载链接）、
```
name
```
、
```
file_type
```
、
```
size
```
通过
```
files[].url
```
下载文件 — 链接为直接访问地址，无需授权

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686" \
  -H "Authorization: Bearer $TOKEN"

Ответ: {"data":{"id":154332686,"content":"Смотри файл","files":[{"url":"https://...","name":"report.pdf","file_type":"file","size":12345}],...}}

返回结果: {"data":{"id":154332686,"content":"Смотри файл","files":[{"url":"https://...","name":"report.pdf","file_type":"file","size":12345}],...}}


> Вебхук о новом сообщении НЕ содержит вложений — поле `files` отсутствует даже если файлы есть. При анализе любого сообщения (из вебхука, из истории чата) всегда проверяй вложения через GET /messages/{id} — если `files` непустой, в сообщении есть файлы, которые могут быть важны для контекста.


> 新消息的Webhook不包含附件字段 — 即使消息有文件，`files`字段也不会出现。处理任何消息（来自Webhook或聊天历史）时，都需通过GET /messages/{id}检查附件 — 如果`files`数组非空，说明消息包含可能对上下文很重要的文件。

Закрепить/открепить сообщение

置顶/取消置顶消息

Закрепить: POST /messages/{id}/pin
Открепить: DELETE /messages/{id}/pin

В чате может быть несколько закреплённых сообщений.

置顶：调用POST /messages/{id}/pin
取消置顶：调用DELETE /messages/{id}/pin

一个聊天中可以有多条置顶消息。

Подписаться на тред сообщения

订阅消息线程

POST /messages/{id}/thread — если треда нет, он будет создан; если есть — вернётся существующий
Из ответа возьми
```
chat_id
```
треда (
```
data.chat_id
```
)
Добавь бота (или пользователя) в участники чата треда: POST /chats/{id}/members с
```
member_ids
```
Теперь бот будет получать вебхук-события о новых сообщениях в этом треде

POST /messages/{id}/thread идемпотентен — безопасно вызывать повторно. После добавления в участники бот получает события треда через исходящий вебхук.

调用POST /messages/{id}/thread — 如果线程不存在则创建，存在则返回已有线程
从返回结果中获取线程的
```
chat_id
```
（
```
data.chat_id
```
）
将机器人（或用户）添加为线程聊天的成员：调用POST /chats/{id}/members并传入
```
member_ids
```
之后机器人会通过Webhook接收该线程的新消息事件

POST /messages/{id}/thread是幂等操作 — 可安全重复调用。添加为成员后，机器人会通过Webhook接收线程事件。

Упомянуть пользователя по имени

通过名称提及用户

Определи поисковый запрос — используй фамилию, она уникальнее. Имена не склоняются в API, приводи к именительному падежу: «упомяни Пашу» → ищи
```
Паша
```
или
```
Павел
```
, «тегни Голубева» → ищи
```
Голубев
```
Ищи сначала среди участников целевого чата: GET /chats/{id}/members (для треда тоже работает, у него свои участники) — фильтруй по имени на клиенте
Если пишешь в тред: также проверь участников родительского чата (GET /chats/{id}/members с
```
id=message_chat_id
```
)
Не нашёл — ищи по всей компании: GET /users?query={запрос}
Один подходящий результат → используй
```
nickname
```
. Несколько → уточни у пользователя (имя + фамилия). Ничего → попробуй другую форму имени (уменьшительное ↔ полное)
Вставь
```
@nickname
```
в текст сообщения

bash

curl "https://api.pachca.com/api/shared/v1/chats/12345/members" \
  -H "Authorization: Bearer $TOKEN"

确定搜索关键词 — 使用姓氏更准确，因为姓氏唯一性更高。API中名称无需变格，需转换为第一格：比如“提及帕夏”→ 搜索
```
Паша
```
或
```
Павел
```
，“标记戈卢别夫”→ 搜索
```
Голубев
```
先在目标聊天的成员中搜索：调用GET /chats/{id}/members（线程也适用，线程有独立成员）→ 在客户端过滤名称
如果是在线程中发送消息：还需检查父聊天的成员（调用GET /chats/{id}/members，
```
id=message_chat_id
```
）
未找到则在全公司搜索：调用GET /users?query={关键词}
找到唯一匹配结果 → 使用其
```
nickname
```
。多个匹配结果 → 让用户补充信息（姓名+姓氏）。无匹配结果 → 尝试其他名称形式（昵称↔全名）
在消息文本中插入
```
@nickname
```

bash

curl "https://api.pachca.com/api/shared/v1/chats/12345/members" \
  -H "Authorization: Bearer $TOKEN"

Ответ: [{"id":42,"first_name":"Павел","last_name":"Голубев","nickname":"golubevpn",...}]

返回结果: [{"id":42,"first_name":"Павел","last_name":"Голубев","nickname":"golubevpn",...}]


> Поиск среди участников чата точнее — пользователь явно связан с контекстом, меньше вероятность спутать однофамильцев. GET /users?query — последний fallback для поиска по всей компании.


> 在聊天成员中搜索更准确 — 用户与上下文明确关联，重名概率更低。GET /users?query是全公司搜索的最后备选方案。

Отредактировать сообщение

编辑消息

PUT /messages/{id} с полем
```
content
```
(и/или
```
buttons
```
,
```
files
```
)

bash

curl -X PUT "https://api.pachca.com/api/shared/v1/messages/154332686" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"content":"Обновлённый текст"}}'

Редактировать можно только свои сообщения (или от имени бота).

调用PUT /messages/{id}并传入
```
content
```
字段（和/或
```
buttons
```
、
```
files
```
）

bash

curl -X PUT "https://api.pachca.com/api/shared/v1/messages/154332686" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":{"content":"Обновлённый текст"}}'

只能编辑自己发送的消息（或机器人发送的消息）。

Изменить вложения сообщения

修改消息附件

GET /messages/{id} — получи текущие вложения из поля
```
files[]
```
, сохрани нужные объекты (
```
key
```
,
```
name
```
,
```
file_type
```
,
```
size
```
)
Если нужно добавить новый файл: POST /uploads → загрузи файл → добавь объект в список
PUT /messages/{id} с массивом
```
files
```
— только те файлы, которые должны остаться (+ новые при необходимости)

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686" \
  -H "Authorization: Bearer $TOKEN"

调用GET /messages/{id} — 从
```
files[]
```
字段获取当前附件，保存需要保留的文件对象（
```
key
```
、
```
name
```
、
```
file_type
```
、
```
size
```
）
如需添加新文件：调用POST /uploads → 上传文件 → 将文件对象添加到列表
调用PUT /messages/{id}并传入
```
files
```
数组 — 仅包含需要保留的文件（+新文件，如有）

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686" \
  -H "Authorization: Bearer $TOKEN"

Ответ: {"data":{"files":[{"key":"uploads/.../a.pdf","name":"a.pdf","file_type":"file","size":1000},{"key":"uploads/.../b.pdf","name":"b.pdf","file_type":"file","size":2000}],...}}

返回结果: {"data":{"files":[{"key":"uploads/.../a.pdf","name":"a.pdf","file_type":"file","size":1000},{"key":"uploads/.../b.pdf","name":"b.pdf","file_type":"file","size":2000}],...}}

curl -X PUT "https://api.pachca.com/api/shared/v1/messages/154332686"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"message":{"files":[{"key":"uploads/.../a.pdf","name":"a.pdf","file_type":"file","size":1000}]}}'


> `files` при редактировании работает по принципу replace-all: присылаемый массив полностью заменяет текущие вложения, отсутствующие файлы удаляются. `files: []` удаляет все вложения. Если поле `files` не передавать — вложения не меняются.


> 编辑时`files`字段采用全量替换原则：传入的数组会完全替换当前附件，未包含的文件会被删除。`files: []`会删除所有附件。如果不传递`files`字段 — 附件保持不变。

Удалить сообщение

删除消息

DELETE /messages/{id}

bash

curl -X DELETE "https://api.pachca.com/api/shared/v1/messages/154332686" \
  -H "Authorization: Bearer $TOKEN"

调用DELETE /messages/{id}

bash

curl -X DELETE "https://api.pachca.com/api/shared/v1/messages/154332686" \
  -H "Authorization: Bearer $TOKEN"

Добавить реакцию на сообщение

为消息添加表情反应

POST /messages/{id}/reactions с полем
```
code
```
(emoji)
Убрать реакцию: DELETE /messages/{id}/reactions с полем
```
code
```

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686/reactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"👍"}'

code
— emoji-символ, не его текстовое название.

调用POST /messages/{id}/reactions并传入
```
code
```
字段（表情符号）
移除表情反应：调用DELETE /messages/{id}/reactions并传入
```
code
```
字段

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686/reactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"👍"}'

code
为表情符号本身，而非其文本名称。

Проверить, кто прочитал сообщение

查询消息已读人员

GET /messages/{id}/read_member_ids — возвращает массив
```
user_id
```
прочитавших
При необходимости сопоставь с GET /users для получения имён

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686/read_member_ids" \
  -H "Authorization: Bearer $TOKEN"

调用GET /messages/{id}/read_member_ids — 返回已读用户的
```
user_id
```
数组
如需获取用户姓名，可结合GET /users接口

bash

curl "https://api.pachca.com/api/shared/v1/messages/154332686/read_member_ids" \
  -H "Authorization: Bearer $TOKEN"

Разослать уведомление нескольким пользователям

向多个用户批量发送通知

Определи список
```
user_id
```
получателей (GET /users или из контекста)

Для каждого: POST /messages с

"entity_type": "user"

"entity_id": user_id

Соблюдай rate limit: ~4 req/sec для сообщений. Добавляй паузы при большом списке.

确定接收方的
```
user_id
```
列表（通过GET /users或上下文获取）
为每个用户调用POST /messages，传入
```
"entity_type": "user"
```
,
```
"entity_id": user_id
```

需遵守速率限制：消息发送速率约为4 req/sec。发送大量消息时需添加停顿。

Обработка ошибок

错误处理

Код	Причина	Что делать
422	Неверные параметры	Проверь обязательные поля, типы данных, допустимые значения enum
429	Rate limit	Подожди и повтори. Лимит: ~50 req/sec, сообщения ~4 req/sec
403	Нет доступа	Недостаточно скоупов ( `insufficient_scope` ), бот не в чате, или endpoint только для админов/владельцев
404	Не найдено	Неверный id. Проверь что сущность существует
401	Не авторизован	Проверь токен в заголовке Authorization

状态码	原因	处理方式
422	参数错误	检查必填字段、数据类型、枚举值的合法性
429	触发速率限制	等待后重试。限制规则：约50 req/sec，消息发送约4 req/sec
403	无访问权限	权限范围不足（ `insufficient_scope` ）、机器人不在聊天中、或该端点仅对管理员/所有者开放
404	资源不存在	ID错误。检查资源是否存在
401	未授权	检查Authorization头中的令牌

Доступные операции

可用操作

Загрузка файла

文件上传

POST /direct_url

POST /direct_url

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

发送新消息

POST /messages

скоуп:
messages:create

json

{
  "message": {
    "entity_id": 198,
    "content": "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)"
  }
}

POST /messages

权限范围:
messages:create

json

{
  "message": {
    "entity_id": 198,
    "content": "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)"
  }
}

Список сообщений чата

获取聊天消息列表

GET /messages

скоуп:
messages:read

GET /messages

权限范围:
messages:read

Информация о сообщении

获取消息详情

GET /messages/{id}

скоуп:
messages:read

GET /messages/{id}

权限范围:
messages:read

Редактирование сообщения

编辑消息

PUT /messages/{id}

скоуп:
messages:update

json

{
  "message": {}
}

PUT /messages/{id}

权限范围:
messages:update

json

{
  "message": {}
}

Удаление сообщения

删除消息

DELETE /messages/{id}

скоуп:
messages:delete

DELETE /messages/{id}

权限范围:
messages:delete

Закрепление сообщения

置顶消息

POST /messages/{id}/pin

скоуп:
pins:write

POST /messages/{id}/pin

权限范围:
pins:write

Открепление сообщения

取消置顶消息

DELETE /messages/{id}/pin

скоуп:
pins:write

DELETE /messages/{id}/pin

权限范围:
pins:write

Добавление реакции

添加表情反应

POST /messages/{id}/reactions

скоуп:
reactions:write

json

{
  "code": "👍"
}

POST /messages/{id}/reactions

权限范围:
reactions:write

json

{
  "code": "👍"
}

Удаление реакции

删除表情反应

DELETE /messages/{id}/reactions

скоуп:
reactions:write

DELETE /messages/{id}/reactions

权限范围:
reactions:write

Список реакций

获取表情反应列表

GET /messages/{id}/reactions

скоуп:
reactions:read

GET /messages/{id}/reactions

权限范围:
reactions:read

Список прочитавших сообщение

获取消息已读人员ID列表

GET /messages/{id}/read_member_ids

скоуп:
messages:read

GET /messages/{id}/read_member_ids

权限范围:
messages:read

Новый тред

创建新线程

POST /messages/{id}/thread

скоуп:
threads:create

POST /messages/{id}/thread

权限范围:
threads:create

Информация о треде

获取线程详情

GET /threads/{id}

скоуп:
threads:read

GET /threads/{id}

权限范围:
threads:read

Получение подписи, ключа и других параметров

获取签名、密钥及其他参数

POST /uploads

скоуп:
uploads:write

POST /uploads

权限范围:
uploads:write

Ограничения и gotchas

限制与注意事项

```
message.entity_type
```
: допустимые значения —
```
discussion
```
(Беседа или канал),
```
thread
```
(Тред),
```
user
```
(Пользователь)
```
message.display_avatar_url
```
: максимум 255 символов
```
message.display_name
```
: максимум 255 символов
```
limit
```
: максимум 50
Пагинация: cursor-based (limit + cursor), НЕ page-based

```
message.entity_type
```
: 允许的值为
```
discussion
```
（群组或频道）、
```
thread
```
（线程）、
```
user
```
（用户）
```
message.display_avatar_url
```
: 最大长度255字符
```
message.display_name
```
: 最大长度255字符
```
limit
```
: 最大值50
分页方式: cursor-based（limit + cursor），而非page-based