Кастомні канали

Канал підключає адміністратор організації в кабінеті Pager.

1. 1

   Відкрийте Налаштування → Канали і натисніть Підключити власний канал.

2. 2

   Вкажіть назву каналу — її бачитимуть менеджери в інбоксі — і URL для відправки повідомлень: адресу вашого сервера, на яку Pager надсилатиме відповіді менеджерів.

3. 3

   Після підключення в картці каналу з'явиться API Key виду chan_sk_live_… — це ключ каналу. Додайте його в налаштування свого сервера.

Обидва напрямки підписуються ключем каналу в заголовку x-channel-key.

• Ваш сервер → Pager. Передавайте ключ у x-channel-key кожного запиту до вебхука. За ключем Pager визначає канал і організацію.
• Pager → ваш сервер. Pager передає той самий ключ у x-channel-key. Порівнюйте його зі своїм і відхиляйте запити з іншим ключем — інакше будь-хто, хто знає ваш URL, зможе надіслати вашим клієнтам повідомлення від імені менеджера.

Успішна обробка — завжди 200 з ok: true. Поле action показує, що зроблено:

Помилки повертаються з полем error:

{
  "error": "Invalid payload",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "client": [
        "Invalid input: expected string, received undefined"
      ]
    }
  }
}

Відповідайте кодом 2xx, щойно прийняли повідомлення, і поверніть у JSON ідентифікатор повідомлення на вашій платформі.

{
  "externalMessageId": "msg_90415"
}

• externalMessageId (або externalId) Pager зберігає як ідентифікатор повідомлення. Без нього ви не зможете потім відредагувати чи видалити це повідомлення.
• Повідомлення враховується в ліміті повідомлень організації, лише якщо ви відповіли 2xx і повернули externalMessageId.
• Менеджер бачить повідомлення надісланим лише після вашої відповіді, тож відповідайте швидко, а важку обробку робіть уже після неї.

Доставка й повтори

• Якщо ваш сервер відповів не 2xx або не відповів зовсім, Pager повторює запит ще двічі — через 0,2 і 0,6 секунди.
• Якщо всі три спроби невдалі, повідомлення зберігається в Pager із позначкою «не доставлено», і менеджер це бачить. Пізніше Pager його автоматично не надсилає.

Мінімальний обробник: перевіряє ключ, відкидає повтори, передає повідомлення на вашу платформу й повертає його ідентифікатор.

import express from "express"

const app = express()
app.use(express.json())

// pagerMessageId -> externalMessageId. У продакшні — база або Redis
const processed = new Map()

app.post("/pager/outbound", async (req, res) => {
  // 1. Запит справді від Pager
  if (req.get("x-channel-key") !== process.env.PAGER_CHANNEL_KEY) {
    return res.status(401).end()
  }

  const { client, message } = req.body

  // 2. Повтор уже обробленого повідомлення
  if (processed.has(message.pagerMessageId)) {
    return res.json({ externalMessageId: processed.get(message.pagerMessageId) })
  }

  // 3. Відправка клієнту на вашій платформі
  const sent = await platform.sendMessage({
    to: client.externalId,
    text: message.text,
    attachments: message.attachments,
  })

  processed.set(message.pagerMessageId, sent.id)
  res.json({ externalMessageId: sent.id })
})

Вкладення передаються масивом об'єктів { type, payload: { url } } — однаково у вхідних подіях і в запитах від Pager.

[
  {
    "type": "image",
    "payload": {
      "url": "https://cdn.example.com/uploads/photo.jpg"
    }
  },
  {
    "type": "document",
    "payload": {
      "url": "https://cdn.example.com/uploads/invoice.pdf"
    }
  }
]

• Pager зберігає посилання, а не копію файлу, тож воно має лишатися доступним, поки менеджерам потрібна історія розмови.
• Посилання на localhost і внутрішні мережі (127.*, 10.*, 192.168.*) Pager мовчки відкидає, решта повідомлення зберігається.
• До 20 вкладень в одному повідомленні.
• У запитах від Pager посилання тимчасові й діють 24 години — завантажуйте файли одразу.