Быстрый старт

Отправляйте уведомления клиентам через Telegram, WhatsApp, MAX и SMS — через единый REST API с авторизацией OAuth2. От регистрации до первого отправленного уведомления — 6 шагов.

Что умеет API

Telegram, WhatsApp, MAX и SMS через единый интерфейс
Идемпотентные запросы — безопасный retry при сетевых ошибках
Webhook для получения статусов доставки
Авторизация по client_id / client_secret без привязки к пользователю

Шаг 1. Получите credentials

Перейдите в timevisit.ru/ui/integrations/, найдите карточку HTTP API и нажмите «Создать интеграцию». После подтверждения client_id и client_secret придут на почту.

Карточка HTTP API с кнопкой Создать интеграцию — Создайте интеграцию в карточке HTTP API.Открыть оригинал

На почту придёт письмо с двумя значениями. Используйте их в запросе токена:

Данные HTTP API из письма

Ваш идентификатор клиента: client_idchat-center-integration-client-<uuid>
Ваш ключ доступа к системе: client_secretЗначение ключа из письма

Это пример формата. Ваши значения находятся в письме интеграции HTTP API.

Шаг 2. Подключите канал доставки

После создания интеграции откроется Нотификационная стратегия — список доступных каналов. Нажмите «Подключить» рядом с нужным каналом и пройдите процесс подключения.

Нотификационная стратегия

Подключите каналы для отправки уведомлений.

Telegram BotПодключить
Telegram PersonalПодключить
WhatsApp PersonalПодключить
MAX BotПодключить
MAX PersonalПодключить
SMSПодключить

Пример списка каналов. SMS всегда остаётся последним шагом каскада.

Порядок карточек определяет приоритет: если первый канал не доставил сообщение, сервис автоматически попробует следующий. SMS — резервный канал, который всегда остаётся последним в каскаде. Если сообщение доставлено через мессенджер, SMS не отправляется.

Шаг 3. Получите токен

curl
Python
Node.js
PHP

curl -X POST https://timevisit.ru/auth/realms/std/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET"

import requests

resp = requests.post(
    "https://timevisit.ru/auth/realms/std/protocol/openid-connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
    },
)
token = resp.json()["access_token"]

const params = new URLSearchParams({
  grant_type: "client_credentials",
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET",
});

const resp = await fetch(
  "https://timevisit.ru/auth/realms/std/protocol/openid-connect/token",
  { method: "POST", body: params }
);
const { access_token: token } = await resp.json();

$ch = curl_init("https://timevisit.ru/auth/realms/std/protocol/openid-connect/token");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        "grant_type"    => "client_credentials",
        "client_id"     => "YOUR_CLIENT_ID",
        "client_secret" => "YOUR_CLIENT_SECRET",
    ]),
]);
$data  = json_decode(curl_exec($ch), true);
$token = $data["access_token"];

Пример успешного ответа (HTTP 200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Срок действия токена указан в expires_in в секундах; в примере это 5 минут. Кешируйте его и обновляйте до истечения. При HTTP 401 с error: "invalid_client" проверьте действующую пару client_id / client_secret для интеграции HTTP API — подробнее в аутентификации.

Шаг 4. Отправьте уведомление

Base URL

https://timevisit.ru/unotice-openapi-client

curl
Python
Node.js
PHP

curl -X POST https://timevisit.ru/unotice-openapi-client/api/v1/notifications \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "value": "79001234567" },
    "notificationText": "Ваш заказ №12345 передан в доставку.",
    "externalId": "order-12345-notify-1"
  }'

resp = requests.post(
    "https://timevisit.ru/unotice-openapi-client/api/v1/notifications",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "recipient": {"value": "79001234567"},
        "notificationText": "Ваш заказ №12345 передан в доставку.",
        "externalId": "order-12345-notify-1",
    },
)
notification_id = resp.json()["notificationId"]

const resp = await fetch(
  "https://timevisit.ru/unotice-openapi-client/api/v1/notifications",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipient: { value: "79001234567" },
      notificationText: "Ваш заказ №12345 передан в доставку.",
      externalId: "order-12345-notify-1",
    }),
  }
);
const { notificationId } = await resp.json();

$ch = curl_init("https://timevisit.ru/unotice-openapi-client/api/v1/notifications");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode([
        "recipient"        => ["value" => "79001234567"],
        "notificationText" => "Ваш заказ №12345 передан в доставку.",
        "externalId"       => "order-12345-notify-1",
    ]),
]);
$result = json_decode(curl_exec($ch), true);
$notificationId = $result["notificationId"];

Ответ HTTP 202 — уведомление принято к обработке:

{
  "notificationId": "550e8400-e29b-41d4-a716-446655440000"
}

Сохраните notificationId для сопоставления с webhook. Ответ 202 не подтверждает доставку: конечный статус придёт через webhook.

Идемпотентность

Всегда передавайте externalId. При сетевой ошибке повторите тот же запрос с тем же externalId — в рамках одной интеграции повторная отправка не случится. Для нового уведомления используйте новый externalId.

Шаг 5. Настройте webhook для статусов доставки

Если вам нужно знать, доставлено ли сообщение, зарегистрируйте URL своего сервера до отправки уведомления:

curl
Python
Node.js
PHP

curl -X POST https://timevisit.ru/unotice-openapi-client/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.example.com/webhook"}'

requests.post(
    "https://timevisit.ru/unotice-openapi-client/api/v1/webhooks",
    headers={"Authorization": f"Bearer {token}"},
    json={"url": "https://your-server.example.com/webhook"},
)

await fetch("https://timevisit.ru/unotice-openapi-client/api/v1/webhooks", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://your-server.example.com/webhook" }),
});

$ch = curl_init("https://timevisit.ru/unotice-openapi-client/api/v1/webhooks");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode(["url" => "https://your-server.example.com/webhook"]),
]);
curl_exec($ch);

Когда нотификация достигнет терминального статуса, сервис отправит POST на ваш URL:

{
  "eventType": "NOTIFICATION_STATUS_CHANGED",
  "notificationStatusChanged": {
    "notificationId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "DELIVERED",
    "deliveredAt": "2024-01-15T10:30:00Z"
  }
}

При status: "FAILED" вместо deliveredAt придёт массив errors с кодом и описанием причины. Ответьте 2xx — событие считается принятым. При 5xx / 408 / 429 сервис повторит запрос до 8 раз с exponential backoff (суммарное окно ≈ 42 минуты). Одна интеграция — один webhook URL. Если webhook уже зарегистрирован, обновите URL через PUT /api/v1/webhooks; повторный POST вернёт 400.

Шаг 6. Готово

Что дальше:

Аутентификация — подробнее про токены и scopes
Справочник API — все эндпоинты и схемы
Промт для ИИ-ассистента — скопируйте в ChatGPT или Claude для автоматической генерации кода под ваш стек

Что умеет API​

Шаг 1. Получите credentials​

Шаг 2. Подключите канал доставки​

Шаг 3. Получите токен​

Шаг 4. Отправьте уведомление​

Шаг 5. Настройте webhook для статусов доставки​

Шаг 6. Готово​