Методы клиентов (Client API)

API для работы с клиентами: создание, поиск, обновление данных, получение истории сообщений, управление тегами и сегментами.

Базовый URL: https://api.salebot.pro/v1/clients/

Аутентификация: Bearer Token (тот же, что и для Bot API)

Основные методы

GET /clients — Поиск клиентов

Поиск клиентов по различным критериям: email, телефон, теги, дата создания.

curl -X GET "https://api.salebot.pro/v1/clients?email=client@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

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

  • email — поиск по email
  • phone — поиск по телефону
  • tags — фильтр по тегам (через запятую)
  • created_after — клиенты созданные после даты
  • limit — ограничение количества (по умолчанию 50)

POST /clients — Создание клиента

Создаёт нового клиента в системе. Если клиент с таким email/телефоном уже существует, возвращает существующую запись.

curl -X POST https://api.salebot.pro/v1/clients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ivan@example.com",
    "phone": "+79161234567",
    "first_name": "Иван",
    "last_name": "Петров",
    "custom_fields": {
      "city": "Москва",
      "source": "landing_page"
    },
    "tags": ["новый", "интернет-магазин"]
  }'

GET /clients/{id} — Полная информация о клиенте

Возвращает полную информацию о клиенте, включая историю сообщений, заказы, теги.

curl -X GET https://api.salebot.pro/v1/clients/client_456 \
  -H "Authorization: Bearer YOUR_TOKEN"

PUT /clients/{id}/tags — Управление тегами

Добавляет или удаляет теги у клиента.

curl -X PUT https://api.salebot.pro/v1/clients/client_456/tags \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["купил_телефон", "лояльный"],
    "remove": ["новый"]
  }'

GET /clients/{id}/messages — История сообщений

Возвращает историю переписки с клиентом (сообщения от клиента и от бота).

curl -X GET "https://api.salebot.pro/v1/clients/client_456/messages?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"

Практические примеры из опыта

Пример 1: Синхронизация клиентов с CRM

Задача: При регистрации на сайте создавать клиента в Salebot и назначать тег "веб-регистрация".

Решение: На бэкенде сайта после успешной регистрации вызываем POST /clients.

// PHP пример
$clientData = [
    'email' => $user->email,
    'phone' => $user->phone,
    'first_name' => $user->firstName,
    'last_name' => $user->lastName,
    'tags' => ['веб-регистрация', 'новый'],
    'custom_fields' => [
        'user_id' => $user->id,
        'registration_date' => date('Y-m-d')
    ]
];

$ch = curl_init('https://api.salebot.pro/v1/clients');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . SALEBOT_TOKEN,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($clientData));

$response = curl_exec($ch);
// Обработка ответа

Результат: Все зарегистрированные пользователи автоматически появляются в Salebot, можно сразу начинать диалог.

Пример 2: Сегментация для рассылок

Задача: Выбрать всех клиентов из Москвы, которые купили что-то в последние 30 дней, но не получали рассылку о новой коллекции.

Решение: Используем комбинацию API методов: поиск по тегам + фильтр по custom_fields.

# Python скрипт для сегментации
import requests

def get_segment_clients():
    url = "https://api.salebot.pro/v1/clients"
    headers = {"Authorization": f"Bearer {TOKEN}"}
    
    # Ищем клиентов с тегом "купил" и custom_fields.city = "Москва"
    params = {
        "tags": "купил",
        "custom_fields": '{"city": "Москва"}',
        "created_after": "2025-01-01",
        "limit": 1000
    }
    
    response = requests.get(url, headers=headers, params=params)
    clients = response.json().get('data', [])
    
    # Фильтруем тех, у кого нет тега "получил_рассылку_коллекция"
    filtered = [c for c in clients if "получил_рассылку_коллекция" not in c.get('tags', [])]
    
    return filtered

Результат: Точечная рассылка только релевантной аудитории, конверсия в покупки выросла с 3% до 8%.

Кастомные поля (custom_fields)

Позволяют хранить любые дополнительные данные о клиенте, специфичные для вашего бизнеса.

Рекомендуемая структура

{
  "custom_fields": {
    "demographic": {
      "age": 35,
      "gender": "male"
    },
    "business": {
      "company": "ООО Ромашка",
      "position": "директор"
    },
    "purchase_history": {
      "total_orders": 12,
      "total_spent": 45000,
      "last_purchase": "2025-01-20"
    },
    "integration_data": {
      "crm_id": "lead_789",
      "website_session_id": "abc123def"
    }
  }
}

Совет: Используйте вложенную структуру для организации полей. Максимальный размер custom_fields — 16 КБ на клиента.

Ограничения и лучшие практики

  • Лимит запросов: 100 запросов в минуту на токен
  • Пагинация: Все методы поиска поддерживают limit и offset
  • Идемпотентность: POST /clients идемпотентен — повторный вызов с теми же email/телефоном не создаст дубликата
  • Кэширование: Кэшируйте данные клиентов на своей стороне, чтобы уменьшить количество запросов
  • Обработка ошибок: Всегда проверяйте поле success в ответе API

Дальнейшие шаги

← Методы ботов
Вебхуки →