C#
Типизированный клиент для Pachca API. Работает в .NET 8+ с поддержкой async/await и CancellationToken.
Быстрый старт
Установка
Создание клиента
Клиенту нужен токен бота или персональный токен. Какой выбрать и кто может его выпустить, описано в разделе Какой токен выбрать.
Первый запрос
Инициализация
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
token | string | — | Bearer-токен для авторизации |
baseUrl | string | https://api.pachca.com/api/shared/v1 | Базовый URL API |
Клиент реализует IDisposable — рекомендуется использовать using для автоматического освобождения ресурсов.
Для прокси, таймаутов и других параметров HTTP передайте готовый HttpClient: new PachcaClient(PachcaConstants.PachcaApiUrl, http). Заголовок Authorization задайте в http.DefaultRequestHeaders, а переходы по редиректам выключите (AllowAutoRedirect = false в обработчике), иначе DownloadExportAsync выбросит ошибку вместо ссылки на архив. Повторы SDK у такого клиента сохраняются, а Dispose() закрывает и переданный HttpClient.
Для тестов без сети есть клиент-заглушка: PachcaClient.Stub(messages: fakeMessages). В нём подменяют только нужные сервисы: класс наследует сервис, например MessagesService, и переопределяет нужные методы. Метод, который вы не переопределили, выбрасывает NotImplementedException.
Все методы
| Метод | Метод API |
|---|---|
client.Oauth.RevokeTokenAsync() | POSTОтзыв токена |
client.Oauth.ExchangeTokenAsync() | POSTОбмен кода на токен |
client.Oauth.GetTokenInfoAsync() | GETИнформация о токене |
client.Chats.CreateChatAsync() | POSTНовый чат |
client.Chats.RequestExportAsync() | POSTЭкспорт сообщений |
client.Chats.ListChatsAsync() | GETСписок чатов |
client.Chats.DownloadExportAsync() | GETСкачать архив экспорта |
client.Chats.GetChatAsync() | GETИнформация о чате |
client.Chats.ListCompanyChatsAsync() | GETСписок чатов пространства |
client.Chats.UpdateChatAsync() | PUTРедактирование чата |
client.Chats.ArchiveChatAsync() | PUTАрхивация чата |
client.Chats.UpdateChatAvatarAsync() | PUTЗагрузка аватара чата |
client.Chats.UnarchiveChatAsync() | PUTРазархивация чата |
client.Chats.MarkChatUnreadAsync() | PUTОтметка чата непрочитанным |
client.Chats.DeleteChatAvatarAsync() | DELETEУдаление аватара чата |
client.Profile.GetProfileAsync() | GETСвой профиль |
client.Profile.GetStatusAsync() | GETСвой статус |
client.Profile.UpdateProfileAvatarAsync() | PUTЗагрузка своего аватара |
client.Profile.UpdateStatusAsync() | PUTНовый свой статус |
client.Profile.DeleteProfileAvatarAsync() | DELETEУдаление своего аватара |
client.Profile.DeleteStatusAsync() | DELETEУдаление своего статуса |
client.Company.ReissueInviteLinkAsync() | POSTПеревыпуск ссылки-приглашения |
client.Company.GetCompanyAsync() | GETИнформация о пространстве |
client.Company.GetInviteLinkAsync() | GETСсылка-приглашение |
client.Company.UpdateCompanyAsync() | PUTРедактирование пространства |
client.Users.CreateUserAsync() | POSTНовый сотрудник |
client.Users.ListUsersAsync() | GETСписок сотрудников |
client.Users.GetUserAsync() | GETИнформация о сотруднике |
client.Users.GetUserStatusAsync() | GETСтатус сотрудника |
client.Users.UpdateUserAsync() | PUTРедактирование сотрудника |
client.Users.UpdateUserAvatarAsync() | PUTЗагрузка аватара сотрудника |
client.Users.UpdateUserStatusAsync() | PUTНовый статус сотрудника |
client.Users.DeleteUserAsync() | DELETEУдаление сотрудника |
client.Users.DeleteUserAvatarAsync() | DELETEУдаление аватара сотрудника |
client.Users.DeleteUserStatusAsync() | DELETEУдаление статуса сотрудника |
client.GroupTags.CreateTagAsync() | POSTНовый тег |
client.GroupTags.ListTagsAsync() | GETСписок тегов |
client.GroupTags.GetTagAsync() | GETИнформация о теге |
client.GroupTags.GetTagUsersAsync() | GETСписок сотрудников тега |
client.GroupTags.UpdateTagAsync() | PUTРедактирование тега |
client.GroupTags.DeleteTagAsync() | DELETEУдаление тега |
client.Members.AddTagsAsync() | POSTДобавление тегов |
client.Members.AddMembersAsync() | POSTДобавление участников |
client.Members.ListMembersAsync() | GETСписок участников чата |
client.Members.UpdateMemberRoleAsync() | PUTРедактирование роли участника |
client.Members.RemoveTagAsync() | DELETEИсключение тега из чата |
client.Members.LeaveChatAsync() | DELETEВыход из чата |
client.Members.RemoveMemberAsync() | DELETEИсключение участника |
client.Threads.CreateThreadAsync() | POSTНовый тред |
client.Threads.CreateStandaloneThreadAsync() | POSTНовый самостоятельный тред |
client.Threads.ListThreadsAsync() | GETСписок тредов |
client.Threads.GetThreadAsync() | GETИнформация о треде |
client.Messages.CreateMessageAsync() | POSTНовое сообщение |
client.Messages.UnfurlAsync() | POSTUnfurl (разворачивание ссылок) |
client.Messages.PinMessageAsync() | POSTЗакрепление сообщения |
client.Messages.ListChatMessagesAsync() | GETСписок сообщений чата |
client.Messages.GetMessageAsync() | GETИнформация о сообщении |
client.Messages.UpdateMessageAsync() | PUTРедактирование сообщения |
client.Messages.DeleteMessageAsync() | DELETEУдаление сообщения |
client.Messages.UnpinMessageAsync() | DELETEОткрепление сообщения |
client.ReadMembers.ListReadMembersAsync() | GETСписок прочитавших сообщение |
client.Reactions.AddReactionAsync() | POSTДобавление реакции |
client.Reactions.ListReactionsAsync() | GETСписок реакций |
client.Reactions.RemoveReactionAsync() | DELETEУдаление реакции |
client.ImportantMessages.AddMessageToImportantAsync() | POSTДобавление сообщения в важные |
client.ImportantMessages.ListImportantMessagesAsync() | GETСписок важных сообщений |
client.ImportantMessages.RemoveMessageFromImportantAsync() | DELETEУдаление сообщения из важных |
client.Search.SearchChatsAsync() | GETПоиск чатов |
client.Search.SearchMessagesAsync() | GETПоиск сообщений |
client.Search.SearchUsersAsync() | GETПоиск сотрудников |
client.Tasks.CreateTaskAsync() | POSTНовое напоминание |
client.Tasks.ListTasksAsync() | GETСписок напоминаний |
client.Tasks.GetTaskAsync() | GETИнформация о напоминании |
client.Tasks.UpdateTaskAsync() | PUTРедактирование напоминания |
client.Tasks.DeleteTaskAsync() | DELETEУдаление напоминания |
client.Drafts.CreateDraftAsync() | POSTНовый черновик |
client.Drafts.ListDraftsAsync() | GETСписок черновиков |
client.Drafts.GetDraftAsync() | GETИнформация о черновике |
client.Drafts.UpdateDraftAsync() | PUTРедактирование черновика |
client.Drafts.DeleteDraftAsync() | DELETEУдаление черновика |
client.Views.OpenViewAsync() | POSTОткрытие представления |
client.Views.SubmitViewResponseAsync() | POSTОтвет на отправку формы |
client.Bots.SelfRecreateBotTokenAsync() | POSTРотация собственного токена бота |
client.Bots.CreateBotAsync() | POSTНовый бот |
client.Bots.RecreateBotTokenAsync() | POSTРотация токена бота |
client.Bots.RotateBotClientSecretAsync() | POSTРотация секрета клиента |
client.Bots.CreateBotTokenAsync() | POSTНовый токен бота |
client.Bots.ReissueBotTokenAsync() | POSTПеревыпуск токена бота |
client.Bots.ListBotsAsync() | GETСписок ботов |
client.Bots.GetBotAsync() | GETИнформация о боте |
client.Bots.GetBotScopesAsync() | GETКаталог прав бота |
client.Bots.ListBotTokensAsync() | GETСписок токенов бота |
client.Bots.ListCompanyBotsAsync() | GETСписок ботов пространства |
client.Bots.GetWebhookEventsAsync() | GETИстория событий |
client.Bots.GetWebhookEventsStreamAsync() | GETПоток событий |
client.Bots.SelfUpdateBotWebhookAsync() | PUTСаморегистрация вебхука бота |
client.Bots.UpdateBotAsync() | PUTРедактирование бота |
client.Bots.UpdateBotAvatarAsync() | PUTЗагрузка аватара бота |
client.Bots.UpdateBotTokenAsync() | PUTИзменение токена бота |
client.Bots.DeleteBotAsync() | DELETEУдаление бота |
client.Bots.DeleteBotAvatarAsync() | DELETEУдаление аватара бота |
client.Bots.DeleteBotTokenAsync() | DELETEУдаление токена бота |
client.Bots.DeleteWebhookEventAsync() | DELETEУдаление события истории |
client.Security.GetAuditEventsAsync() | GETЖурнал аудита событий |
client.CustomProperties.ListPropertiesAsync() | GETСписок дополнительных полей |
client.Files.UploadFileAsync() | POSTЗагрузка файла |
client.Files.GetUploadParamsAsync() | POSTПолучение подписи, ключа и других параметров |
client.Files.DownloadFileAsync() | GETСкачивание файла |
Запросы
Все методы асинхронные. Метод с телом ответа возвращает Task<T>, метод без тела, например DeleteBotAsync, возвращает Task, а PollWebhookEventsAsync и PollWebhookPayloadsAsync возвращают IAsyncEnumerable<T>.
GET с параметрами:
POST с телом запроса:
Простой вызов по ID:
Значение null
Необязательное поле, которое не задано, в запрос не попадает, поэтому метод обновления меняет только то, что вы передали. Некоторые поля API принимают null: например, null в oauth_client выключает у бота авторизацию от имени сотрудника, а в webhook.kind удаляет входящий вебхук. Чтобы отправить null, назовите поле в NullFields той же модели запроса так, как оно называется в C#:
NullFields есть у моделей запроса с такими полями, а в его описании перечислены имена, которые в нём можно указать. С другим именем SDK выбрасывает ArgumentException и запрос не отправляет.
Пагинация
Поля пагинации называются как в API, но в PascalCase: Meta.Paginate.NextPage, PrevPage, HasNext и HasPrev. У методов поиска в Meta.Paginate только NextPage и HasNext, зато есть Meta.Total. Какие поля приходят у каждого метода и как понять, что страницы закончились, описано в разделе Пагинация.
Ручная пагинация
В модели поле HasNext имеет тип bool?. Если оно null, цикл идёт дальше и останавливается на пустой странице. Так же обходят страницы методы *AllAsync().
Автопагинация
Для каждого метода с пагинацией есть *AllAsync() вариант, который автоматически обходит все страницы и возвращает плоский список:
Доступные методы автопагинации:
| Метод | Возвращает |
|---|---|
Security.GetAuditEventsAllAsync() | List<AuditEvent> |
Bots.ListBotsAllAsync() | List<BotResponse> |
Bots.ListBotTokensAllAsync() | List<BotAccessToken> |
Bots.ListCompanyBotsAllAsync() | List<CompanyBotResponse> |
Bots.GetWebhookEventsAllAsync() | List<WebhookEvent> |
Chats.ListChatsAllAsync() | List<Chat> |
Chats.ListCompanyChatsAllAsync() | List<Chat> |
Drafts.ListDraftsAllAsync() | List<Draft> |
GroupTags.ListTagsAllAsync() | List<GroupTag> |
GroupTags.GetTagUsersAllAsync() | List<User> |
ImportantMessages.ListImportantMessagesAllAsync() | List<Message> |
Members.ListMembersAllAsync() | List<User> |
Messages.ListChatMessagesAllAsync() | List<Message> |
Reactions.ListReactionsAllAsync() | List<Reaction> |
ReadMembers.ListReadMembersAllAsync() | List<int> |
Search.SearchChatsAllAsync() | List<Chat> |
Search.SearchMessagesAllAsync() | List<Message> |
Search.SearchUsersAllAsync() | List<User> |
Tasks.ListTasksAllAsync() | List<Pachca.Sdk.Task> |
Threads.ListThreadsAllAsync() | List<Pachca.Sdk.Thread> |
Users.ListUsersAllAsync() | List<User> |
Обработка ошибок
SDK выбрасывает два типа исключений:
ApiError
Возникает при ответе с массивом errors в теле: это коды 400, 402, 403, 404, 409, 410, 422, 429, 503 и 504. Ответы 429 и 5xx SDK сначала повторяет по правилам из раздела Повторные запросы, а ApiError выбрасывает, если повторы не помогли или не положены:
Поля ApiErrorItem:
| Поле | Тип | Описание |
|---|---|---|
Key | string | Поле, вызвавшее ошибку |
Value | object? | Переданное значение |
Message | string | Текст ошибки |
Code | ValidationErrorCode | Код валидации (Blank, Invalid, Taken, ...) |
Payload | Dictionary<string, object>? | Дополнительные данные |
Код статуса ответа — в поле StatusCode. Если ответ с ошибкой пришёл без тела или не в JSON, SDK тоже выбрасывает ApiError: с кодом статуса и пустым Errors. Так бывает с ответом 404 без тела от метода GETПоток событий, когда история событий выключена, и со страницей прокси при 502.
OAuthError
Возникает при ошибке авторизации: 401, а также 403 с кодом insufficient_scope или role_forbidden и отказе при обмене кода на токен. Код — в поле Error, список кодов — в разделе Ошибки авторизации:
Поле Error — структура OAuthErrorCode: её сравнивают через == с константой, например OAuthErrorCode.InsufficientScope, или со строкой, а строку кода даёт Value.
Повторные запросы
Паузы между попытками, к каждой SDK добавляет случайную величину до 25%:
- 429 с заголовком
Retry-Afterдо минуты: срок из заголовка - 429 с
Retry-Afterдольше минуты: без повтора, SDK сразу выбрасываетApiErrorс кодом статуса429 - 429 без заголовка: 1 сек, 2 сек, 4 сек
- 5xx: ~10 сек, ~20 сек, ~40 сек
Срок дольше минуты бывает только у суточного предела сообщений и блокировки отправки, они описаны на странице Лимиты. Самого заголовка Retry-After в ApiError нет, поэтому срок паузы SDK не сообщает. Получив такую ошибку, остановите задачу и вернитесь к ней позже без пробных запросов.
Сетевую ошибку без ответа сервера SDK не повторяет: исключение HttpRequestException приходит сразу. Паузы прерывает CancellationToken, переданный в метод.
Общие правила повторов — в разделе Повторные запросы.
Отмена запросов
Все асинхронные методы поддерживают CancellationToken:
Загрузка файлов
Загрузка файла идёт в три шага: получить параметры загрузки, отправить файл по адресу DirectUrl и прикрепить его к сообщению по ключу. Поля каждого шага описаны в разделе Файлы.
Тип File есть и в SDK, поэтому System.IO.File в примере записан полностью. Такие совпадения имён перечислены в разделе Имена Task, Thread, File и TaskStatus.
Сериализация
SDK автоматически конвертирует имена полей между PascalCase (C#) и snake_case (API):
Типы
Все типы доступны из пространства имён Pachca.Sdk:
Перечисление в ответе — структура со строкой Value: значение, которого SDK ещё не знает, приходит как есть, и IsKnown у него false. Значения такого перечисления сравниваются через ==, а в switch — по Value. Ту же строку, что и Value, возвращает ToString().
Все перечисления SDK: AuditEventKey, AuditLoginGrantDenyReason, AuditLoginGrantDevicePlatform, BotCanEdit, BotEventName, BotTemplateEngine, BotTriggerOn, BotWebhookKind, BotWhoCanAdd, ChatActivity, ChatAvailability, ChatMemberRole, ChatMemberRoleFilter, ChatSortField, ChatSubtype, CompanyManagementAccess, CustomPropertyDataType, DraftRepetitionInterval, DraftType, FileTarget, FileType, InviteStatus, MemberEventType, MessageEntityType, MessageSearchSort, MessageSortField, MessageSource, OAuthErrorCode, OAuthScope, OAuthTokenTypeHint, ReactionEventType, SearchEntityType, SearchSortOrder, SortOrder, TaskKind, TaskStatus, UserCreateRole, UserEventType, UserRole, UserRoleInput, ValidationErrorCode, VideoCallEventType, VoiceTranscriptStatus и WebhookEventType.
Имена Task, Thread, File и TaskStatus
В SDK есть типы Task, Thread, File и TaskStatus. Проект .NET по умолчанию неявно подключает пространства имён System.Threading.Tasks, System.Threading и System.IO, где есть типы с теми же именами. Поэтому рядом с using Pachca.Sdk; такое короткое имя неоднозначно, и компилятор отвечает ошибкой CS0104. Запишите тип полностью, например Pachca.Sdk.Task или System.IO.File, или задайте псевдонимы в начале файла:
Тогда Task означает задачу .NET, например в static async Task Main(), а PachcaTask — напоминание Пачки.
Тело вебхука
Тела событий вебхука описаны классами MessageWebhookPayload, ReactionWebhookPayload, ButtonWebhookPayload, ViewSubmitWebhookPayload, ChatMemberWebhookPayload, CompanyMemberWebhookPayload, LinkSharedWebhookPayload и VideoCallWebhookPayload. Их общий базовый класс WebhookPayloadUnion разбирается своим конвертером: класс он выбирает по полям type и event.
Подпись проверяйте по исходному телу до разбора, как в разделе Безопасность. Те же классы отдают методы PollWebhookEventsAsync и PollWebhookPayloadsAsync, которые забирают события из истории: пример — в разделе Пример поллинга.
Примеры
Отправка сообщения:
Список сотрудников:
Создание напоминания: