Руководство

Полный путь от пустого API-ключа до отправленного сообщения. Все примеры используют base URL https://send.beebro.com.

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

Каждый запрос требует API-ключ. Передавай его одним из способов:

X-API-Key: bb_abcdef...
# или
Authorization: Bearer bb_abcdef...

Где взять ключ

• Root-ключ — задаётся в .env при развёртывании. Работает всегда, имеет права админа.
• Обычные ключи — создаются в админке или через POST /api-keys (нужны админ-права).

2. Создание аккаунта в мессенджере

Под «аккаунтом» понимается одна сессия в одном мессенджере (один номер телефона).

curl -X POST https://send.beebro.com/accounts \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "label": "main",
    "phone": "+79991234567",
    "proxy_url": "http://user:pass@host:5000"
  }'

Ответ:

{
  "id": 1,
  "platform": "telegram",
  "label": "main",
  "phone": "+79991234567",
  "status": "pending",
  "external_id": null,
  "created_at": "2026-05-16T11:00:00Z"
}

proxy_url — необязательно. Если указан, весь трафик аккаунта пойдёт через прокси (рекомендуется резидентский прокси по гео номера).

3. Логин (Telegram)

После создания аккаунт находится в статусе pending. Чтобы залогиниться:

3.1. Запросить код

curl -X POST https://send.beebro.com/accounts/1/login/start \
  -H "X-API-Key: $KEY"

Telegram пришлёт код внутри приложения Telegram (не SMS) на этот номер. Аккаунт перейдёт в статус needs_code.

3.2. Передать код

curl -X POST https://send.beebro.com/accounts/1/login/code \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "12345"}'

Если на номере включена 2FA — после первой попытки аккаунт перейдёт в needs_2fa. Тогда повтори с паролем:

curl -X POST https://send.beebro.com/accounts/1/login/code \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "12345", "password": "my2fa-password"}'

В случае успеха аккаунт станет active и появится external_id (Telegram user ID).

4. Отправка сообщений

curl -X POST https://send.beebro.com/messages/send \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 1,
    "to": "@username",
    "text": "Привет!"
  }'

Поддерживаемые форматы получателя (TG)

Ответ возвращается сразу со статусом queued — реальная отправка происходит асинхронно. Узнать финальный статус можно через GET /messages/{id}.

5. Получение входящих

Все входящие автоматически сохраняются в БД. Получить можно двумя способами:

Polling — последние сообщения

Real-time — SSE-стрим

Открываешь long-poll SSE, получаешь события вида:

data: {"type":"message.inbound","platform":"telegram","account_id":"1","message_id":"42","from":"123456","text":"Привет"}

Пример клиента на Python

import httpx
import json

with httpx.stream(
    "GET",
    "https://send.beebro.com/events/stream",
    params={"api_key": KEY, "account_id": 1},
    timeout=None,
) as r:
    for line in r.iter_lines():
        if line.startswith("data: "):
            evt = json.loads(line[6:])
            print(evt)

Пример на Node.js

const es = new EventSource(
  `https://send.beebro.com/events/stream?api_key=${KEY}&account_id=1`
);
es.onmessage = (e) => {
  console.log(JSON.parse(e.data));
};

6. Диалоги

Сообщения автоматически группируются в чаты по собеседнику.

Список диалогов аккаунта с превью последнего сообщения.

История переписки с конкретным собеседником.

7. Коды ошибок

8. Безопасность

• API-ключи хранятся в БД в виде sha256-хэша, восстановить нельзя.
• Сессии TG/IG/WA шифруются Fernet (ключ в .env).
• Все внутренние сервисы (PG, Redis, воркеры) изолированы — снаружи только 80/443.
• HTTPS обязательный, TLS-сертификат от Let's Encrypt автоматически.

9. Лимиты и здравый смысл

API не лимитирует, но платформы лимитируют аккаунты. Чтобы аккаунты жили долго:

• Прогревай новые аккаунты 1-2 недели (читать, лайкать, без массовых рассылок)
• ≤ 20-30 новых диалогов в день на свежий TG-аккаунт
• Резидентский прокси по гео аккаунта (поле proxy_url)
• Случайные паузы 2-10 сек между отправками — реализуй на стороне клиента
• Не логинься с одним аккаунтом из разных IP