BOTIX SDK для PHP

Официальная клиентская библиотека для публичного API BOTIX — платформы визуального конструктора чат-ботов и AI-ассистентов.

Что это

SDK даёт удобный PHP-клиент над REST API https://api.botix.pro/public/v1/*: контакты, сообщения, чаты, сценарии, каналы и webhooks. Авторизация — Bearer-токеном, привязанным к проекту в BOTIX.

Получить ключ: войти в кабинет app.botix.pro, открыть Настройки → API-ключи, нажать «Создать ключ». Полный ключ (btx_live_…) показывается один раз — сохраните.

Установка

composer require botix-pro/sdk

Требования: PHP 8.0+, расширения curl, json, mbstring.

Первый запрос

Проверка ключа — endpoint GET /me возвращает контекст: project_id, scopes тариф, остаток rate-limit.

<?php
require __DIR__ . '/vendor/autoload.php';

$client = new \BotixPro\Sdk\Client('btx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');

$me = $client->system()->meGet();
echo "project_id = {$me->getData()->getProjectId()}\n";
echo "plan = {$me->getData()->getPlanKey()}\n";

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

POST /messages — реально шлёт текст в канал (Telegram / виджет / VK). Канал берётся из payload или last_channel контакта.

<?php
$body = new \BotixPro\Sdk\Model\MessagesSendRequest([
    'contact_id' => 12345,
    'content'    => 'Привет от BOTIX SDK',
    'channel'    => 'telegram', // опционально
]);

$response = $client->messages()->messagesSend($body);
echo "message_id = {$response->getData()->getMessageId()}\n";

Заголовок Idempotency-Key (UUID v4) добавляется автоматически — повтор запроса с тем же ключом в течение 24 часов вернёт сохранённый ответ без новой отправки. Отключить: new Client($key, ['auto_idempotency_key' => false]).

Webhooks: проверка подписи

BOTIX подписывает каждую доставку HMAC-SHA256 от raw body и кладёт результат в заголовок X-Botix-Signature. Секрет подписки выдаётся один раз при POST /webhooks.

<?php
require __DIR__ . '/vendor/autoload.php';

$rawPayload = file_get_contents('php://input');
$signature  = $_SERVER['HTTP_X_BOTIX_SIGNATURE'] ?? '';
$secret     = getenv('BOTIX_WEBHOOK_SECRET');

if (!\BotixPro\Sdk\Client::verifyWebhook($rawPayload, $signature, $secret)) {
    http_response_code(401);
    exit('invalid signature');
}

$event = json_decode($rawPayload, true);
// обрабатываем $event['event'], $event['data']
http_response_code(200);

Сравнение через hash_equals — защита от timing-атак.

Работа с ошибками

API возвращает {success: false, error: {code, message, details}}. SDK кидает \BotixPro\Sdk\ApiException на не-2xx; код ошибки — внутри тела.

HTTP	code	Когда
401	MISSING_API_KEY / INVALID_API_KEY / KEY_REVOKED	Ключ отсутствует, поддельный или отозван
403	INSUFFICIENT_SCOPE	У ключа нет нужного scope
403	API_NOT_AVAILABLE_ON_PLAN	Тариф клиента не включает API
403	TRIAL_READ_ONLY	Триал — мутирующие методы запрещены
422	NO_CHANNEL_AVAILABLE / CHANNEL_NOT_CONNECTED / CONTACT_NOT_REACHABLE	Не удалось определить или достучаться до канала
422	CHANNEL_NOT_SUPPORTED_YET	Канал есть в системе, но интеграция в API ещё не подключена (WhatsApp)
422	CONTACT_BUSY	Контакт в активном сценарии — передайте force=true
429	RATE_LIMIT_EXCEEDED	Превышен минутный или суточный лимит
502	DELIVERY_FAILED	Канал отверг отправку

try {
    $client->messages()->messagesSend($body);
} catch (\BotixPro\Sdk\ApiException $e) {
    $payload = json_decode($e->getResponseBody(), true);
    error_log("BOTIX error {$payload['error']['code']}: {$payload['error']['message']}");
}

Ссылки

• Документация API: https://developers.botix.pro/
• Маркетинговая страница: https://botix.pro/developers
• Этот репозиторий: https://github.com/BOTIX-pro/sdk-php
• Issues / поддержка: https://github.com/BOTIX-pro/sdk-php/issues
• Email: hello@botix.pro

Лицензия

MIT