API — Общие сведения и архитектура

API сервиса «Ai2n Звонки» позволяет легко связать мобильную телефонию вашей компании с любой внешней информационной системой: CRM (amoCRM, Битрикс24, PlanFix, Мегаплан), учетными программами 1С, Helpdesk-системами, Telegram-ботами или собственными внутренними порталами.

REST API (HTTP Запрос → Ответ)

Используется для активных действий: инициация вызова на телефон менеджера (Click-to-Call), отправка SMS, выгрузка истории звонков за период или управление списком сотрудников.

Webhook API (События в реальном времени)

Сервер Ai2n Звонки моментально отправляет HTTP POST запрос на URL вашей системы при наступлении событий: начало звонка, поднятие трубки, завершение разговора (с передачей ссылки на MP3 запись) или получение/отправка SMS.

2

Авторизация и формат запросов

Все REST запросы осуществляются методом POST с типом содержимого Content-Type: application/json. В теле запроса передается JSON-объект.

Базовый URL точки входа:

https://zvonki.ai2n.dev/api/v1

* Если у вашей компании настроен выделенный поддомен, можно использовать адрес https://[subdomain].zvonki.ai2n.dev/api/v1.

Обязательные поля авторизации в каждом запросе:

Параметр	Тип	Описание
user_name	string	Email (логин) пользователя, от имени которого выполняется запрос.
api_key	string	API-ключ вашей компании (находится в Личном кабинете: «Настройки → Интеграция»).
action	string	Название вызываемого метода API (например, `calls.make_call`).

3

Инициация звонка и отправка SMS

Совершить исходящий звонок: calls.make_call

Команда инициирует автоматический набор номера на смартфоне сотрудника (указанного в user_name). Смартфон менеджера сразу открывает системную звонилку и начинает вызов клиента.

Тело POST-запроса (JSON):

{
  "user_name": "manager@company.kz",
  "api_key": "YOUR_COMPANY_API_KEY_32_CHARS",
  "action": "calls.make_call",
  "to": "+77011234567"
}

Успешный ответ сервера (HTTP 200 OK):

{
  "success": true,
  "message": "Call initiated successfully"
}

Отправить SMS через смартфон: calls.send_sms

Отправляет SMS-сообщение клиенту через SIM-карту смартфона указанного сотрудника по вашему сотовому тарифу.

Тело POST-запроса (JSON):

{
  "user_name": "manager@company.kz",
  "api_key": "YOUR_COMPANY_API_KEY_32_CHARS",
  "action": "calls.send_sms",
  "to": "+77011234567",
  "text": "Здравствуйте! Ваш заказ №4589 собран и готов к выдаче."
}

Совет: В приложении на Android в меню «Настройки → Отправка SMS» можно включить режим «Без подтверждения», чтобы сообщения уходили клиентам моментально и прозрачно для менеджера.

4

Получение журнала звонков: calls.list

Метод позволяет выгрузить список звонков из базы данных с фильтрацией по времени или последовательно по идентификаторам вызовов.

Пример запроса (JSON):

{
  "user_name": "admin@company.kz",
  "api_key": "YOUR_COMPANY_API_KEY_32_CHARS",
  "action": "calls.list",
  "from_id": 1050,
  "max_results": 50,
  "supervised": 0
}

Параметры фильтрации выборки:

from_id — ID звонка, начиная с которого возвращать данные (для инкрементальной синхронизации используйте ID последнего полученного звонка + 1). При значении 0 выгрузка идет с самого начала.
from_date — время в формате UTC Unix Timestamp (в секундах), начиная с которого выбирать звонки.
to_date — время окончания выборки в UTC Unix Timestamp.
max_results — максимальное количество записей в одном ответе (по умолчанию 50, максимум 100).
supervised — если 1, возвращаются только звонки подчиненных пользователей (для роли Руководителя).

Пример структуры ответа (JSON):

{
  "calls": [
    {
      "db_call_id": 1051,
      "date": 1727595000,
      "direction": 1,
      "duration": 142,
      "phone": "+77011234567",
      "user_name": "manager@company.kz",
      "user_display_name": "Азамат Сериков",
      "status": 1,
      "record_url": "https://zvonki.ai2n.dev/records/play/rec_1051.mp3",
      "note": "Договорились о встрече во вторник"
    }
  ],
  "has_more": false
}

* Значения поля direction: 1 — Входящий, 2 — Исходящий. Значения status: 1 — Отвечен, 0 — Пропущен/Не дозвонился.

5

Управление сотрудниками аккаунта

* Данные методы доступны только от лица учетной записи с ролью Администратора.

Добавить сотрудника: company.create_employee

{
  "user_name": "admin@company.kz",
  "api_key": "YOUR_COMPANY_API_KEY_32_CHARS",
  "action": "company.create_employee",
  "employee_user_name": "new_manager@company.kz",
  "employee_password": "SecurePassword123",
  "employee_display_name": "Динара Алиева",
  "employee_role": 4
}

Коды ролей (employee_role): 2 — Руководитель компании, 3 — Руководитель группы, 4 — Менеджер (по умолчанию).

Удалить сотрудника: company.delete_employee

{
  "user_name": "admin@company.kz",
  "api_key": "YOUR_COMPANY_API_KEY_32_CHARS",
  "action": "company.delete_employee",
  "employee_user_name": "old_manager@company.kz"
}

6

Webhook API: События в реальном времени

В личном кабинете в разделе «Настройки → Интеграция» укажите URL вашего веб-сервера (например, https://crm.company.kz/webhooks/calls). Наш сервис будет мгновенно отправлять POST-запросы при каждом телефонном событии.

Событие: call_start (Звонок начат)

Отправляется в момент появления входящего вызова на смартфоне или начала набора номера. Используется для открытия всплывающей карточки клиента в CRM.

{
  "event": "call_start",
  "phone": "+77011234567",
  "direction": 1,
  "user_name": "manager@company.kz",
  "user_display_name": "Азамат Сериков",
  "timestamp": 1727595000
}

Событие: call_answer (Снята трубка)

Отправляется в секунду соединения абонентов. Позволяет фиксировать точное время начала живого диалога.

{
  "event": "call_answer",
  "phone": "+77011234567",
  "user_name": "manager@company.kz",
  "timestamp": 1727595006
}

Событие: call_end (Разговор завершен)

Финальное событие с полными данными о разговоре, длительностью и прямой ссылкой на загрузку/прослушивание MP3 файла аудиозаписи.

{
  "event": "call_end",
  "call_id": 1051,
  "phone": "+77011234567",
  "direction": 1,
  "status": 1,
  "duration": 142,
  "user_name": "manager@company.kz",
  "user_display_name": "Азамат Сериков",
  "timestamp": 1727595148,
  "record_url": "https://zvonki.ai2n.dev/records/play/rec_1051.mp3"
}

7

Примеры кода на cURL, Python, PHP и Node.js

Python (библиотека requests): python3

import requests

url = "https://zvonki.ai2n.dev/api/v1"
payload = {
    "user_name": "manager@company.kz",
    "api_key": "YOUR_COMPANY_API_KEY",
    "action": "calls.make_call",
    "to": "+77011234567"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
print("Статус:", response.status_code)
print("Ответ:", response.json())

PHP (cURL): php

<?php
$data = [
    'user_name' => 'manager@company.kz',
    'api_key'   => 'YOUR_COMPANY_API_KEY',
    'action'    => 'calls.make_call',
    'to'        => '+77011234567'
];

$ch = curl_init('https://zvonki.ai2n.dev/api/v1');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

Node.js / JavaScript (Fetch API): nodejs

const response = await fetch('https://zvonki.ai2n.dev/api/v1', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_name: 'manager@company.kz',
    api_key: 'YOUR_COMPANY_API_KEY',
    action: 'calls.make_call',
    to: '+77011234567'
  })
});
const result = await response.json();
console.log(result);