# HTTP API для интеграций

> Как подключить Eggent к своему сайту, CRM, боту или автоматизации — получить токен, отправить сообщение, передать файл, получать ответ потоком и сохранять разговор между запросами.

Source: https://eggent.ai/r/docs/external-api/

**Внешний API** — способ дать задачу агенту из другой программы: бэкенда сайта, CRM, n8n или Make, своего бота, фоновой задачи. Ты отправляешь сообщение, Eggent выполняет его как обычный чат и возвращает ответ.

## Адрес {#base-url}

| Где Eggent | Базовый адрес |
| --- | --- |
| Облако | `https://имя.cloud.eggent.ai` |
| Свой сервер | адрес, по которому открывается Eggent, например `https://eggent.example.com` |

## Получить токен {#token}

1. Открой **Настройки → API**.
2. Сгенерируй токен внешнего API.
3. Сохрани его в своей системе как секрет.

Токен передаётся в заголовке `Authorization: Bearer <токен>`. Не вставляй его в код, который выполняется в браузере: с ним можно давать агенту любые задачи. На своём сервере вместо генерации можно задать переменную `EXTERNAL_API_TOKEN`; токен из настроек главнее.

## Отправить сообщение {#message}

```http
POST /api/external/message
Authorization: Bearer <токен>
Content-Type: application/json
```

```bash
curl -X POST https://имя.cloud.eggent.ai/api/external/message \
  -H "Authorization: Bearer $EGGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "crm:client-42",
    "projectName": "Продажи",
    "message": "Напиши короткое письмо клиенту по последним заметкам"
  }'
```

### Поля запроса {#request}

| Поле | Обязательно | Что это |
| --- | --- | --- |
| `sessionId` | да | Постоянный ключ разговора. Один на пользователя, тред, клиента или задачу |
| `message` | да | Текст задачи, непустой |
| `projectId` | нет | id проекта (или точное имя, если оно одно) |
| `projectName` | нет | Точное имя проекта |
| `chatId` | нет | Существующий чат. Обычно не нужен |
| `currentPath` | нет | Подсказка рабочей папки для задач с файлами |

Без проекта сообщение уходит оркестратору.

### Ответ {#response}

```json
{
  "success": true,
  "sessionId": "crm:client-42",
  "reply": "Здравствуйте, Анна! …",
  "context": {
    "activeProjectId": "sales",
    "activeProjectName": "Продажи",
    "activeChatId": "0a2f…",
    "activeChatTitle": "Звонок с Анной",
    "currentPath": ""
  },
  "chatChanged": false,
  "switchedProject": null,
  "createdProject": null
}
```

Если агент во время работы переключил или создал проект, это видно в `switchedProject` и `createdProject`. `chatChanged` равно `true`, когда разговор теперь в другом чате, чем до этого сообщения — агент его перевёл, — а `activeChatTitle` называет этот чат.

## Как работает sessionId {#session}

Eggent помнит для каждого `sessionId` текущий проект, текущий чат и рабочую папку. Повторяй тот же `sessionId` — и агент продолжит тот же разговор, с историей. Новый `sessionId` — новый разговор.

Хорошие ключи: `telegram:<user-id>`, `crm:<client-id>`, `slack:<channel>:<thread>`, `job:daily-report`.

## Ответ потоком {#streaming}

Если добавить заголовок `Accept: text/event-stream`, ответ придёт потоком событий (SSE) — удобно, чтобы показывать текст по мере написания. Каждое событие — JSON в строке `data:`:

| Событие | Что значит |
| --- | --- |
| `{"type":"text","delta":"…"}` | Очередной кусок ответа |
| `{"type":"tool","name":"…","phase":"start"}` | Агент начал или закончил (`"end"`) использовать инструмент |
| `{"type":"done","result":{…}}` | Готово; `result` — тот же JSON, что и без потока |
| `{"type":"error","status":500,"payload":{…}}` | Ошибка с тем кодом, который вернулся бы без потока |

Если клиент отключился посреди ответа, работа не прерывается: агент доделает её, и результат сохранится в чате.

## Отправить файл {#files}

```http
POST /api/external/media-message
Authorization: Bearer <токен>
Content-Type: multipart/form-data
```

Поля те же, что у `/message`, плюс `file` и `kind` (`document`, `photo`, `audio`, `video`, `voice`, `file`). Файл сохраняется во вложения чата, агент его видит. Голосовое (`kind=voice`) сначала расшифровывается в текст.

```bash
curl -X POST https://имя.cloud.eggent.ai/api/external/media-message \
  -H "Authorization: Bearer $EGGENT_API_TOKEN" \
  -F "sessionId=crm:client-42" \
  -F "message=Выпиши из договора все сроки" \
  -F "kind=document" \
  -F "file=@./contract.pdf"
```

## Ошибки {#errors}

| Код | Причина | Что сделать |
| --- | --- | --- |
| `400` | Нет `sessionId` или `message` | Передай оба непустыми строками |
| `401` | Нет токена или он неверный | Проверь заголовок `Authorization: Bearer …` |
| `404` | Проект или чат не найден | Проверь id и имена проектов |
| `409` | Имя проекта неоднозначно или чат из другого проекта | Используй `projectId` или убери `chatId` |
| `503` | Токен не настроен | Сгенерируй его в **Настройки → API** |

## Советы {#tips}

- Вызывай API только с сервера и только по HTTPS.
- Ставь большой таймаут: сложная задача может выполняться несколько минут. Или используй поток.
- Один реальный разговор — один `sessionId`.
- Сообщение, которое начинается с `@` и названия проекта, поручает задачу этому проекту, как в приложении: проект работает в своём чате, а его ответ входит в ответ API. См. [Проекты](https://eggent.ai/r/docs/projects.md#ask).
- Ответы через API тратят баланс так же, как чат, и всегда работают в полном режиме.