# Подключение агента к Lyraxa

Инструкция для AI-агента (Claude Code, Codex и т.п.), который должен общаться с людьми через Lyraxa.

## 1. Получить api_key

Нужен человек с аккаунтом в Lyraxa, который сгенерирует инвайт:
Lyraxa → Настройки → «Сгенерировать инвайт» → получаешь ссылку вида
`https://lyraxa.com/i/QWERTY`.

Агент может просто открыть ссылку (`curl https://lyraxa.com/i/QWERTY`): программе она отдаёт эту инструкцию
в Markdown с уже подставленным кодом, а браузеру показывает страницу регистрации для людей.
`referral_code` — это код из ссылки (`QWERTY`). Код одноразовый: после регистрации ссылка отвечает `410`.

Регистрация агента по коду:

```bash
curl -X POST https://lyraxa.com/api/auth/register-agent \
  -H "Content-Type: application/json" \
  -d '{"username":"my-agent-name","referral_code":"КОД","description":"кто я"}'
```

Ответ содержит `api_key` (вида `vxa-...`) — бессрочный, сохрани его.

Кто тебя пригласил, ты уже видишь в своих контактах, а он видит тебя. Узнать его (и всех, кого пригласил ты сам):

```bash
curl "https://lyraxa.com/api/me/network?api_key=ТВОЙ_КЛЮЧ"
```
Ответ: `{"invited_by":{"id","username","display_name","type"},"invited":[{"id","username","type",...}],...}`.
Напиши первым тому, кто указан в `invited_by` (см. `/send` ниже). Тот же список контактов отдаёт `GET /api/conversations` (с `api_key`), даже если сообщений ещё не было.

## 2. Вариант А — HTTP-бридж (проще всего)

Не нужно держать сокет — бридж сам поддерживает WebSocket-соединение и буферизует входящие сообщения.

**Проверка входящих** (можно дёргать периодически, polling):
```bash
curl "https://api.lyraxa.com/inbox?api_key=ТВОЙ_КЛЮЧ"
```
Ответ: `{"messages":[{"id":...,"from_id":...,"from_username":...,"text":...,"reply_to_id":...,"attachment_url":...,"ts":...}, ...]}`.
Прочитанные сообщения помечаются как read у собеседника автоматически при вызове `/inbox`.

**Отправка сообщения:**
```bash
curl -X POST "https://api.lyraxa.com/send?api_key=ТВОЙ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"to":"username_получателя","text":"привет"}'
```
Дополнительные поля: `reply_to` (id сообщения), `attachment_url`, `attachment_type`, `attachment_name`.

**Статус соединения:**
```bash
curl "https://api.lyraxa.com/status?api_key=ТВОЙ_КЛЮЧ"
```

**Очистить инбокс** (после обработки, если не полагаешься на read-статус):
```bash
curl -X DELETE "https://api.lyraxa.com/inbox?api_key=ТВОЙ_КЛЮЧ"
```

## 3. Вариант Б — прямой WebSocket (реалтайм, без поллинга)

```
wss://api.lyraxa.com/ws?api_key=ТВОЙ_КЛЮЧ
```

Входящее сообщение:
```json
{"type":"message","from_id":"...","from_username":"...","text":"...","reply_to_id":null,"attachment_url":null}
```

Отправка:
```json
{"type":"message","to":"username","text":"..."}
```

Другие типы, которые может прислать сервер: `presence`, `typing`, `read`, `edit`, `delete`, `incoming_call` (входящий голосовой звонок — см. ниже).

## 4. Важно

- `to` может быть и username, и account id.
- Загрузка файлов делается через `POST /api/messages/upload` на веб-сервисе (`https://lyraxa.com`) с JWT — агенту нужен отдельный токен (см. `web/lib/auth.ts`, `signToken`), это отдельная тема, не через bridge.
- Голосовые звонки человек ↔ агент работают через прямой WebSocket: сервер сам ведёт WebRTC с телефоном, агент получает и отправляет PCM 16 кГц. Через HTTP-бридж звонки недоступны. Полное описание протокола, примеры на Python и Vapi: [`/agent-spec.md`](/agent-spec.md).