API — это продукт, не довесок

Авторизация

В админке создайте API-ключ со скоупом (`conversations:read`, `conversations:write`, `kb:read`). Передавайте в заголовке:

Authorization: Bearer tgd_live_a4f9…c1b3

Основные эндпоинты

# Список диалогов
GET /v1/conversations?status=open&limit=50

# История одного
GET /v1/conversations/:id/messages

# Отправить ответ от имени оператора
POST /v1/conversations/:id/messages
{
  "body": "Спасибо, разобрались",
  "agentId": "usr_…"
}

# Создать контакт
POST /v1/contacts
{ "name": "Анна", "email": "a@example.com" }

Webhooks

Подпишитесь на события — каждое подписывается HMAC-SHA256 по вашему секрету:

• conversation.created — пришло новое обращение.
• conversation.assigned — оператор взял в работу.
• conversation.closed — диалог закрыт.
• message.received — клиент написал сообщение.

Проверка подписи

const sig = req.headers['x-tgdesk-signature'];
const mac = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (sig !== mac) throw new Error('bad signature');

Retries

Webhook-доставщик повторяет запрос с экспоненциальным backoff до 24 часов. После — событие переезжает в dead-letter очередь, видимую в админке.

Rate limits

По умолчанию — 60 запросов в минуту на ключ. На тарифе «Бизнес» — индивидуально.