Foresko Support API

API для встроенного чата поддержки в мобильных и веб-приложениях. Пользователь пишет сообщение, сервис создает или переоткрывает тикет, подтягивает профиль приложения, базу знаний и похожие закрытые тикеты, затем возвращает ответ ИИ.

Base URL

https://support.foresko.com

Auth

Все endpoints под /v1, кроме /v1/health, требуют bearer token. Есть два типа токенов:

Admin token: серверный секрет для управления приложениями, знаниями и тикетами.
Chat token: короткоживущий токен только для POST /v1/messages, привязан к конкретным app_id и user_id.

Authorization: Bearer <SUPPORT_API_TOKEN>

Не вшивайте главный admin token в публичное приложение. Production flow: ваш backend проверяет пользователя и выдает chat token.

Выдать chat token

POST /v1/chat-tokens

Этот endpoint вызывается только вашим backend с admin token.

{
  "app_id": "ios.payments",
  "user_id": "user_123",
  "expires_in_seconds": 600
}

Ответ содержит token, который frontend чата использует в POST /v1/messages.

Основной сценарий чата

POST /v1/messages

{
  "app_id": "ios.payments",
  "user_id": "user_123",
  "external_id": "ios-message-0001",
  "platform": "iOS",
  "subject": "Payment does not work",
  "text": "Face ID opens but Apple Pay fails after confirmation.",
  "device": {
    "platform": "iOS",
    "model": "iPhone 15 Pro",
    "os_version": "18.5",
    "locale": "en_US"
  },
  "app": {
    "version": "2.4.1",
    "build": "241"
  },
  "metadata": {
    "screen": "checkout",
    "payment_provider": "apple_pay"
  }
}

external_id нужен для идемпотентности: если приложение повторит отправку из-за плохой сети, второй AI-ответ не создастся.

Ответ на сообщение создается асинхронно. API быстро вернет 202 Accepted, job.id и reply_status=pending. Фронт должен poll-ить job или тикет.

{
  "ticket": { "id": "ticket_..." },
  "message": { "id": "msg_...", "role": "user" },
  "job": { "id": "job_...", "status": "pending" },
  "reply_status": "pending"
}

Polling ответа

GET /v1/jobs/{job_id}

Возвращает статус pending, running, done или failed. Chat token может читать только свои jobs.

GET /v1/tickets/{ticket_id}

Когда worker завершит job, в messages появится сообщение с role=assistant.

Профиль приложения

PUT /v1/apps/{app_id}

{
  "name": "Payments App",
  "platform": "iOS",
  "description": "Checkout and Apple Pay flow for the consumer app.",
  "support_prompt": "For Apple Pay issues, ask for region, payment method, transaction id, error text, and whether Face ID completed.",
  "metadata": {
    "bundle_id": "com.example.payments"
  }
}

GET /v1/apps/{app_id}

База знаний

POST /v1/apps/{app_id}/knowledge

{
  "title": "Apple Pay troubleshooting",
  "content": "If Face ID completes and payment fails, ask for the Apple Pay error text, device region, app version, order id, and attempt time.",
  "source_url": "internal://runbook/apple-pay"
}

GET /v1/apps/{app_id}/knowledge?q=Face%20ID%20payment

Тикеты

GET /v1/tickets?app_id=ios.payments&status=open

GET /v1/tickets/{ticket_id}

POST /v1/tickets/{ticket_id}/close

{ "summary": "User was asked for Apple Pay error text and order id." }

Поиск

GET /v1/search?app_id=ios.payments&q=Face%20ID

OpenAPI

Машиночитаемая схема доступна тут: /openapi.json