Как подключить CRM или CDP через нативную интеграцию — База знаний

Задача, которую решает инструкция: настроить двусторонний обмен — CRM получает события чатов через вебхуки и умеет отправлять сообщения клиентам через API Fasttrack.

Разберём на примере интернет-магазина косметики «Люблю себя»: команда разработки подключает свою CRM, чтобы менеджеры могли переписываться с покупателями из Telegram, MAX, Вконтакте и виджета сайта, не выходя из карточки клиента.

Что понадобится до начала

Доступ к личному кабинету проекта в Fasttrack с правами администратора.
Backend CRM, способный принимать входящие HTTPS-запросы (эндпоинт для вебхуков) и делать исходящие запросы к API Fasttrack.
Понимание, какие каналы клиента (Telegram, MAX, Вконтакте, Widget и т.д.) должны попадать в CRM — это понадобится на шаге регистрации вебхука.

⚠ Важно: все запросы к API должны идти из бэкенда CRM. Ходить в API Fasttrack напрямую из браузера оператора нельзя — токен доступа не должен попадать в клиентский код.

Шаг 1. Получите Bearer-токен через OAuth

Все запросы к API Fasttrack требуют авторизации. CRM проходит OAuth 2.0 и получает Bearer-токен, который передаётся в заголовке Authorization при каждом запросе.

client_id и secret_key для приложения CRM заводятся самостоятельноу — в личном кабинете Fasttrack, в разделе Настройки → OAuth: там нужно создать приложение, и платформа сразу покажет секретные данные для работы.

Полная инструкция по получению токена — отдельная статья: Подключение через OAuth. Здесь важны два момента, которые нужно заложить в архитектуру CRM сразу, а не добавлять по факту сбоя:

токен обновляется до истечения срока действия (refresh), чтобы интеграция не обрывалась незаметно;
при ошибке 401 Unauthorized CRM должна залогировать это как признак истечения токена и повторно его получить, а не просто зафиксировать сбой запроса.

⚠ Важно: токен нигде не должен фигурировать в открытом виде — ни в логах, ни в клиентском коде.

Шаг 2. Зарегистрируйте вебхук и подпишитесь на события

Когда токен получен, CRM сообщает Fasttrack, куда отправлять события — одним запросом на эндпоинт /api/partners/integrations/credentials/.

curl -X 'PUT' \
'https://dashboard.fstrk.io/api/partners/integrations/credentials/' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <_>' \
-H 'Content-Type: application/json; camelcase=1' \
-d '{
    "webhook_url": "https://your-domain.com/webhook",
    "webhook_events": [
 "message_created",
    "message_updated",
    "operator_replied",
    "session_updated"
 ],
    "webhook_platforms": [
 "Telegram",
    "Facebook",
    "Instagram",
    "Viber",
    "Whatsapp",
    "Vkontakte",
    "Widget",
    "Odnoklassniki",
    "Email",
    "API_Messenger",
    "Avito",
    "Auto_Ru",
    "Max",
    "Ozon",
    "Telegram_Personal",
    "Max_Personal"
 ]
}'

webhook_url — HTTPS-адрес CRM, куда Fasttrack будет слать POST-запросы.
webhook_events — на практике подписываются на все четыре типа события.
webhook_platforms — список каналов, актуальный полный список каналов — в Swagger Fasttrack.

Эндпоинт CRM для приёма вебхуков должен всегда отвечать HTTP 200 — независимо от того, успешно ли обработано событие внутри CRM.

⚠ Важно: при ответах кодами 3xx, 4xx или 5xx Fasttrack автоматически отключает вебхук. Обработку ошибок нужно делать асинхронно после подтверждения приёма, а не до него.

Шаг 3. Настройте приём session_updated

Вебхук session_updated приходит в двух случаях: при открытии новой чат-сессии (всегда в паре с message_created) и при передаче чата другой команде или оператору.

{
 "event_type": "session_updated",
 "payload": {
 "chat": {
    "uuid": "<uuid пользователя>",
    "platform": "Telegram",
    "phone": null,
    "name": "<имя пользователя>"
},
 "profile": {
    "uuid": "<uuid профиля>"
},
 "session": {
 "title": null,
 "context": null,
 "team": {
    "id": "<id команды>",
    "name": "<название команды>"
}
 }
 },
 "timestamp": 1777967172102
}

На этом шаге CRM должна:

создать или обновить запись чата в своей базе по chat.uuid — это ключ, который свяжет все последующие сообщения;
сохранить chat.uuid как идентификатор для дальнейшей отправки сообщений через API;
корректно обработать null в полях session.title и session.context — они не всегда заполнены;
не падать на повторных session_updated для одного и того же chat.uuid — событие может прийти снова, например при передаче чата другому оператору.

Шаг 4. Настройте приём message_created

Каждое сообщение клиента приходит вебхуком message_created. Платформа поддерживает семь типов сообщений, и CRM должна обработать каждый:

Тип	Что содержит
`text`	`text` — текст сообщения
`postback`	`text` — название нажатой кнопки в сценарии бота
`image`	`url` — ссылка на изображение, `caption` — подпись или `null`
`document`	`url` — ссылка на файл, `caption` — подпись или `null`
location	text — широта и долгота геолокации пользователя
contact	text — номер телефона пользователя
`unknown`	`error` — описание неподдерживаемого формата (например, отправка контакта)

{
 "event_type": "message_created",
 "payload": {
 "chat": {
    "uuid": "...",
    "platform": "...",
    "name": "..."
},
 "profile": {
    "uuid": "..."
},
 "message": {
    "uuid": "<uuid сообщения>",
    "type": "text",
    "text": "<текст сообщения>"
},
 "session": { "title": null, "context": null, "team": {
    "id": "...",
    "name": "..."
} }
 },
 "timestamp": 1777966993528
}

⚠ Важно: используйте message.uuid для дедупликации. Fasttrack может повторно доставить одно и то же событие — без проверки по message.uuid сообщение задвоится в истории переписки.

Шаг 5. Настройте приём operator_replied

Если чат одновременно виден и в CRM, и в чат-центре Fasttrack, оператор чат-центра тоже может ответить клиенту напрямую. Об этом Fasttrack сообщает вебхуком operator_replied — его нужно обработать отдельно от message_created, иначе CRM не будет знать о последнем ответе и рискует отправить дубль.

Структура похожа на message_created, но добавляет данные оператора:

{
 "event_type": "operator_replied",
 "payload": {
 "chat": {
    "uuid": "...",
    "platform": "...",
    "name": "..."
},
 "message": {
    "uuid": "...",
    "type": "text",
    "text": "Сообщение от оператора"
},
 "session": {
 "team": {
    "id": "...",
    "name": "..."
},
 "operator": {
    "uuid": "<uuid оператора>",
    "name": "<имя оператора>",
    "avatar": null
},
 "integration": null
 }
 },
 "timestamp": 1777966575024
}

Что важно учесть:

обрабатывайте все три типа сообщений оператора: text, image, document (у image/document здесь нет поля caption, в отличие от message_created);
визуально отделяйте в истории переписки сообщения клиента от сообщений оператора чат-центра — иначе менеджер CRM не поймёт, кто уже ответил;
session.integration может быть null — это ожидаемое поведение, не ошибка.

Шаг 6. Реализуйте отправку сообщений через API

Ответ клиенту из CRM отправляется через единый эндпоинт /api/partners/connector/. chat.uuid для этого берётся из уже полученных вебхуков session_updated или message_created.

Отправка сообщения пользователю через UUID чата

Вы можете отвечать на сообщения клиентов по API, используя следующий формат:

Endpoint: https://dashboard.fstrk.io/api/partners/connector/
HTTP-метод: POST

{
 "event": "message_created",
 "chat": {
    "uuid": "uuid чата пользователя"
},
 "message": {
    "type": "text",
    "text": "Привет,
    у меня все отлично!"
},
 "sender": {
    "name": "Иван Пупкин",
    "uuid": "uuid оператора"
},
 "timestamp": 1624607235580
}

Отправка PUSH-сообщения по профилю (UUID/номер телефона) для CDP

Предусловие. Настроенная интеграция по передаче информации профиля Fasttrack в CDP (настраивается на стороне Fasttrack кастомно или продуктизировано).

Отправить сообщение по UUID:

Endpoint: https://dashboard.fstrk.io/api/partners/push-messages/
HTTP-метод: POST

{
 "profile": {
    "uuid": "00000000-0000-0000-0000-000000000000"
},
 "content": {
    "type": "TEXT",
    "text": "Текст сообщения"
}
}

Отправить сообщение по номеру телефона:

Endpoint: https://dashboard.fstrk.io/api/partners/push-messages/
HTTP-метод: POST

{
 "profile": {
    "phone_number": "+79999999999"
},
 "content": {
    "type": "TEXT",
    "text": "Текст сообщения"
}
}

Отправка платного сообщения WABA пользователю при инициации (написать первым) или за пределами 24-х часового окна для CDP и CRM

Предварительно шаблоны должны заведены быть на платформе Fasttrack и согласованы провайдером (в текущий момент поддерживаются EDNA и SMS Traffic).

Endpoint: https://dashboard.fstrk.io/api/partners/push-messages/
HTTP-метод: POST

{
 "profile": {
    "phone_number": "+79999999999"
},
 "content": {
 "type": "WHATSAPP_TEMPLATE",
 "whatsapp_template": {
    "pid": "hello_world"
},
 "whatsapp_template_variables": {
    "v1": "Иван"
}
 }
}

Отправка сообщения используя “каскад” для CDP или CRM

Отправка одного запроса для отправки на несколько каналов пошагово.

Endpoint: https://cascades.fstrk.io/
HTTP-метод: POST

{
 "phone_number": "79991234567",
 "routing": [
 "BOT",
 "WHATSAPP",
 "VIBER",
 "VK",
 "SMS"
 ],
 "validity_period_seconds": 120,
 "whatsapp_template_name": "hello_world",
 "whatsapp_template_variables": {
    "v1": "Иван"
}
}

Ключи для авторизации при отправке каскадных запросов получаются у вашего проектного менеджера

Список шаблонов WABA

Созданные и добавленные.

Данный сценарий не является необходимым для отправки шаблонов, может использоваться для визуализации шаблонов в CDP и CRM.

Endpoint: https://dashboard.fstrk.io/api/partners/whatsapp/templates/
HTTP-метод: GET

Пример ответа:

{
 "count": 1,
 "next": null,
 "previous": null,
 "results": [
 {
 "provider_template_id": "test",
 "name": "test",
 "status": "NOT_WORKED",
 "sections": [
 "CHAT_CENTER",
 "BROADCAST_CAMPAIGNS",
 "CONSTRUCTOR"
 ],
 "text": "Hello: {{ v1 }}.",
 "variables": [
 "v1"
 ],
 "buttons": [
 {
    "text": "test"
}
 ]
 }
 ]
}

Доставка статусов WABA

Имеется возможность дополнительно в настройках в учетке Fasttrack установить специальный URL адрес, на который будут приходить статусы о доставках.

Пример события:

{
 "timestamp": 1651777267.2949505,
 "type": "update",
 "model": "message",
 "data": {
 "uuid": "7feeec45-8013-4757-afb2-6326b358082e",
 "status": "sent",
 "detail": null,
 "messages": [
 {
    "status": "undelivered",
    "error": "failed"
}
 ]
 }
}

Доставка статусов по каскадным отправкам

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

Пример события:

{
 "event_type": "transaction.done",
 "payload": {
 "uuid": "04191c1d-e7dd-4572-a544-6eb9c2855a5e",
 "done_at": "2022-05-05T18:41:00.831294Z",
 "done_status": "MESSAGE_SENT",
 "successful_routes": [
 "WHATSAPP"
 ],
 "route_details": {
 "BOT": {
    "uuid": "cfa41bcb-fdf6-4a34-a8a7-4334e5014bbc",
    "state": "ERROR",
    "response_status": null,
    "response_description": null
},
 "WHATSAPP": {
    "uuid": "855d6d27-58d4-4ae4-9deb-de6c504cc845",
    "state": "SENT",
    "response_status": "DELIVERED",
    "response_description": null
}
 }
 },
 "timestamp": 1651776060.8439758
}

Шаг 7. Проверьте отказоустойчивость перед запуском

Прежде чем выводить интеграцию в прод, убедитесь, что CRM выполняет всё это без ручного вмешательства:

отвечает 2xx на каждый вебхук — независимо от того, успела ли CRM обработать событие;
идемпотентно обрабатывает повторные доставки — по message.uuid для сообщений и по chat.uuid для сессий;
реализует retry с экспоненциальной задержкой при ошибках 5xx и 429 на исходящих запросах к /api/partners/connector/;
логирует входящие вебхуки (event_type, chat.uuid, timestamp) и исходящие запросы с полученными UUID.

Проверка интеграции

Напишите боту от своего тестового профиля — CRM должна получить session_updated и message_created и создать чат у себя.
Отправьте ещё одно сообщение — CRM не должна создать вторую запись чата или продублировать первое сообщение.
Ответьте клиенту через API CRM — сообщение должно появиться в чат-центре Fasttrack.
Ответьте тому же клиенту из чат-центра Fasttrack — CRM должна получить operator_replied и показать ответ в истории, не пытаясь отправить его повторно.
Отправьте изображение и документ в обе стороны — проверьте, что оба типа корректно отображаются.
Отправьте что-то неподдерживаемое (например, геолокацию или контакт) — CRM должна корректно обработать message.type = unknown, не сломавшись на нём.

Осторожно: актуальный список webhook_events и webhook_platforms может меняться — перед запуском в прод сверьтесь со Swagger Fasttrack, а не полагайтесь только на список из этой инструкции.