Вебхуки и интеграции

Telegram-вебхук

Настройка

1. Создайте бота у @BotFather, получите токен
2. Сохраните токен в настройках Orbita: Настройки → Интеграции → Telegram Bot Token
3. Зарегистрируйте вебхук:

POST /api/settings/telegram/set-webhook
Authorization: Bearer <admin-token>

Orbita автоматически передаст Telegram URL вида:

https://app.orbita.example/api/telegram/webhook

Входящие сообщения

Каждое сообщение в Telegram-боте сохраняется как SysIncomingMessage с channel = 'telegram'.

Полный payload сообщения доступен в поле payload.

---

Incoming Actions — обработка входящих событий

Incoming Actions позволяют настроить, что делать с входящими сообщениями: создавать записи, запускать процессы, выполнять скрипты.

Схема работы

Telegram/Email → SysIncomingMessage
                       ↓
              IncomingAction (настроенное правило)
                       ↓
                  Подготовка данных
                  (field mapping + script)
                       ↓
                Создание записи в Orbita

Просмотр входящих сообщений

GET /api/sys/incoming_messages
Authorization: Bearer <token>

Ответ:

{
  "data": [
    {
      "id": 1,
      "channel": "telegram",
      "from_name": "Иван Иванов",
      "from_email": null,
      "from_id": "123456789",
      "subject": null,
      "body": "Не работает принтер на 3 этаже",
      "payload": { ... },
      "is_processed": false,
      "received_at": "2024-02-10T09:15:00Z"
    }
  ]
}

Создать правило IncomingAction

POST /api/sys/incoming-actions
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Создать IT-заявку из Telegram",
  "channel": "telegram",
  "is_automatic": false,
  "target_model": "it_requests",
  "field_mapping": {
    "name": "body",
    "details": "body"
  },
  "button_label": "Создать заявку",
  "button_color": "blue"
}

Поле	Описание
channel	telegram, email, api или all
is_automatic	true — выполняется сразу, false — кнопка в интерфейсе
target_model	Имя таблицы назначения
field_mapping	Маппинг: поле_записи → путь_в_сообщении
script	PHP-скрипт для трансформации данных

Маппинг полей

field_mapping поддерживает dot-notation для вложенных объектов:

{
  "name": "subject",
  "details": "body",
  "sender_name": "from.name",
  "sender_email": "from.email"
}

Скрипт трансформации

Если стандартного маппинга недостаточно, добавьте скрипт:

// Контекст: $incoming (данные сообщения), $data (подготовленные данные), $api

// Нормализовать приоритет из текста
if (strpos(strtolower($incoming['body']), 'срочно') !== false) {
    $data['priority'] = 'critical';
} else {
    $data['priority'] = 'medium';
}

// Найти пользователя по Telegram ID
$user = $api->find('users', 'telegram_chat_id', $incoming['from_id']);
if ($user) {
    $data['requested_by'] = $user['id'];
}

$data['name'] = 'Telegram: ' . substr($incoming['body'], 0, 100);
$data['details'] = $incoming['body'];

Подготовить данные из сообщения (preview)

POST /api/sys/incoming-actions/{action_id}/prepare
Authorization: Bearer <token>
Content-Type: application/json

{
  "message_id": 42
}

Возвращает подготовленные данные без создания записи — удобно для проверки маппинга.

Узнать доступные модели и поля

GET /api/sys/incoming-actions/models
Authorization: Bearer <token>

{
  "data": [
    {
      "model_class": "it_requests",
      "label": "IT-заявки",
      "fields": [
        { "name": "name", "type": "text" },
        { "name": "priority", "type": "value_list" },
        { "name": "assignee", "type": "user" }
      ]
    }
  ]
}

---

IMAP (Email-интеграция)

Orbita может забирать письма из почтового ящика и создавать из них входящие сообщения.

Настройка IMAP

Настройки → Интеграции → Email:

MAIL_HOST=imap.example.com
MAIL_PORT=993
MAIL_USERNAME=support@example.com
MAIL_PASSWORD=secret
MAIL_ENCRYPTION=ssl

Ручная проверка почты

POST /api/sys/settings/fetch-imap
Authorization: Bearer <admin-token>

Тест подключения

POST /api/sys/settings/test-imap
Authorization: Bearer <admin-token>