Реєстрація
Для реєстрації вашого застосунку в нашій системі, підготуйте та надайте наступну інформацію ⬇️
💡Ви можете надати описи та назви на декількох мовах для кращої локалізації. На даний момент ми підтримуємо наступні мови: українська, англійська, португальська, польська, іспанська, німецька.
| Locale | Language |
|---|---|
| uk | Ukraine |
| en-US | English US |
| pt-BR | Portuguese |
| pl | Polish |
| es-ES | Spanish |
| de | German |
Після надання цієї інформації, ви отримаєте client_id та secret_id для подальшої розробки.
Розробка бекенд частини
Ми підготували шаблон на базі Laravel PHP з базовими налаштуваннями.
🔍 Ознайомтесь за посиланням ➡️ ТУТ
Встановлення застосунку
Коли користувач встановлює застосунок, ви отримаєте наступний запит:
❗️Ми використовуємо JWT токен. Для визначення порталу, який встановлює застосунок, необхідно розпарсити токен та перевірити його достовірність. Приклад реалізації цієї логіки можна побачити за посиланням ➡️ ТУТ
Вам необхідно зберегти:
- token – живе 1 добу
- refresh_token – живе 30 днів
- expiry_date – для перевірки валідності токена
При розробці інтеграції ви зіткнетеся з двома видами токенів: токен користувача та токен інтеграції. Вони підписуються різними ключами та мають різний набір полів у payload.
Оновлення токена доступу
У попередньому кроці ми отримали токен. Цей токен має час життя 1 добу, після чого запити з його використанням не будуть працювати. Для оновлення токена рекомендуємо використати наступний запит:
Видалення застосунку
При видаленні застосунку ви отримаєте:
💡 Токен знаходиться в header Authorization. Необхідно запарсити токен, отримати значення domain та перевірити токен на достовірність.
Робота з зовнішніми лініями (ЗЛ)
Створення ЗЛ
Для того, щоб відправляти повідомлення в зовнішні лінії (далі ЗЛ), необхідно спочатку створити їх. Як правило, одне підключення має одну ЗЛ. Наприклад, в застосунку Instagram користувач може додати декілька акаунтів (підключень) і для кожного з них ми створюємо окрему ЗЛ.
Збережіть ідентифікатор створеної ЗЛ, він знадобиться пізніше.
🔍 Більше інформації про методи взаємодії з ЗЛ можна знайти ➡️ ТУТ
Створення чату
Далі необхідно створити чат. Якщо вам, наприклад, на вебхук будуть приходити івенти про повідомлення, то маючи ідентифікатор користувача, який надсилає ці повідомлення, ви можете створити чат. Тоді при подальших подібних подіях ви будете знати до якого саме чату надсилати оброблені повідомлення зі свого сервісу в ЗЛ.
Збережіть ідентифікатор створеного чату.
Це базові необхідні поля.
🔍 Більше інформації про взаємодію з чатами можна знайти ➡️ ТУТ
Відправка повідомлень
Якщо ваше повідомлення буде містити прикріплені файли, то вам необхідно спочатку завантажити їх.
1. Завантаження файлів (якщо потрібно):
🔍 Більше інформації про зберігання файлів можна знайти ➡️ ТУТ
2. Відправка повідомлення:
💡 Ви можете використовувати Markdown для форматування тексту повідомлення.
🔍 Більше інформації про маніпуляції з повідомленнями можна знайти ➡️ ТУТ
3. Отримання події про повідомлення:
Коли ви реєстрували застосунок, то надали нам поле sns_subscription_url. На цей URL ми будемо надсилати вебхук про повідомлення в ЗЛ. Подію, яка надходить, треба перевірити, а також виокремити тільки пейлоад. Для цього можна, наприклад, скористатись пакетом для PHP nipwaayoni/laravel-aws-sns та додати наступний код до контролера:
Ось приклад отриманого повідомлення з зображенням:
Після чого радимо перевірити, що це саме повідомлення, а також від ЗЛ:
Далі можете по ідентифікатору chatId знайти відповідний чат в вашій системі.
Створено: 26 вересня 2024 р. / Оновлено: 24 вересня 2025 р.