API для ИИ-агентов

Быстрый старт

1. В кабинете откройте Интеграции → API для агентов и нажмите «Создать ключ». Ключ показывается один раз, сохраните его.
2. На той же странице включите API для нужного агента и скопируйте его ID.
3. Отправьте первое сообщение:

curl -X POST 'https://agent-rails.ru/api/public/v1/agents/AGENT_ID/messages' \
  -H 'Authorization: Bearer ВАШ_API_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"user":{"id":"user_123456","name":"Анна"},"message":"Сколько стоит доставка?"}'

const res = await fetch('https://agent-rails.ru/api/public/v1/agents/AGENT_ID/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.AGENT_RAILS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ user: { id: 'user_123456', name: 'Анна' }, message: 'Сколько стоит доставка?' }),
})
const data = await res.json()
console.log(data.status, data.reply)

import os, requests

resp = requests.post(
    "https://agent-rails.ru/api/public/v1/agents/AGENT_ID/messages",
    headers={"Authorization": f"Bearer {os.environ['AGENT_RAILS_API_KEY']}"},
    json={"user": {"id": "user_123456", "name": "Анна"}, "message": "Сколько стоит доставка?"},
    timeout=60,
)
data = resp.json()
print(data["status"], data["reply"])

Ответ:

{
  "status": "completed",
  "reply": "Здравствуйте, Анна! Доставка по городу стоит 300 ₽, привезём завтра.",
  "reply_id": "f639f508-3c3e-4e71-b9cc-2041a0e877a0",
  "message_id": "850f0ad7-a3d3-4d77-a6e1-05e502b056fd",
  "seq": 1288,
  "conversation_id": "19008257-f70e-42d4-a0ec-7eb9880c600f",
  "reason": ""
}

Аутентификация

Передайте ключ в одном из заголовков, какой удобнее вашей системе:

Authorization: Bearer ar_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# или
X-Api-Key: ar_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ключ принадлежит аккаунту и работает только с агентами этого аккаунта, у которых включён доступ по API. У аккаунта может быть до 10 активных ключей. Отозванный ключ перестаёт работать сразу.

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

Сохраняет сообщение клиента в диалоге и возвращает ответ агента. Диалог определяется парой «агент + user.id», поэтому агент помнит всю переписку с клиентом.

Тело запроса

Ответ

Всегда код 200 и плоский JSON: все поля присутствуют всегда, удобно сохранять их в переменные.

Пример с контекстом

{
  "user": { "id": "user_123456", "name": "Анна" },
  "message": "А можно забрать заказ сегодня?",
  "context": "Выбрала в меню: самовывоз",
  "metadata": { "utm_source": "newsletter", "utm_campaign": "autumn" },
  "timeout_seconds": 25,
  "idempotency_key": "msg-000123"
}

Получить отложенный ответ

Если пришёл pending, запросите ответ через 5–15 секунд по message_id. Формат ответа такой же, как у отправки сообщения. Запрос ничего не генерирует и не списывает сообщения, его можно повторять.

История диалога

{
  "conversation_id": "19008257-f70e-42d4-a0ec-7eb9880c600f",
  "messages": [
    { "seq": 1288, "id": "850f0ad7-…", "role": "user", "text": "Сколько стоит доставка?", "is_manual": false, "created_at": "2026-09-25T09:12:04Z" },
    { "seq": 1289, "id": "f639f508-…", "role": "assistant", "text": "Здравствуйте, Анна! Доставка по городу стоит 300 ₽…", "is_manual": false, "created_at": "2026-09-25T09:12:08Z" }
  ],
  "next_after_seq": 1289
}

Передайте next_after_seq в after_seq, чтобы получать только новые сообщения.

Список агентов

Агенты аккаунта с включённым доступом по API. Удобно для проверки ключа.

{ "agents": [ { "id": "2b34cd48-5898-4308-9890-6e67fd0d01b9", "name": "Консультант" } ] }

Статусы и причины

Поле status

Поле reason

Диалоги и контекст

• Один клиент = один диалог. Все сообщения с одинаковым user.id попадают в один диалог агента, и агент видит историю.
• Имя и контекст передаются агенту только при изменении, поэтому их можно отправлять в каждом запросе.
• Метаданные видит только оператор (например, чтобы понимать источник клиента). Агенту они не передаются.
• Оператор может остановить ИИ в любом диалоге. Пока ИИ остановлен, запросы получают no_reply / paused. Писать клиенту из кабинета в API-диалог нельзя: ответы клиенту доставляет ваша система.
• Буферизация сообщений агента в API не применяется: каждое сообщение обрабатывается сразу.

Повторы запросов

Соединение может оборваться, когда агент уже отвечает. Чтобы повтор не создал второе сообщение и не списал сообщение дважды, передавайте уникальный idempotency_key для каждого сообщения клиента, например его ID в вашей системе.

• Повтор с тем же ключом и тем же телом возвращает результат исходного запроса: дожидается идущего ответа, возвращает готовый или повторяет неотвеченное сообщение.
• Тот же ключ с другим телом вернёт ошибку idempotency_key_reused.
• Ключ действует 24 часа.

Ошибки

Ошибки запроса возвращаются с кодом 4xx/5xx:

{ "error": { "code": "unauthorized", "message": "Неверный или отозванный API-ключ." } }

Лимиты

Подключение конструктора ботов

Сценарий: воронку ведёт конструктор ботов (кнопки, сбор данных), а ИИ-агент отвечает, когда клиент пишет вопрос текстом. Отдельно включать и выключать агента не нужно: он отвечает только на те сообщения, которые передаёт конструктор.

Шаги

1. В кабинете создайте API-ключ и включите API для агента. Загрузите базу знаний. Если заявки в CRM создаёт сам конструктор, отключите у агента функции создания лида.
2. В сценарии конструктора сохраните текст клиента в переменную.
3. Добавьте блок HTTP-запроса: метод POST, адрес https://agent-rails.ru/api/public/v1/agents/AGENT_ID/messages, заголовки Authorization: Bearer ВАШ_API_КЛЮЧ и Content-Type: application/json.
4. В тело подставьте переменные конструктора: ID пользователя в user.id, имя в user.name, текст в message, выбор из меню в context, UTM-метки в metadata.
5. Сохраните ответ в переменную. Если status равен completed, отправьте клиенту значение reply.
6. Если status равен pending, сделайте паузу 10–15 секунд и запросите GET …/messages/{message_id}/reply. При merged и no_reply ничего не отправляйте или передайте клиента менеджеру.

Примеры кода

Отправка с повтором и ожиданием отложенного ответа

const BASE = 'https://agent-rails.ru/api/public/v1'
const headers = { Authorization: 'Bearer ' + process.env.AGENT_RAILS_API_KEY, 'Content-Type': 'application/json' }

async function ask(agentId, userId, text, messageKey) {
  const res = await fetch(`${BASE}/agents/${agentId}/messages`, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': messageKey },
    body: JSON.stringify({ user: { id: userId }, message: text }),
  })
  let data = await res.json()
  for (let i = 0; data.status === 'pending' && i < 6; i++) {
    await new Promise((r) => setTimeout(r, 10000))
    data = await (await fetch(`${BASE}/agents/${agentId}/messages/${data.message_id}/reply`, { headers })).json()
  }
  return data.status === 'completed' ? data.reply : null // null: ничего не отправлять
}

import os, time, requests

BASE = "https://agent-rails.ru/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['AGENT_RAILS_API_KEY']}"}

def ask(agent_id, user_id, text, message_key):
    data = requests.post(
        f"{BASE}/agents/{agent_id}/messages",
        headers={**HEADERS, "Idempotency-Key": message_key},
        json={"user": {"id": user_id}, "message": text},
        timeout=60,
    ).json()
    for _ in range(6):
        if data["status"] != "pending":
            break
        time.sleep(10)
        data = requests.get(f"{BASE}/agents/{agent_id}/messages/{data['message_id']}/reply", headers=HEADERS, timeout=30).json()
    return data["reply"] if data["status"] == "completed" else None  # None: ничего не отправлять

OpenAPI

Машиночитаемое описание API в формате OpenAPI 3.1: openapi.json. Его можно импортировать в Postman, Insomnia или генератор клиентов.

Вопросы по подключению: support@agent-rails.ru.