Создание контактов через API

Эта инструкция поможет настроить приём контактов из внешней системы (сайт, форма, CRM, свой backend) в кампанию Salesbot и при необходимости сразу ставить новые контакты в очередь на звонок.

---

Что умеет интеграция

• Создавать контакты в выбранной кампании по HTTP-запросу (GET или POST).
• Сразу запускать звонок для новых контактов — по настройке интеграции или параметру в теле запроса.
• Обновлять данные при повторной отправке того же номера в кампании (без повторной постановки в очередь).
• Сохранять источник контакта (source) для аналитики и экспорта.
• Принимать один контакт или пачку контактов (массив в POST).

Подходит для сценариев «форма на сайте → контакт в Salesbot → звонок».

---

Подключение: пошаговая настройка

Шаг 1. Открыть раздел интеграций

1. В меню слева откройте «Интеграции».
2. Нажмите «+ Добавить интеграцию».

Шаг 2. Выбрать шаблон

В каталоге выберите карточку «Создание контактов через API» (категория API) и нажмите «Далее».

Шаг 3. Название и инструкция

Укажите название интеграции (произвольное, для удобства). Ниже на экране — краткая инструкция по настройке и способы авторизации.

Шаг 4. Токен API

В поле «Токен API» сгенерируйте или вставьте секретный токен. Его нужно передавать в каждом запросе к API (кнопки справа — скопировать и перегенерировать).

warning

Храните токен в секрете. Не публикуйте его в клиентском JavaScript на открытом сайте без ограничений (прокси на своём backend, IP allowlist и т.п.).

Шаг 5. Автозапуск звонка

В поле «Автоматически начинать звонок» выберите:

• «Да» — новый контакт сразу попадает в очередь на звонок;
• «Нет» — создаётся только контакт (звонок можно включить параметром start_call в POST).

Шаг 6. Источник и дополнительные поля (опционально)

При необходимости укажите в «Поле для источника (source)» имя поля из доп. данных (например utm_source), если источник не передаёте явно параметром source.

Шаг 7. Кампания и сохранение

Выберите кампанию(и) и нажмите «Создать интеграцию».

---

Endpoint

GET|POST https://app.salesbot.tech/api/v1/contact-creation-integration/create-contact

Авторизация (по приоритету)

1. Заголовок Authorization: Bearer <токен> — рекомендуемый способ
2. Параметр token в JSON body (POST)
3. Параметр token в query — для простых форм и быстрой проверки в браузере

---

Параметры запроса

Параметр	Где передать	Обязательный	Описание
token / Bearer	header / body / query	да	Токен интеграции
phone или msisdn	query / body / contact_data	да	Номер телефона
name / fio / FIO / famili	query / body	нет	Имя контакта
campaign_id	query / body	нет	Кампания; если не указана — первая кампания, привязанная к интеграции
source	query / body	нет	Источник контакта (лендинг, форма, CRM). Участвует в аналитике и экспорте
contact_data	query (JSON-строка) / body	нет	Дополнительные поля контакта
start_call	только JSON body (POST)	нет	Переопределяет настройку «Автоматически начинать звонок»

Любые дополнительные поля в JSON body (кроме служебных) также попадут в данные контакта.

---

Когда запускается звонок (start_call)

• Параметр start_call работает только в теле POST (true / false).
• В GET и в query-параметрах start_call игнорируется.
• Если в POST параметр не передан — используется настройка интеграции «Автоматически начинать звонок».
• Звонок ставится в очередь только при создании нового контакта.

---

Повторные контакты

Если контакт с таким же номером уже есть в кампании:

• обновляются дополнительные поля контакта (непустые значения из запроса);
• статус и очередь звонков не меняются;
• в ответе: contact_created: false, call_enqueued: false.

Повторная отправка того же номера не запускает новый звонок автоматически.

---

Источник контакта (source)

Нужен, чтобы сохранить, откуда пришёл контакт. Заполняется так:

1. Явный параметр source в запросе; иначе
2. Значение из поля contact_data, имя которого указано в настройке «Поле для источника (source)»; иначе
3. Пусто.

---

Примеры

GET — быстрый тест в браузере

https://app.salesbot.tech/api/v1/contact-creation-integration/create-contact?token=ВАШ_ТОКЕН&phone=+79991234567&name=Test

Звонок пойдёт только если в интеграции включён автозвонок. Параметр start_call в URL не работает.

POST + Bearer + автозвонок

curl -X POST "https://app.salesbot.tech/api/v1/contact-creation-integration/create-contact" \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+79991234567","name":"Иван","start_call":true,"source":"Landing","utm_campaign":"summer"}'

JavaScript (POST)

async function createContact() {
  const res = await fetch(
    "https://app.salesbot.tech/api/v1/contact-creation-integration/create-contact",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        phone: "+79991234567",
        name: "Иван",
        start_call: true,
        source: "Landing",
      }),
    },
  );
  return res.json();
}

Несколько контактов сразу (POST, JSON-массив)

curl -X POST "https://app.salesbot.tech/api/v1/contact-creation-integration/create-contact" \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '[{"phone":"+79991111111","name":"Алексей"},{"phone":"+79992222222","name":"Мария","start_call":true}]'

---

Ответы

Новый контакт

{
  "success": true,
  "contact_id": 123,
  "campaign_id": 1,
  "phone": "79991234567",
  "contact_created": true,
  "call_enqueued": true,
  "message": "Contact created successfully"
}

Контакт уже был в кампании

{
  "success": true,
  "contact_id": 123,
  "campaign_id": 1,
  "phone": "79991234567",
  "contact_created": false,
  "call_enqueued": false,
  "message": "Contact already exists"
}

Поле	Значение
contact_created	true — контакт создан; false — найден существующий
call_enqueued	true — поставлен в очередь на звонок

---

Проверка подключения

1. Сохраните интеграцию с токеном и привязанной кампанией.
2. Вызовите GET-ссылку из раздела «Примеры» с вашим токеном и тестовым номером.
3. Убедитесь, что контакт появился в кампании.
4. Если нужен автозвонок — проверьте настройку интеграции или отправьте POST с "start_call": true.

---

Что делать, если что-то не работает

Что происходит	Что проверить
401 / «Invalid token»	Токен совпадает с полем «Токен API», интеграция сохранена, в запросе используется правильный способ передачи (Bearer / body / query).
400 / нет телефона	Передан phone или msisdn (отдельно или внутри contact_data).
404 / кампания не найдена	К интеграции привязана кампания, либо в запросе указан корректный campaign_id.
403	campaign_id принадлежит вашему аккаунту.
Контакт создаётся, звонка нет	Для новых контактов: включён автозвонок или в POST передан "start_call": true. В GET параметр start_call не работает.
Повторный запрос не звонит	Так и задумано: для уже существующего номера в кампании звонок повторно не ставится.
Токен «светится» в логах сайта	Не вызывайте API напрямую из браузера посетителя — проксируйте запрос через свой сервер и используйте Authorization: Bearer.

Если проблема не решается — сохраните текст ответа API (код и тело) и обратитесь в поддержку, указав ID интеграции и пример запроса без реального токена.

---

Частые вопросы

Какой URL использовать для создания контакта?

GET|POST https://app.salesbot.tech/api/v1/contact-creation-integration/create-contact

Как передать токен API?

Рекомендуется заголовок Authorization: Bearer <токен>. Также можно передать token в JSON body или в query (legacy, для простых форм).

Работает ли start_call в GET-запросе?

Нет. Параметр start_call учитывается только в JSON body POST. В GET и query он игнорируется.

Что происходит при повторной отправке того же номера?

Контакт в кампании обновляется, звонок повторно в очередь не ставится. В ответе contact_created: false и call_enqueued: false.

Можно ли создать несколько контактов одним запросом?

Да — отправьте POST с JSON-массивом объектов контактов в теле запроса.