Реєстрація
Для реєстрації вашого застосунку в нашій системі, підготуйте та надайте наступну інформацію ⬇️
{
"code": "my_custom_app_code", // унікальний код вашої інтеграції
"callback_url": "https://my_custom_app_host", // url на який будуть відправлятись запити на встановлення та видалення додатку (для цих дій ми додаємо до callback_url ще /portals/install та /portals/uinstall відповідно)
"price": "true", // чи буде платна ваша інтеграція
"sns_subscription_url": null, // url на який будуть відправлятись повідомлення з ваших зовнішніх ліній
"localized_data": [
{
"locale": "en-US",
"name": "Назва додатку",
"logo": "https://...", // посилання на логотип. Ми можемо зберегти у себе логотип, його розмір має бути 240х240 px
"short_description": "Короткий опис додатку, який буде показуватись на сторінці маркетплейсу",
"description": "<div class="app-description"><div id="slider"><div class="slides"><img src="https://uspacy.github.io/static/unitalk-slider1.png" width="100%" /></div><div class="slides"><img src="https://uspacy.github.io/static/unitalk-slider2.png" width="100%" /></div><div class="slides"><img src="https://uspacy.github.io/static/binotel-slider3.png" width="100%" /></div><div class="slides"><img src="https://uspacy.github.io/static/unitalk-slider4.png" width="100%" /></div><div class="slides"><img src="https://uspacy.github.io/static/unitalk-slider5.png" width="100%" /> </div> </div>
<h5 class="title">
Розширюйте можливості вашої CRM, підключивши до неї IP-телефонію UniTalk.
</h5>
<p class="paragraph">
Одним із ключів до успішних продажів є задоволення потреб клієнтів. А використання IP-телефонії дозволяє налагодити комунікацію з ними та за рахунок цього якісно підвищити рівень обслуговування.
</p>
<br />
<p class="paragraph">
Для того, щоб телефонувати клієнтам не потрібно встановлювати додаткові сторонні програми на ваші пристрої. Завдяки спеціальному розширенню у Google Chrome можна здійснювати вхідні та приймати вихідні дзвінки на будь-яких сторінках браузера, враховуючи ваш Простір Uspacy.
</p>
<img src="https://uspacy.github.io/static/unitalk-slider3.png" alt="unitalk" />
<p class="paragraph">
Тобто, не потрібно згортати відкриті картки сутностей у CRM, щоб набрати номер клієнта або запустити обдзвін. Розширення можна розмістити поверх сторінки та паралельно працювати з базою клієнтів чи угод.
</p>
</div>"
}
],
"developer_name": "Uspacy", // Назва вашої компаніїґ
"developer_link": "https://uspacy.com/" // Посилання на ресурс вашої компанії
}
💡Ви можете надати описи та назви на декількох мовах для кращої локалізації. На даний момент ми підтримуємо наступні мови: українська, англійська, португальська, польська, іспанська.
Locale | Language |
uk | Ukraine |
en-US | English US |
pt-BR | Portuguese |
pl | Polish |
es-ES | Spanish |
Після надання цієї інформації, ви отримаєте client_id та secret_id для подальшої розробки.
Розробка бекенд частини
Ми підготували шаблон на базі Laravel PHP з базовими налаштуваннями.
🔍 Ознайомтесь за посиланням ➡️ ТУТ
Встановлення застосунку
Коли користувач встановлює застосунок, ви отримаєте наступний запит:
POST {callback_url}/portals/install
Content-Type: application/json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiry_date": 1727072924
}
❗️Ми використовуємо JWT токен. Для визначення порталу, який встановлює застосунок, необхідно розпарсити токен та перевірити його достовірність. Приклад реалізації цієї логіки можна побачити за посиланням ➡️ ТУТ
Вам необхідно зберегти:
token – живе 1 добу
refresh_token – живе 30 днів
expiry_date – для перевірки валідності токена
Рекомендується створити cron для оновлення токенів порталів.
🔍 Приклад можна знайти ➡️ ТУТ
Видалення застосунку
При видаленні застосунку ви отримаєте:
DELETE {callback_url}/portals/uninstall
Authorization: Bearer JWT_TOKEN
💡 Токен знаходиться в header Authorization. Необхідно запарсити токен, отримати значення domain та перевірити токен на достовірність.
Робота з зовнішніми лініями (ЗЛ)
Створення ЗЛ
Для того, щоб відправляти повідомлення в зовнішні лінії (далі ЗЛ), необхідно спочатку створити їх. Як правило, одне підключення має одну ЗЛ. Наприклад, в застосунку Instagram користувач може додати декілька акаунтів (підключень) і для кожного з них ми створюємо окрему ЗЛ.
POST https://{domain}.uspacy.ua/messenger/v1/external-lines
Content-Type: application/json
{
"name": "...", // унікальне ім'я
"icon": "https://...", // посилання на іконку, це зображення буде відображатись справа знизу біля іконки чату у вкладці ЗЛ
"phoneNumber": "...", // якщо є можливість додати номер, якщо ні, то можете продублювати сюди значення з поля name
"externalId": "..." // унікальний ідентифікатор ЗЛ
}
Збережіть ідентифікатор створеної ЗЛ, він знадобиться пізніше.
🔍 Більше інформації про методи взаємодії з ЗЛ можна знайти ➡️ ТУТ
Створення чату
Далі необхідно створити чат. Якщо вам, наприклад, на вебхук будуть приходити івенти про повідомлення, то маючи ідентифікатор користувача, який надсилає ці повідомлення, ви можете створити чат. Тоді при подальших подібних подіях ви будете знати до якого саме чату надсилати оброблені повідомлення зі свого сервісу в ЗЛ.
POST https://{domain}.uspacy.ua/messenger/v1/chats
Content-Type: application/json
{
"name": "...",
"type": "EXTERNAL",
"id": "...",
"externalLines": [], // додайте сюди ID ЗЛ, яку створили раніше
"pictureUrl": "https://...",
"meta": [ // використовується для прив'язки чату до CRM
{
"type": "integration_code", // радимо додати сюди код вашої інтеграції
"value": "..." // можете додати номер телефону або ID
}
]
}
Збережіть ідентифікатор створеного чату.
Це базові необхідні поля.
🔍 Більше інформації про взаємодію з чатами можна знайти ➡️ ТУТ
Відправка повідомлень
Якщо ваше повідомлення буде містити прикріплені файли, то вам необхідно спочатку завантажити їх.
1. Завантаження файлів (якщо потрібно):
POST https://{domain}.uspacy.ua/files/v1/files
Content-Type: multipart/form-data
{
"entityType": "chat_message",
"entity_id": "...", // ідентифікатор повідомлення
"files": []
}
🔍 Більше інформації про зберігання файлів можна знайти ➡️ ТУТ
2. Відправка повідомлення:
POST https://{domain}.uspacy.ua/messenger/v1/messages
Content-Type: application/json
{
"id": "...",
"externalLine": "",
"chatId": "",
"type": "MESSAGE", // більше про типи описано в документації
"message": "Повідомлення ...",
"externalId": "...",
"externalAuthorId": "...", // ID відправника повідомлення
"parentMessage": "...", // ID батьківського повідомлення
"attachedFiles": [ // дані завантажених файлів з попереднього кроку
{
"id": "...",
"entityId": "...",
"lastModified": 3434434343,
"originalFilename": "...",
"size": "...",
"url": "..."
}
]
}
💡 Ви можете використовувати Markdown для форматування тексту повідомлення.
🔍 Більше інформації про маніпуляції з повідомленнями можна знайти ➡️ ТУТ
3. Отримання події про повідомлення:
Коли ви реєстрували застосунок, то надали нам поле sns_subscription_url. На цей URL ми будемо надсилати вебхук про повідомлення в ЗЛ. Подію, яка надходить, треба перевірити, а також виокремити тільки пейлоад. Для цього можна, наприклад, скористатись пакетом для PHP nipwaayoni/laravel-aws-sns та додати наступний код до контролера:
$message = Message::fromJsonString($request->getContent());
$snsMessage = new SnsMessage($message);
$messageBody = json_decode($snsMessage->content(), true);
Ось приклад отриманого повідомлення з зображенням:
{
"data": {
"action": "create",
"domain": "demo.uspacy.com",
"entity": {
"attachedFiles": [
{
"creatorId": 3,
"entityId": "37741d88-4903-4cee-b363-6404156c6d82",
"entityType": "chat_message",
"id": 467,
"lastModified": 1727256812,
"originalFilename": "Untitled.jpg",
"size": 5422,
"uploadId": "e3eb7705-8cb8-....",
"url": "https://..."
}
],
"authorId": 3937,
"chatId": "89cc8fc3-ec6c-42ca-9310...",
"externalLine": {
"externalId": "8b64d20c-e616-4e2f...",
"icon": "https://...",
"id": "66eaf2c703bd0...",
"name": "Антон Чернов",
"phoneNumber": "Антон Чернов",
"portal": "test.uspacy.com",
"timestamp": 1726673607915
},
"id": "37741d88-4903-4cee-b363-...",
"mentioned": null,
"message": "Тестове повідомлення",
"parent": {
"active": true,
"externalLines": [
{
"externalId": "8b64d20c-e616-4e2f-b841-...",
"icon": "https://...",
"id": "66eaf2c703bd0d42...",
"name": "Антон Чернов",
"phoneNumber": "Антон Чернов",
"portal": "test.uspacy.com",
"timestamp": 1726673607915
}
],
"id": "89cc8fc3-ec6c-42ca-9310-...",
"lastMessage": {
"attachedFiles": [
{
"creatorId": 3,
"entityId": "37741d88-4903-4cee-b363-...",
"entityType": "chat_message",
"id": 467,
"lastModified": 1727256812,
"originalFilename": "Untitled.jpg",
"size": 5422,
"uploadId": "e3eb7705-8cb8-46e2-900b-...",
"url": "https://..."
}
],
"authorId": 3937,
"chatId": "89cc8fc3-ec6c-42ca-9310-...",
"externalLine": "66eaf2c703bd0d420...",
"id": "37741d88-4903-4cee-b363-...",
"mentioned": null,
"message": "Тестове повідомлення",
"readBy": null,
"relations": null,
"timestamp": 1727256825340,
"type": "MESSAGE"
},
"members": [
3937
],
"meta": [
{
"type": "instagram",
"value": "416955767636055"
}
],
"name": "Антон Чернов",
"ownerId": 3934,
"pictureUrl": "https://...",
"portals": [
"test.uspacy.com"
],
"timestamp": 1727256825340,
"type": "EXTERNAL"
},
"readBy": null,
"relations": null,
"timestamp": 1727256825340,
"type": "MESSAGE"
},
"service": "messenger",
"timestamp": "2024-09-25T09:33:45.390Z",
"user_id": 3
},
"env": "com",
"metadata": null,
"request_id": "c627affe-7a73-449c-baaf-...",
"topic": "Notifications",
"type": "message"
}
Після чого радимо перевірити, що це саме повідомлення, а також від ЗЛ:
if($messageBody['type'] === 'message' &&
isset($message['data']['entity']['externalLine']))
Далі можете по ідентифікатору chatId знайти відповідний чат в вашій системі.