API Documentation

Unicore Support REST API позволяет интегрировать чаты поддержки, управлять контактами и получать аналитику в ваших приложениях и автоматизациях.

Base URL: https://api.unisup.space/v1

Формат ответов

Все ответы возвращаются в формате JSON. Списковые эндпоинты содержат поля items, total, limit, offset.

Аутентификация

Все запросы к API должны содержать API-ключ. Ключи создаются в панели управления в разделе API-ключи.

Ключ показывается только один раз при создании. Сохраните его в безопасном месте.

Способ 1 — HTTP-заголовок (рекомендуется)

X-API-Key: usp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Способ 2 — Query-параметр

GET https://api.unisup.space/v1/sessions?api_key=usp_xxxx...

Как получить ключ

Войдите в панель управления как администратор
Перейдите в раздел API-ключи в левом меню
Нажмите Создать ключ, выберите нужные права доступа
Скопируйте и сохраните полученный ключ

Права доступа (Scopes)

Каждый API-ключ имеет набор разрешений (scopes). Запросы к закрытым разделам возвращают 403 Forbidden.

chats

Работа с чатами и сообщениями

Список и детали сессий
История сообщений
Отправка сообщений
Закрытие сессий

contacts

Управление контактами пользователей

Список контактов
Детальная информация
Обновление данных

analytics

Аналитика и статистика

Общая статистика
Распределение по статусам
Рейтинг и метрики

Коды ошибок

Код	Описание
400	Неверный запрос — проверьте тело запроса
401	Отсутствует или неверный API-ключ
403	Нет необходимого scope для этого эндпоинта
404	Ресурс не найден
409	Конфликт — например, сессия уже закрыта

{
  "detail": "Scope 'chats' required for this endpoint"
}

Чаты / Sessions chats

GET /v1/sessions chats

Возвращает список сессий текущего администратора.

Query-параметры

Параметр	Тип	Описание
status	string	Фильтр: `bot`, `waiting`, `operator`, `closed`
limit	int	Макс. кол-во (1–500, по умолчанию 50)
offset	int	Смещение (по умолчанию 0)

Пример ответа

{
  "items": [
    {
      "id": "sess_abc123",
      "status": "waiting",
      "user_name": "Иван Иванов",
      "user_email": "ivan@example.com",
      "last_activity": "2024-01-15T10:30:00"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

GET /v1/sessions/{session_id} chats

Детальная информация о конкретной сессии.

POST /v1/sessions/{session_id}/close chats

Закрывает сессию. Если сессия уже закрыта — вернёт {"detail": "already closed"}.

GET /v1/sessions/{session_id}/messages chats

История сообщений сессии, отсортированная по времени.

Query-параметры

Параметр	Тип	Описание
limit	int	Макс. кол-во (1–1000, по умолчанию 100)

Пример ответа

{
  "items": [
    {
      "id": "msg_001",
      "session_id": "sess_abc123",
      "sender_type": "user",
      "content": "Здравствуйте, нужна помощь",
      "created_at": "2024-01-15T10:25:00"
    }
  ],
  "total": 12
}

POST /v1/sessions/{session_id}/messages chats

Отправляет сообщение от имени оператора в указанную сессию. Сессия не должна быть закрыта.

Тело запроса

{
  "content": "Добрый день! Чем могу помочь?"
}

Возвращает

// Созданное сообщение, HTTP 201
{
  "id": "msg_xyz",
  "session_id": "sess_abc123",
  "sender_type": "operator",
  "sender_id": "api:key-id",
  "content": "Добрый день! Чем могу помочь?",
  "channel": "api",
  "created_at": "2024-01-15T10:31:00"
}

Контакты contacts

GET /v1/contacts contacts

Список всех контактов (end_users) администратора.

Query-параметры

Параметр	Тип	Описание
limit	int	1–500, по умолчанию 50
offset	int	По умолчанию 0

GET /v1/contacts/{contact_id} contacts

Детальная информация о контакте.

PUT /v1/contacts/{contact_id} contacts

Обновление данных контакта. Можно передавать только изменяемые поля.

Тело запроса

{
  "name": "Иван Петров",
  "email": "ivan.petrov@example.com",
  "phone": "+7 900 123 45 67"
}

Аналитика analytics

GET /v1/analytics analytics

Сводная аналитика по аккаунту: статистика сессий, сообщений, рейтинг, контакты.

Пример ответа

{
  "total_sessions": 254,
  "sessions_by_status": {
    "bot": 12,
    "waiting": 5,
    "operator": 8,
    "closed": 229
  },
  "total_messages": 3847,
  "avg_rating": 4.72,
  "total_contacts": 186
}

Примеры запросов

cURL

# Получить список открытых чатов
curl -H "X-API-Key: usp_ваш_ключ" \
  "https://api.unisup.space/v1/sessions?status=waiting"

# Отправить сообщение
curl -X POST \
  -H "X-API-Key: usp_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"content": "Менеджер скоро ответит"}' \
  "https://api.unisup.space/v1/sessions/SESS_ID/messages"

Python

import requests

API_KEY = "usp_ваш_ключ"
BASE = "https://api.unisup.space/v1"
headers = {"X-API-Key": API_KEY}

# Список ожидающих чатов
resp = requests.get(f"{BASE}/sessions", headers=headers, params={"status": "waiting"})
sessions = resp.json()["items"]

# Отправить сообщение
requests.post(
    f"{BASE}/sessions/{sessions[0]['id']}/messages",
    headers=headers,
    json={"content": "Добрый день!"}
)

JavaScript / Node.js

const API_KEY = 'usp_ваш_ключ';
const BASE = 'https://api.unisup.space/v1';

// Получить аналитику
const res = await fetch(`${BASE}/analytics`, {
  headers: { 'X-API-Key': API_KEY }
});
const data = await res.json();
console.log(data.total_sessions, data.avg_rating);