API Reference

REST API для программного управления виджетами и аналитикой WritesApp. Доступно на тарифе Business.

Base URL

https://writesapp.ru/api/v1

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

Bearer Token в заголовке Authorization

Формат

JSON запросы и ответы. UTF-8.

Примеры кода

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

Все запросы к REST API должны содержать API ключ в заголовке Authorization.

Authorization: Bearer wa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Получение API ключа

API ключ доступен в тарифе Business. Создайте ключ в настройках аккаунта.

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

Scope	Описание
`widgets:read`	Чтение списка и настроек виджетов
`widgets:write`	Создание и редактирование виджетов
`analytics:read`	Чтение аналитики и статистики

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

curl -X GET "https://writesapp.ru/api/v1/widgets" \
  -H "Authorization: Bearer wa_your_api_key"

Виджеты

CRUD операции для управления виджетами.

GET/api/v1/widgetsСписок виджетов

Получить список всех виджетов аккаунта

Параметры запроса

`page`	Номер страницы (по умолчанию 1)
`limit`	Количество на странице (макс. 100)

curl -X GET "https://writesapp.ru/api/v1/widgets?page=1&limit=10" \
  -H "Authorization: Bearer wa_your_api_key"

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

{
  "data": [
    {
      "id": "clx123abc456",
      "name": "Основной виджет",
      "domain": "example.com",
      "isActive": true,
      "eventsCount": 1234,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

POST/api/v1/widgetsСоздать виджет

Создать новый виджет

curl -X POST "https://writesapp.ru/api/v1/widgets" \
  -H "Authorization: Bearer wa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Мой виджет",
    "domain": "example.com",
    "channels": [
      {"type": "whatsapp", "value": "79001234567", "label": "WhatsApp"}
    ],
    "config": {
      "position": "bottom-right",
      "color": "#25D366"
    }
  }'

GET/api/v1/widgets/:idПолучить виджет

Получить полную информацию о виджете включая настройки

curl -X GET "https://writesapp.ru/api/v1/widgets/clx123abc456" \
  -H "Authorization: Bearer wa_your_api_key"

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

{
  "data": {
    "id": "clx123abc456",
    "name": "Основной виджет",
    "domain": "example.com",
    "isActive": true,
    "config": {
      "position": "bottom-right",
      "size": "medium",
      "color": "#25D366",
      "style": "classic",
      "title": "Напишите нам",
      "greeting": "Привет! Чем помочь?"
    },
    "channels": [
      {"type": "whatsapp", "value": "79001234567", "label": "WhatsApp", "device": "all"},
      {"type": "telegram", "value": "mycompany", "label": "Telegram", "device": "all"}
    ],
    "triggers": {
      "delay": 3,
      "scrollPercentage": 50,
      "exitIntent": true
    },
    "eventsCount": 1234,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z"
  }
}

PUT/api/v1/widgets/:idОбновить виджет

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

curl -X PUT "https://writesapp.ru/api/v1/widgets/clx123abc456" \
  -H "Authorization: Bearer wa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Новое название",
    "isActive": false,
    "config": {"color": "#FF4B3A"}
  }'

DELETE/api/v1/widgets/:idУдалить виджет

Удалить виджет и всю связанную аналитику

curl -X DELETE "https://writesapp.ru/api/v1/widgets/clx123abc456" \
  -H "Authorization: Bearer wa_your_api_key"

Структура данных виджета

channels — Каналы связи

Поле	Тип	Описание
`type`	string	whatsapp, telegram, viber, vk, max, phone, email, callback, livechat, custom
`value`	string	Номер/username/ссылка
`label`	string	Название кнопки
`device`	string	all, desktop, mobile

config — Внешний вид и поведение

Поле	Тип	Описание
`position`	string	bottom-right, bottom-left, top-right, top-left
`size`	string	small, medium, large
`style`	string	classic, horizontal, bubble, minimal, glass, premium
`shape`	string	circle, rounded, square
`color`	string	HEX акцентный цвет (#25D366)
`animation`	string	none, bounce, pulse, shake, glow
`title`	string	Заголовок панели
`greeting`	string	Подзаголовок/приветствие
`themeMode`	string	auto, light, dark
`showCopyright`	boolean	Копирайт «Работает на WritesApp» (Pro+)
`qrEnabled`	boolean	QR-коды для десктопных пользователей (Pro+)
`showOnMobile` / `showOnDesktop`	boolean	Видимость на устройствах
`offsetX` / `offsetY`	number	Отступы от краёв экрана (px)

Поля Делового стиля (premium)

`managerImage`	string	URL аватара менеджера
`managerName`	string	Имя менеджера
`managerTitle`	string	Должность менеджера
`showOnlineStatus`	boolean	Зелёный индикатор «Онлайн»

triggers — Условия показа

Поле	Тип	Описание
`delay`	number	Задержка показа (сек)
`scrollPercentage`	number	Показ при прокрутке (%)
`exitIntent`	boolean	Показ при попытке уйти
`workingHoursEnabled`	boolean	Ограничение по рабочим часам
`urlMode`	string	all, include, exclude
`repeatInterval`	string	session, daily, weekly, once

Аналитика

Получение статистики и событий виджетов.

GET/api/v1/analytics

Параметры запроса

Параметр	Тип	Описание
`widget_id`	string	ID виджета (опц.)
`period`	string	1d, 7d, 30d, 90d
`event`	string	view, click, channel_click
`channel`	string	whatsapp, telegram, viber...

curl -X GET "https://writesapp.ru/api/v1/analytics?period=30d&event=channel_click" \
  -H "Authorization: Bearer wa_your_api_key"

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

{
  "data": [
    {
      "id": "evt_abc123",
      "widgetId": "clx123abc456",
      "event": "channel_click",
      "channel": "whatsapp",
      "timestamp": "2024-01-15T14:30:00.000Z"
    }
  ],
  "summary": {
    "views": 1500,
    "clicks": 320,
    "channelClicks": 180
  },
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 180,
    "totalPages": 2
  }
}

Типы событий

`view`	Виджет показан на странице
`click`	Пользователь открыл виджет
`channel_click`	Переход в мессенджер

Webhooks

Получайте уведомления о событиях виджета в реальном времени.

Настройка

Укажите URL вебхука в настройках виджета. WritesApp отправит POST-запрос при каждом событии.

Формат запроса

POST https://your-server.com/webhook
Content-Type: application/json
X-Webhook-Signature: hmac-sha256-hex (если задан секретный ключ)

{
  "event": "channel_click",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "widgetId": "clx123abc456",
  "channel": "whatsapp",
  "visitorId": "wa_v_abc123",
  "metadata": {
    "url": "https://example.com/product",
    "referrer": "https://google.com",
    "userAgent": "Mozilla/5.0...",
    "device": "desktop"
  }
}

Типы событий

Событие	Описание
`view`	Виджет показан на странице
`click`	Виджет открыт (кнопка нажата)
`channel_click`	Клик по каналу связи
`callback_lead`	Отправлена заявка на обратный звонок

Лимиты запросов

API имеет ограничения на количество запросов для защиты от злоупотреблений.

Тариф	Лимит	Окно
Pro	100 запр.	1 мин
Business	1000 запр.	1 мин

Заголовки ответа

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

Коды ошибок

API возвращает стандартные HTTP коды ответа.

Код	Описание	Решение
`200`	Успешный запрос	—
`400`	Неверный запрос	Проверьте параметры
`401`	Не авторизован	Проверьте API ключ
`403`	Запрещён	Недостаточно прав
`404`	Не найдено	Ресурс не существует
`429`	Rate limit	Дождитесь сброса
`500`	Ошибка сервера	Повторите позже

Формат ошибки

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API ключ недействителен или отозван",
    "details": null
  }
}

Нужна помощь с интеграцией?

Свяжитесь с нами — поможем с настройкой API

Документация Написать в поддержку