Исходящие Webhook

Исходящие Webhook в Пачке — это инструмент для создания интеграций, который позволяет получать уведомления в формате JSON о различных событиях в реальном времени на ваш URL. В этой статье мы разберем настройку, типы событий и особенности использования вебхуков.

Как настроить отправку исходящих Webhook

1. Перейдите в раздел «‎Автоматизации»

2. В настройках бота выберите вкладку «‎Исходящий Webhook»

3. Введите полный URL вашего сервера, на который будут отправляться уведомления

4. У каждого исходящего вебхука автоматически генерируется уникальный токен — Signing secret, который вы не можете изменить. Такая авторизация позволяет серверу проверять и принимать запросы только от доверенного источника. Подробнее здесь.

О каких событиях можно получать Webhook

• Новые сообщения: отправка уведомлений о появлении новых сообщений в чатах, где есть бот (в т.ч. о сообщениях в тредах)
• Редактирование и удаление сообщений: уведомления при редактировании или удалении существующих сообщений в чатах, где есть бот‍
• Добавление и удаление реакций: уведомления при добавлении или удалении эмодзи-реакций на сообщения от бота‍
• Нажатие кнопок: уведомления при нажатии пользователями на интерактивные кнопки в сообщениях бота‍
• Изменение состава участников чатов: уведомления при добавлении или удалении участников в чатах, где есть бот‍
• Изменение состава участников пространства: уведомления при приглашении, подтверждении, приостановке или удалении участников пространства

Исходящие Webhook о новых сообщениях

Если вы выбрали событие «‎Новые сообщения», то у вас есть возможность выбрать, о каких именно новых сообщениях получать уведомления. Доступно два варианта:

• Любые сообщения: получать уведомления о всех новых сообщениях в чатах с ботом
• Начинающиеся с команд: получать уведомления только о сообщениях, которые начинаются с команд, указанных в поле «‎Команды». Команды должны начинаться с символа /, быть на английском языке и перечисляться через запятую. Например: /start, /hello, /task

Типы событий исходящих Webhook

Пачка поддерживает 5 основных типов событий. Они отправляются в формате JSON.

1. Сообщение

Отправляется при создании нового сообщения в чате.

{
  "type": "message",
  "id": 4062313533,
  "event": "new",
  "entity_type": "thread",
  "entity_id": 14904221,
  "content": "/new разработка чата",
  "user_id": 18531312,
  "created_at": "2023-01-26T15:25:16.000Z",
  "url": "https://app.pachca.com/chats/34876123?message=4062313533",
  "chat_id": 34876123,
  "parent_message_id": 4062313532,
  "thread": {
    "message_id": 5631128658,
    "message_chat_id": 38926752
  }
}

2. Реакция

{
  "type": "reaction",
  "event": "new",
  "message_id": 21344124,
  "code": "👍",
  "user_id": 18531312,
  "created_at": "2023-01-26T15:25:16.000Z"
}

3. Кнопка

{
  "type": "button",
  "message_id": 21344124,
  "data": "vote_yes",
  "user_id": 18531312
}

4. Участник чата

{
  "type": "chat_member",
  "event": "add",
  "chat_id": 34876123,
  "thread_id": 1243243,
  "user_ids": [13, 321],
  "created_at": "2023-01-26T15:25:16.000Z"
}

5. Участник пространства

{
  "type": "company_member",
  "event": "invite",
  "user_ids": [13, 321],
  "created_at": "2023-01-26T15:25:16.000Z"
}

Облегчённый формат Webhook

‍Поскольку исходящие вебхуки позволяют быстро и в реальном времени получать уведомления на URL, в них содержится только базовая информация о событии. Если вам нужна полная информация, то можно сделать запрос через API.

• Так, для полной информации по событиям «‎Сообщения» и «‎Кнопка», нужно использовать API-метод «‎Информация о сообщении». Информация о кнопках будет возвращаться как параметр сообщения.
• Для полной информации по событию «‎Реакция» — API-метод «Список реакций» для конкретного сообщения.
• Для полной информации по событию «‎Участник чата» — API-метод «Информация о беседе или канале». Будет отдаваться вся информация о чате, в т.ч. об участниках чата.
• Для полной информации по событию «‎Участник пространства» — API-метод «Список сотрудников»

Пример

‍Вебхук о новом сообщении:

{
  "type": "message",
  "id": 4062313533,
  "event": "new",
  "entity_type": "thread",
  "entity_id": 14904221,
  "content": "/new разработка чата",
  "user_id": 18531312,
  "created_at": "2023-01-26T15:25:16.000Z",
  "url": "https://app.pachca.com/chats/34876123?message=4062313533",
  "chat_id": 34876123,
  "parent_message_id": 4062313532,
  "thread": {
    "message_id": 5631128658,
    "message_chat_id": 38926752
  }
}

API-ответ с расширенной информацией о новом сообщении:

{
  "id": 4062313533,
  "entity_type": "thread",
  "entity_id": 14904221,
  "chat_id": 34876123,
  "content": "/new разработка чата",
  "user_id": 18531312,
  "created_at": "2023-01-26T15:25:16.000Z",
  "url": "https://app.pachca.com/chats/34876123?message=4062313533",
  "files": [
    {
      "id": 123456,
      "key": "path/to/file.pdf",
      "name": "document.pdf",
      "file_type": "file",
      "url": "https://app.pachca.com/files/download/123456"
    },
    {
      "id": 789012,
      "key": "path/to/image.jpg",
      "name": "screenshot.jpg",
      "file_type": "image",
      "url": "https://app.pachca.com/files/download/789012",
      "width": 1920,
      "height": 1080
    }
  ],
  "buttons": [
    [
      {
        "text": "Принять",
        "url": "https://example.com/accept",
        "data": "accept_task"
      },
      {
        "text": "Отклонить",
        "url": "",
        "data": "decline_task"
      }
    ]
  ],
  "thread": {
    "id": 12345,
    "chat_id": 67890
  },
  "forwarding": {
    "original_message_id": 123456789,
    "original_chat_id": 987654321,
    "author_id": 18531312,
    "original_created_at": "2023-01-25T12:30:15.000Z",
    "original_thread_id": 55555,
    "original_thread_message_id": 44444,
    "original_thread_parent_chat_id": 33333
  },
  "parent_message_id": 4062313532,
  "display_avatar_url": "https://app.pachca.com/custom_avatars/bot.png",
  "display_name": "Бот помощник"
}