Подключите свой сервис к TryDesk

Отправляйте обращения клиентов и служебные уведомления из своего приложения. Доставляйте ответы операторов через собственный адаптер Telegram, email или другого канала.

1. Создайте интеграцию

В рабочем пространстве откройте Интеграции и создайте источник обращений. Сохраните показанный один раз ключ на своём сервере в переменной TRYDESK_API_KEY. Ключ определяет рабочее пространство и источник; передавать projectId или workspaceId не нужно.

Не размещайте ключ в браузере, мобильном приложении или логах. Коннектор использует HTTP API; прямой доступ к Firestore или Storage TryDesk ему не нужен.

2. Установите SDK для Node.js

SDK 0.2.0 · Node.js 22.12+ (22.x) · JavaScript / TypeScript · без зависимостей времени выполнения.

Публикация в npm ожидает доступа к scope @trydesk. Команда установки ниже заработает после публикации. HTTP API уже доступен.

npm install @trydesk/sdk@0.2.0

Пакет npm (ожидает публикации) · Справочник SDK (English) · Лицензия MIT (только SDK)

3. Отправьте сообщение

import { TryDesk, imageFromFile } from '@trydesk/sdk';

const apiKey = process.env.TRYDESK_API_KEY;
if (!apiKey) throw new Error('Set TRYDESK_API_KEY on the server');
const desk = new TryDesk({ apiKey });
const result = await desk.messages.send({
  eventId: 'telegram:BOT_ID:UPDATE_ID',
  externalConversationId: 'telegram-chat-42',
  sender: { externalId: '42', displayName: 'Алексей', kind: 'customer' },
  text: 'Помогите, пожалуйста, с доступом к аккаунту',
  // При необходимости: images: [await imageFromFile('/tmp/screenshot.png')],
});
console.log(result.conversationId, result.messageId, result.duplicate);

eventId — идентификатор события в вашем источнике, а не номер обращения TryDesk. При повторной отправке того же события сохраняйте его ID. Для Telegram используйте ID бота + update_id. Если ID не указан, SDK создаёт его и повторно использует при HTTP-повторах. Для повторов после перезапуска используйте ID события источника или сохраняйте его в своей очереди.

externalConversationId должен оставаться одинаковым для внешнего чата, а sender.externalId — для отправителя. Для служебных уведомлений используйте kind: 'service' и ID, например alarm. Пользователи разных интеграций разделены.

HTTP без SDK

curl 'https://api.trydesk.io/v1/messages' \
  -H "Authorization: Bearer $TRYDESK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"eventId":"event-1","externalConversationId":"chat-42","sender":{"externalId":"42"},"message":{"text":"Нужна помощь"}}'

Текст передаётся в JSON. Изображения отправляйте через multipart/form-data: поле payload с JSON и повторяющиеся файловые поля images. SDK автоматически устанавливает multipart boundary.

curl 'https://api.trydesk.io/v1/messages' \
  -H "Authorization: Bearer $TRYDESK_API_KEY" \
  --form-string 'payload={"eventId":"image-1","externalConversationId":"chat-42","sender":{"externalId":"42"},"message":{"text":"Скриншот"}}' \
  --form 'images=@./screenshot.png;type=image/png'

Новое событие получает HTTP 201. Точный повтор — HTTP 200 с duplicate: true. Если отправить тот же eventId с другим содержимым, сервер вернёт 409. Ошибки API имеют формат {"error":{"code":"…","message":"…"}}.

400: некорректные данные; 401/403: ключ или отключённый источник; 413: превышение размера; 415: неподдерживаемый тип. При 429/503 повторите запрос через время из Retry-After с тем же ID и файлами. Ошибки валидации повторять без исправления не нужно.

4. Доставляйте ответы операторов

Включите ответы при создании интеграции и укажите свой Pub/Sub topic. Предоставьте серверному аккаунту TryDesk право публикации в этот topic. Коннектор подписывается на события и получает только идентификаторы:

{ "deliveryId": "…", "workspaceId": "…", "integrationId": "…",
  "conversationId": "…", "messageId": "…" }

Тем же ключом интеграции получите задачу доставки, её текст и внешнего адресата. Зафиксируйте начало отправки, один раз вызовите API своего канала и подтвердите полученные идентификаторы сообщений провайдера.

const task = await desk.deliveries.claim({ deliveryId });
if (task.status === 'ready') {
  const lease = { deliveryId, leaseId: task.leaseId };
  const started = await desk.deliveries.start(lease);
  if (started.status === 'sending') {
    // Отправьте сообщение через свой адаптер один раз и подтвердите ID:
    // await desk.deliveries.complete({ ...lease, providerMessageIds });
  }
}

В одном диалоге ответы доставляются по порядку. Для skip/waiting_for_previous подтвердите событие Pub/Sub (ACK): завершение предыдущего ответа запустит доставку следующего. Сейчас поддерживаются только текстовые ответы до 10000 символов; адаптер Telegram разделяет длинный текст на части.

Таймаут не всегда означает отказ провайдера. При неопределённом результате или частичной отправке используйте unknown и не повторяйте вызов провайдера автоматически. retry подходит только для подтверждённого временного отказа. TryDesk не гарантирует отправку ровно один раз у провайдеров без поддержки идемпотентности. Статус отправки означает приём провайдером, а не прочтение получателем.

Адреса API

Основной API: https://api.trydesk.io. Если ваша сеть не может обратиться к этому домену, доступны эквивалентные адреса Firebase Hosting:

const desk = new TryDesk({
  apiKey: process.env.TRYDESK_API_KEY ?? '',
  endpoint: 'https://helpdesk-1510b-api.web.app/v1/messages',
  deliveryEndpoint: 'https://helpdesk-1510b-api.web.app/v1/deliveries',
});

HTTP-функции API работают в europe-central2 (Варшава). Домены Hosting и расположение триггеров Eventarc не определяют регион выполнения функций.

Контракты и примеры

• Входящие сообщения: OpenAPI 3.1
• Исходящие ответы: OpenAPI 3.1
• Коллекция Postman — импортируйте её и задайте ключ интеграции локально

Методы доставки — серверные POST-запросы с JSON до 64 KB и тем же Bearer-ключом. Не вызывайте complete из Postman, если сообщение не было отправлено через провайдера.