Операции Mindbox

Раздел описывает операции интеграции Mindbox в платформе Fasttrack: какие операции доступны, в какой момент они вызываются, какие параметры принимают и как обрабатывать результат в конструкторе.

В описании параметров символом * обозначены обязательные поля. Остальные поля передаются по необходимости — в зависимости от настроек проекта и сценария бота.

Как вызвать операцию

Любая операция Mindbox вызывается в конструкторе тегом {% mindbox.operation %}. Тело запроса формируется заранее объектом через {% createobj %} … {% endcreateobj %}, а результат выполнения сохраняется в переменную для дальнейшего использования.

Общая схема состоит из трёх шагов:

1

Сформировать тело запроса

Объект с параметрами операции через {% createobj %}.

2

Вызвать операцию

Тег {% mindbox.operation %} с именем операции и телом запроса.

3

Сохранить результат

Тег {% save_variable %}, чтобы обратиться к ответу дальше по сценарию.

Аргументы тега {% mindbox.operation %}:

Аргумент	Описание
name	Имя операции в Mindbox (например, ft.GetCustomer). Должно совпадать с именем, заведённым в админке Mindbox.
custom_fields	Объект с телом запроса, созданный через {% createobj %}.
as <переменная>	Имя переменной, в которую помещается результат выполнения операции.

Пример полного вызова — проверка наличия контакта в Mindbox по номеру телефона:

{# вызываем операцию ft.GetCustomer для проверки наличия контакта в MindBox #}
{% createobj get_contact %}
{
    "page": {
        "pageNumber": "1",
        "itemsPerPage": "10"
    },
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetCustomer" custom_fields=get_contact as operation_ft_GetCustomer %}
{# сохраним результат выполнения операции в переменнную operation_ft_GetCustomer #}
{% save_variable "operation_ft_GetCustomer" operation_ft_GetCustomer %}

Каждая операция (name) должна быть предварительно заведена в админке Mindbox. Если операция не настроена на стороне Mindbox, вызов вернёт ошибку.

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

ft.BotStart — Старт бота

Вызывается в момент первого запуска бота пользователем. Передаёт в Mindbox факт входа в бота, идентификатор пользователя в боте и, при наличии, данные из диплинка (магазин, акция, платформа).

Параметры

Параметр	Тип	Описание
pointOfContact	string	Идентификатор магазина (если передан в диплинке).
customer.ids.tGID *	string	Идентификатор пользователя в боте.
customer.customFields.inbotTG	string	Признак присутствия клиента в боте (True).
customerAction.customFields.advertID	string	Идентификатор акции (если передан в диплинке).
customerAction.customFields.botPlatform	string	Платформа бота: tg / vk / max / wa.

Пример вызова:

{# фиксируем старт бота в Mindbox #}
{% createobj bot_start %}
{
    "pointOfContact": "{{shop_id}}",
    "customer": {
        "customFields": {
            "inbotTG": "True"
        },
        "ids": {
            "tGID": "{{bot_user_id}}"
        }
    },
    "customerAction": {
        "customFields": {
            "advertID": "{{advert_id}}",
            "botPlatform": "tg"
        }
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.BotStart" custom_fields=bot_start as operation_ft_BotStart %}
{% save_variable "operation_ft_BotStart" operation_ft_BotStart %}

Структура ответа (схематично):

{
    "status": "Success",
    "customer": {
        "ids": { "mindboxId": "..." }
    }
}

ft.CreateCustomer — Создание клиента

Создаёт клиента в Mindbox. Вызывается, когда пользователь оставил номер телефона и его нужно завести как контакт. Здесь же фиксируется согласие на рассылки.

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента.
customer.ids.tGID	string	Идентификатор пользователя в боте.
customer.customFields.subTG	string	Признак согласия на рассылки в боте (True).
customer.subscriptions[].brand	string	Передаётся, если согласие на рассылки в боте должно распространяться на все рассылки бренда. В этом случае передаётся весь блок subscriptions.

Пример вызова:

{# создаём клиента в Mindbox #}
{% createobj create_customer %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}",
        "ids": {
            "tGID": "{{bot_user_id}}"
        },
        "customFields": {
            "subTG": "True"
        },
        "subscriptions": [
            {
                "brand": "{{brand}}"
            }
        ]
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.CreateCustomer" custom_fields=create_customer as operation_ft_CreateCustomer %}
{% save_variable "operation_ft_CreateCustomer" operation_ft_CreateCustomer %}

Структура ответа (схематично):

{
    "status": "Success",
    "customer": {
        "ids": { "mindboxId": "..." }
    }
}

ft.FillUpCustomer — Дополнить клиента

Дозаполняет профиль уже существующего клиента: ФИО, дата рождения, пол, контакты, часовой пояс. Вызывается, когда пользователь постепенно сообщает дополнительные данные о себе.

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента (идентификация).
customer.firstName	string	Имя.
customer.lastName	string	Фамилия.
customer.middleName	string	Отчество.
customer.fullName	string	ФИО одной строкой.
customer.birthDate	string	Дата рождения.
customer.sex	string	Пол.
customer.email	string	Email.
customer.timeZone	string	Часовой пояс.

Пример вызова:

{# дополняем профиль клиента #}
{% createobj fill_up_customer %}
{
    "customer": {
        "birthDate": "{{birth_date}}",
        "sex": "{{sex}}",
        "timeZone": "{{time_zone}}",
        "lastName": "{{last_name}}",
        "firstName": "{{first_name}}",
        "middleName": "{{middle_name}}",
        "fullName": "{{full_name}}",
        "email": "{{email}}",
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.FillUpCustomer" custom_fields=fill_up_customer as operation_ft_FillUpCustomer %}
{% save_variable "operation_ft_FillUpCustomer" operation_ft_FillUpCustomer %}

Структура ответа (схематично):

{
    "status": "Success"
}

ft.GetCustomer — Получить информацию о клиенте

Возвращает данные клиента из Mindbox по номеру телефона. Используется для проверки наличия контакта и получения его профиля.

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента для поиска.
page.pageNumber	string	Номер страницы выборки.
page.itemsPerPage	string	Количество записей на странице.

Пример вызова:

{# вызываем операцию ft.GetCustomer для проверки наличия контакта в MindBox #}
{% createobj get_contact %}
{
    "page": {
        "pageNumber": "1",
        "itemsPerPage": "10"
    },
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetCustomer" custom_fields=get_contact as operation_ft_GetCustomer %}
{# сохраним результат выполнения операции в переменнную operation_ft_GetCustomer #}
{% save_variable "operation_ft_GetCustomer" operation_ft_GetCustomer %}

Структура ответа (схематично):

{
    "status": "Success",
    "customer": {
        "ids": { "mindboxId": "..." },
        "firstName": "...",
        "lastName": "...",
        "mobilePhone": "...",
        "email": "..."
    }
}

Бот лояльности

ft.ConfirmPhone — Подтвердить телефон

Подтверждает номер телефона клиента. Используется, если на проекте предусмотрено подтверждение номера (например, через код из SMS).

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента.
customer.ids.mindboxId *	string	Идентификатор клиента в Mindbox.

Пример вызова:

{# подтверждаем номер телефона клиента #}
{% createobj confirm_phone %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}",
        "ids": {
            "mindboxId": "{{mindbox_id}}"
        }
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.ConfirmPhone" custom_fields=confirm_phone as operation_ft_ConfirmPhone %}
{% save_variable "operation_ft_ConfirmPhone" operation_ft_ConfirmPhone %}

Структура ответа (схематично):

{
    "status": "Success"
}

ft.GenerateLoyaltyCode — Генерация QR-кода авторизации

Генерирует код авторизации в программе лояльности. Используется, если на проекте применяется динамический QR-код.

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента.

Пример вызова:

{# генерируем динамический QR-код авторизации #}
{% createobj loyalty_code %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GenerateLoyaltyCode" custom_fields=loyalty_code as operation_ft_GenerateLoyaltyCode %}
{% save_variable "operation_ft_GenerateLoyaltyCode" operation_ft_GenerateLoyaltyCode %}

Структура ответа (схематично):

{
    "status": "Success",
    "loyaltyCode": "..."
}

ft.GetCustomerOrders — Список заказов по номеру телефона

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

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента.
page.pageNumber	string	Номер страницы выборки.
page.itemsPerPage	string	Количество записей на странице.

Пример вызова:

{# получаем список заказов клиента #}
{% createobj customer_orders %}
{
    "page": {
        "pageNumber": "1",
        "itemsPerPage": "10"
    },
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetCustomerOrders" custom_fields=customer_orders as operation_ft_GetCustomerOrders %}
{% save_variable "operation_ft_GetCustomerOrders" operation_ft_GetCustomerOrders %}

Структура ответа (схематично):

{
    "status": "Success",
    "orders": [
        {
            "ids": { "mindboxId": "..." },
            "totalPrice": "...",
            "processingStatus": "..."
        }
    ]
}

Дополнительные методы

ft.EditCustomer — Редактировать клиента

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

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента (идентификация).
customer.firstName	string	Имя.
customer.lastName	string	Фамилия.
customer.middleName	string	Отчество.
customer.fullName	string	ФИО одной строкой.
customer.birthDate	string	Дата рождения.
customer.sex	string	Пол.
customer.email	string	Email.
customer.timeZone	string	Часовой пояс.

Пример вызова:

{# редактируем данные клиента #}
{% createobj edit_customer %}
{
    "customer": {
        "birthDate": "{{birth_date}}",
        "sex": "{{sex}}",
        "timeZone": "{{time_zone}}",
        "lastName": "{{last_name}}",
        "firstName": "{{first_name}}",
        "middleName": "{{middle_name}}",
        "fullName": "{{full_name}}",
        "email": "{{email}}",
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.EditCustomer" custom_fields=edit_customer as operation_ft_EditCustomer %}
{% save_variable "operation_ft_EditCustomer" operation_ft_EditCustomer %}

Структура ответа (схематично):

{
    "status": "Success"
}

ft.GetTicket — Получить тикет по клиенту

Возвращает тикет (обращение / купон / запись) клиента по номеру телефона.

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента.

Пример вызова:

{# получаем тикет клиента #}
{% createobj get_ticket %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetTicket" custom_fields=get_ticket as operation_ft_GetTicket %}
{% save_variable "operation_ft_GetTicket" operation_ft_GetTicket %}

Структура ответа (схематично):

{
    "status": "Success",
    "ticket": {
        "ids": { "mindboxId": "..." }
    }
}

ft.ChatBotEvent — Событие в боте

Передаёт в Mindbox информацию о произошедшем событии в боте. Список идентификаторов (типов) событий определяет клиент.

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента.
customerAction.customFields.chatBotEventType *	string	Тип события в боте (значение из согласованного с клиентом списка).

Пример вызова:

{# фиксируем событие в боте #}
{% createobj chatbot_event %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    },
    "customerAction": {
        "customFields": {
            "chatBotEventType": "{{event_type}}"
        }
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.ChatBotEvent" custom_fields=chatbot_event as operation_ft_ChatBotEvent %}
{% save_variable "operation_ft_ChatBotEvent" operation_ft_ChatBotEvent %}

Структура ответа (схематично):

{
    "status": "Success"
}

ft.GetCustomerRecommendations — Получить рекомендации

Возвращает персональные товарные рекомендации для клиента по номеру телефона.

Параметры

Параметр	Тип	Описание
customer.mobilePhone *	string	Мобильный телефон клиента.
recommendation.limit	string	Максимальное количество рекомендаций в ответе.

Пример вызова:

{# получаем персональные рекомендации для клиента #}
{% createobj recommendations %}
{
    "customer": {
        "mobilePhone": "{{phone_number}}"
    },
    "recommendation": {
        "limit": "10"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetCustomerRecommendations" custom_fields=recommendations as operation_ft_GetCustomerRecommendations %}
{% save_variable "operation_ft_GetCustomerRecommendations" operation_ft_GetCustomerRecommendations %}

Структура ответа (схематично):

{
    "status": "Success",
    "recommendations": [
        {
            "ids": { "mindboxId": "..." },
            "name": "...",
            "price": "..."
        }
    ]
}