API и интеграции
Платформа поддерживает интеграцию с внешними системами: импорт контактов по API, автоматический экспорт лидов в CRM и получение уведомлений через webhook. На этой странице описаны технические детали каждого механизма.
Загрузка контактов по API
Для автоматической загрузки контактов из внешней системы (CRM, формы, таблицы) создайте интеграцию типа «Внешний API» на вкладке «Интеграции» в базе контактов. Платформа сгенерирует уникальный URL — на него нужно отправлять POST-запросы с контактами.
Запрос
Параметр {token} — уникальный ключ доступа, который отображается при создании интеграции. Аутентификация не требуется — токен в URL является единственным идентификатором.
Тело запроса
JSON-массив объектов. Каждый объект — один контакт:
| Поле | Тип | Описание |
|---|---|---|
phone | string | Обязательное. Номер телефона в любом формате — система автоматически нормализует в E.164 (например, +79001234567) |
name | string | Имя контакта. Доступно в роботе через плейсхолдер {name} |
| любое другое | string | Дополнительные параметры (до 128 символов ключ, до 1000 символов значение). Доступны через плейсхолдеры {ключ} |
Ограничения
- Максимум 10 000 контактов за один запрос
- Дубликаты номеров (уже существующих в базе или повторяющихся в запросе) пропускаются
- Невалидные номера пропускаются (система поддерживает российские мобильные номера)
- Нечисловые значения полей конвертируются в строку
Ответ
| Поле | Тип | Описание |
|---|---|---|
totalReceived | int | Всего контактов получено в запросе |
imported | int | Успешно импортировано |
skipped | int | Пропущено (дубликаты, невалидные номера, пустые значения) |
Коды ответов
200 | Запрос обработан, результат в теле ответа |
400 | Ошибка валидации: пустой массив, более 10 000 контактов, некорректный JSON |
404 | Интеграция не найдена, неактивна или удалена |
Пример (cURL)
Пример (Python)
Интеграция с amoCRM
Платформа умеет автоматически создавать сделки и контакты в amoCRM при достижении цели звонка. Для подключения создайте интеграцию типа «amoCRM» на вкладке «Интеграции» в базе контактов.
Настройка
https://mycompany.amocrm.ru, введите mycompany. Импорт контактов из amoCRM
Если включён переключатель «Импорт контактов», платформа предоставит URL для загрузки контактов. Используйте его в Salesbot amoCRM или в webhook-настройках для автоматической передачи контактов. Формат запроса такой же, как у загрузки контактов по API.
Экспорт лидов в amoCRM
Если включён переключатель «Экспорт лидов», при достижении цели звонка платформа автоматически создаст в amoCRM:
- Новую сделку с названием, включающим имя или номер контакта
- Новый контакт с телефонным номером
Экспорт работает через очередь с автоматическими повторными попытками (до 5 раз с увеличивающимся интервалом). Статус последней отправки и ошибки отображаются в настройках интеграции.
Webhook-уведомления
Webhook — это один из каналов уведомлений. При каждом подходящем звонке платформа отправляет HTTP POST-запрос на указанный URL с полными данными о звонке в формате JSON.
HTTP-запрос
| Заголовок | Описание |
|---|---|
X-Webhook-Event | Тип события: lead.goal_achieved (цель достигнута), call.completed (звонок завершён) или test (тестовый запрос) |
X-Webhook-Id | Уникальный идентификатор отправки (UUID) — используйте для идемпотентности |
X-Webhook-Signature | HMAC-SHA256 подпись тела запроса (если настроен секретный ключ). Формат: sha256=<hex> |
JSON-тело запроса
| Поле | Тип | Описание |
|---|---|---|
callId | string (UUID) | Идентификатор звонка |
organizationName | string | Название организации |
callListId | string (UUID) | Идентификатор базы контактов |
callListName | string | null | Название базы контактов |
callListItemId | string (UUID) | Идентификатор контакта в базе |
phoneE164 | string | Номер телефона в формате E.164, например +79001234567 |
contactName | string | null | Имя контакта (если задано) |
status | string | Статус звонка (см. таблицу ниже) |
isGoalAchieved | boolean | true — цель достигнута |
goalSummary | string | null | Краткий результат (заполняется при достижении цели) |
goalConversationResume | string | null | Развёрнутое резюме разговора, автоматически сформированное системой |
durationSeconds | int | Длительность звонка в секундах |
recordingUrl | string | null | Ссылка на запись разговора (если доступна) |
calledAtUtc | string (ISO 8601) | Время звонка в UTC |
Статусы звонка
GoalAchieved | Цель достигнута |
CallLater | Перезвонить позже |
NotInterested | Не интересно |
HungUp | Сбросил |
Negative | Негатив |
Проверка подписи (HMAC-SHA256)
Если при создании webhook-уведомления указан секретный ключ, каждый запрос подписывается алгоритмом HMAC-SHA256. Подпись передаётся в заголовке X-Webhook-Signature в формате sha256=<hex>.
Алгоритм проверки:
- Возьмите тело запроса как строку (raw body)
- Вычислите
HMAC-SHA256(body, secret)— результат в lowercase hex - Сравните с подписью из заголовка (без префикса
sha256=)
Пример проверки (Node.js)
Пример проверки (Python)
Таймаут и повторные попытки
Платформа ожидает ответ от вашего сервера не более 10 секунд. При получении HTTP-ответа с кодом 2xx запрос считается доставленным. При любой другой ошибке (код 4xx/5xx, таймаут, ошибка подключения) система выполнит повторную попытку.