Создайте форму в боте
В MAX отправьте команду /form Название формы. Бот вернёт уникальный form_key и ссылку Webhook.
Готовая схема интеграции для HTML-форм, JavaScript, CMS и CRM. Создайте форму в боте, получите ключ и отправляйте обращения единым POST-запросом.
{
"form_key": "YOUR_FORM_KEY",
"comment": "Хочу консультацию"
}
В MAX отправьте команду /form Название формы. Бот вернёт уникальный form_key и ссылку Webhook.
Передайте данные формы на endpoint ниже. Обязательное поле только одно: form_key. Имя, телефон и email можно не указывать.
При активной оплаченной подписке команда получит заявку в MAX и по email. Ответ success: true подтверждает сохранение заявки.
POST /api/send.php принимает JSON, application/x-www-form-urlencoded и multipart/form-data.
https://n.vlkstudio.ru/api/send.php
<form action="https://n.vlkstudio.ru/api/send.php" method="post">
<input type="hidden" name="form_key" value="YOUR_FORM_KEY">
<input name="name" placeholder="Имя">
<input name="phone" placeholder="Телефон">
<textarea name="comment" placeholder="Текст заявки"></textarea>
<button type="submit">Отправить</button>
</form>
Форма откроет JSON-ответ. Для отправки без перехода используйте fetch или обработчик на своём сервере.
Для другого домена сначала настройте разрешённый origin — подробности ниже.
const payload = {
form_key: 'YOUR_FORM_KEY',
comment: 'Хочу консультацию',
idempotency_key: crypto.randomUUID()
}; // При повторе отправьте этот же payload и ключ.
async function sendLead(payload) {
const response = await fetch('https://n.vlkstudio.ru/api/send.php', {
method: 'POST',
credentials: 'omit',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload)
});
const result = await response.json();
if (!response.ok || !result.success) {
throw new Error(result.message || 'Не удалось сохранить заявку');
}
return result;
}
sendLead(payload).then(console.log).catch(console.error);
form_keyОбязательный ключ формы из команды /form.nameИмя клиента. Все контактные поля необязательны.phoneТелефон для связи.emailEmail клиента; не используется как адрес доставки уведомлений.messagecommentcommentsquestiontextсообщениекомментарийСвободный текст заявки. Можно отправить без name, phone и email; он попадёт в MAX и письмо дословно. Выбирается первое непустое поле в указанном порядке.titleformНазвание заявки: приоритет у title, затем form; по умолчанию «Новая заявка».sourceutm_sourceИсточник: приоритет у source, затем utm_source; по умолчанию site.idempotency_keyexternal_idУникальный ID заявки для защиты от дублей; приоритет у idempotency_key. При повторе отправляйте тот же ID.keycompany_idСохранены для совместимости. Для новой интеграции используйте form_key: компания, сайт и форма определятся по ключу.{
"success": true,
"duplicate": false,
"lead": {
"id": "L-000001"
}
}
Сокращённый пример. Полный ответ также содержит данные заявки, company и recipients. Получение success: true означает сохранение, а не гарантию доставки уведомлений.
Дубль: HTTP 200, duplicate: true и прежний lead. Повторной доставки нет. Без ID используется SHA-1 исходного payload — сохраняйте значения и порядок полей при повторе.
{"success": false,
"message": "Empty lead payload"}
{"success": false,
"message": "Company or form key not found"}
HTTP 400: пустой payload/неразобранный JSON без других параметров либо неизвестная форма/компания. Ошибки MAX и SMTP записываются отдельно и не меняют успешный ответ сохранённой заявки.
form_key скопирован полностью.POST.Content-Type: application/json./forms и убедитесь, что форма существует.Отправьте заявку с сервера своего сайта. CORS не требуется. Сохраните external_id при повторе запроса и обрабатывайте ошибки на своём сервере.
<?php
$payload = [
'form_key' => 'YOUR_FORM_KEY',
'comment' => 'Хочу консультацию',
'external_id' => 'order-123', // ID вашей заявки, сохраняется при повторе.
];
$ch = curl_init('https://n.vlkstudio.ru/api/send.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
if ($body === false) {
throw new RuntimeException('Ошибка соединения: ' . $error);
}
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 200 || empty($result['success'])) {
throw new RuntimeException((string) ($result['message'] ?? 'Ошибка API'));
}
$leadId = $result['lead']['id'];
Для браузерного fetch администратор добавляет точный origin стороннего сайта в integration_allowed_origins файла data/settings.json:
{
"integration_allowed_origins": [
"https://example.ru"
]
}
Укажите схему, домен и порт, без пути и завершающего слеша. По умолчанию список пуст. Запрос OPTIONS возвращает HTTP 204; CORS-заголовки выдаются только разрешённым доменам. Cookies не нужны.
Обычная HTML-форма и серверный cURL работают без CORS. Используйте действительный form_key во всех вариантах. CORS управляет чтением ответа браузером и не заменяет ключ формы.
Получатели совпадают с MAX: активный владелец и сотрудники, с учётом доступа к сайту и форме. Нужна действующая оплаченная подписка. После оплаты отложенные заявки доставляет штатный механизм повторов.
Письмо отправляется на email связанного личного кабинета: cabinet_accounts.email по max_user_id. Если сотрудник ещё не создал кабинет, используется резервный адрес его компании.
Администратор задаёт резервные адреса по ID компании в data/settings.json:
{
"company_notification_emails": {
"1": "team@example.ru",
"2": "sales@example.org"
}
}
На общий адрес приходит одна копия заявки. Email клиента из формы не влияет на выбор получателей. Письмо в UTF-8 содержит тот же текст, что MAX: ID, компанию, источник, название формы, поля и блок «Сообщение».
Если адреса нет, в журнале будет skipped / email_missing; без SMTP — skipped / smtp_not_configured. После настройки недоставленные письма доступны для повторной доставки.
Настройки задаёт администратор в data/settings.json. Они относятся к отправителю сервиса и не передаются сторонним сайтом в заявку.
smtp_host — SMTP-сервер; пустой адрес отключает отправку.smtp_port — 587 по умолчанию; для SSL обычно 465.smtp_username и smtp_password — учётные данные. Пустой username отключает авторизацию SMTP.smtp_encryption — tls (STARTTLS), ssl (SMTPS) или пустая строка для сервера без обязательного шифрования; доступный STARTTLS используется автоматически.smtp_from_email — корректный адрес отправителя; smtp_from_name — его имя, по умолчанию VLK FormBot.smtp_timeout — таймаут операций SMTP, по умолчанию 10 секунд.Ошибка email не мешает MAX и наоборот. Журнал хранит отдельные статусы каналов; повторяется только неудавшийся канал. Повторный POST с тем же ID не запускает повтор уведомлений.