Реєстрація
Для реєстрації вашого застосунку в нашій системі, підготуйте та надайте наступну інформацію ⬇️
☝🏻 Підказка:
- code — це унікальний код вашої інтеграції;
- callback_url — це URL, на який будуть відправлятись запити на встановлення та видалення застосунку (для цих дій ми додаємо до callback_url ще /portals/install та /portals/uinstall відповідно);
- price — true чи буде платна ваша інтеграція, а false якщо ні;
- sns_subscription_url — URL на який будуть відправлятись події про нові повідомлення в зовнішніх каналах.
💡Ви можете надати описи та назви на декількох мовах для кращої локалізації. На даний момент ми підтримуємо наступні мови: українська, англійська, португальська, польська, іспанська, німецька.
| 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 користувач може додати декілька акаунтів (підключень) і для кожного з них ми створюємо окрему ЗЛ.
☝🏻Підказка:
- name — це унікальне ім'я;
- icon — це посилання на іконку, це зображення буде відображатись справа знизу біля іконки чату у вкладці ЗЛ;
- phoneNumber — якщо є можливість додати номер, якщо ні, то можете продублювати сюди значення з поля name;
- externalId — унікальний ідентифікатор ЗЛ.
☝🏻 Збережіть ідентифікатор створеної ЗЛ, він знадобиться пізніше.
🔍 Більше інформації про методи взаємодії з ЗЛ можна знайти ➡️ ТУТ
Створення чату
Далі необхідно створити чат. Якщо вам, наприклад, на вебхук будуть приходити івенти про повідомлення, то маючи ідентифікатор користувача, який надсилає ці повідомлення, ви можете створити чат. Тоді при подальших подібних подіях ви будете знати до якого саме чату надсилати оброблені повідомлення зі свого сервісу в ЗЛ.
☝🏻 Підказка:
- externalLines — ID зовнішньої лінії яку створили раніше;
- meta — використовується для прив'язки чату до CRM;
- meta.type — варіанти: phone, widgetUser, username, facebook, instagram, telegram, twitter, viber або whatsapp;
- meta.value — можете додати номер телефону або ID.
☝🏻 Збережіть ідентифікатор створеного чату.
Це базові необхідні поля.
🔍 Більше інформації про взаємодію з чатами можна знайти ➡️ ТУТ
Відправка повідомлень
Якщо ваше повідомлення буде містити прикріплені файли, то вам необхідно спочатку завантажити їх.
1. Завантаження файлів (якщо потрібно):
🔍 Більше інформації про зберігання файлів можна знайти ➡️ ТУТ
2. Відправка повідомлення:
☝🏻 Підказка:
- type — більше про типи описано в документації ➡️ ТУТ;
- externalAuthorId — ID відправника повідомлення;
- parentMessage — ID батьківського повідомлення;
- attachedFiles — масив завантажених файлів з попереднього кроку.
💡 Ви можете використовувати Markdown для форматування тексту повідомлення.
🔍 Більше інформації про маніпуляції з повідомленнями можна знайти ➡️ ТУТ
3. Отримання події про повідомлення:
Коли ви реєстрували застосунок, то надали нам поле sns_subscription_url. На цей URL ми будемо надсилати вебхук про повідомлення в ЗЛ. Подію, яка надходить, треба перевірити, а також виокремити тільки пейлоад. Для цього можна, наприклад, скористатись пакетом для PHP nipwaayoni/laravel-aws-sns та додати наступний код до контролера:
Ось приклад отриманого повідомлення з зображенням:
Після чого радимо перевірити, що це саме повідомлення, а також від ЗЛ:
Далі можете по ідентифікатору chatId знайти відповідний чат в вашій системі.
Створено: 26 вересня 2024 р. / Оновлено: 24 вересня 2025 р.