Справочник API

Conversations

GET /v1/conversations
# фильтры: status, assignedAgentId, contactId, since, limit, cursor

GET /v1/conversations/:id
GET /v1/conversations/:id/messages?limit=50&before=msg_…

POST /v1/conversations/:id/messages
{ "body": "…", "agentId": "usr_…" }

POST /v1/conversations/:id/assign     # body: { agentId }
POST /v1/conversations/:id/unassign
POST /v1/conversations/:id/close
POST /v1/conversations/:id/reopen
POST /v1/conversations/:id/spam

Contacts

GET  /v1/contacts?email=…
POST /v1/contacts
{ "name": "Анна", "email": "a@example.com", "locale": "ru" }

PATCH /v1/contacts/:id
{ "timezone": "Europe/Moscow" }

Knowledge Base

GET /v1/handbooks
GET /v1/handbooks/:slug/articles
GET /v1/articles/:id

Webhooks

GET    /v1/webhooks
POST   /v1/webhooks
{ "url": "https://api.acme.com/tgdesk",
  "events": ["conversation.created", "message.received"] }
DELETE /v1/webhooks/:id

Коды ошибок

• 401 — нет или истёк ключ.
• 403 — у ключа нет нужного скоупа.
• 404 — объект не принадлежит проекту ключа.
• 409 — конфликт состояний (`assign` на уже занятый диалог).
• 429 — превышен rate limit; смотрите заголовок `Retry-After`.

SDK

Готовые клиенты — @tgdesk/sdk-node и tgdesk-py. Оба сгенерированы из OpenAPI.

import { TGDesk } from '@tgdesk/sdk-node';
const tg = new TGDesk({ apiKey: process.env.TGDESK_KEY });
await tg.conversations.reply(id, { body: 'спасибо' });