Запуск сценарію через deeplink

Deeplink дозволяє створювати прямі посилання для запуску сценаріїв ботів з параметрами. Це корисно для створення персоналізованих посилань з рекламних кампаній, передачі ID клієнта або замовлення, або відстеження джерел трафіку.

Що таке deeplink?

В месенджерах існують механізми, які дозволяють передавати в бот вхідні параметри. Ці механізми називаються deeplink і являють собою спосіб зашити параметр в посилання, яке відкриє бот.

📖 Документація: Детальніше про deeplink читайте в офіційній документації месенджерів:

• Viber Deep Links
• Telegram Deep Linking

Коли використовувати deeplink?

Deeplink підходить для таких кейсів:

• Запуск сценарію з рекламної кампанії з унікальними параметрами
• Передача ID клієнта або замовлення через посилання
• Створення персоналізованих посилань для різних груп користувачів
• Відстеження джерела трафіку (UTM-мітки)

Формати deeplink для різних месенджерів

Telegram

Формат:

https://telegram.me/<Ім'я_бота>?start=<UserID>

Приклад:

https://telegram.me/mybot?start=12345

Обмеження:

• Обмеження для стартового параметру: 64 символи
• Для підписки на нотифікації перейти за посилання недостатньо, потрібно натиснути кнопку "Почати"

Viber

Формат:

viber://pa?chatURI=<URI>&context=<UserID>&text=<Start!>

Приклад:

viber://pa?chatURI=mybot&context=12345&text=Start!

Параметри:

• chatURI — URI вашого бота в Viber
• context — контекст (параметр, який буде передано в бот)
• text — текст, який буде підставлений в строку вводу користувача (не обов'язковий)

ℹ️ Примітка: Якщо параметр text не передавати, перехід за посиланням все одно буде вважатися початком бесіди та достатній для підписки на нотифікації.

Facebook Messenger

При використанні deeplink передається команда start. Враховуйте це, якщо ви використовуєте розгалуження сценарію з допомогою action'а get_command.

Запуск сценарію через Entry Point Deeplink URL

У будь-якій точці входу (Entry Point) є URL, який можна скопіювати щоб запустити сценарій саме з цієї точки. Це доступно для:

• Telegram
• Viber

💡 Примітка: Якщо ви не бачите URL, то перевірте чи канал підключено до бота.

Приклад URL:

https://t.me/botname/?start=n__3

Перехід по цьому посиланню призведе до запуску бота з вказаної точки входу.

Обробка стартового параметра в сценарії

Якщо ви бажаєте використовувати в сценарії стартовий параметр, використовуйте action get_command.

Як це працює:

1. Action get_command обробляє команду виду /commandname або передану через deeplink
2. Якщо переданий параметр, встановлює константу {{messenger_input_param}}
3. Далі ви маєте розібрати messenger_input_param як вам буде зручно через сценарій

Приклад обробки:

// В action jail або через if_else
const param = j.messenger_input_param || '';

if (param === '12345') {
  return 'customer_12345';
} else if (param.startsWith('order_')) {
  return 'order_tracking';
}

return 'default';

Приклади використання

Приклад 1: Передача ID клієнта

Створення посилання:

https://t.me/mybot?start=customer_12345

Обробка в сценарії:

Використовуйте {{messenger_input_param}} для отримання ID клієнта та подальшої обробки.

Приклад 2: Передача ID замовлення

Створення посилання:

https://t.me/mybot?start=order_67890

Обробка в сценарії:

Використовуйте {{messenger_input_param}} для отримання ID замовлення та подальшої обробки.

Обмеження

Telegram

• Максимальна довжина стартового параметру: 64 символи
• Потрібно натиснути кнопку "Почати" для підписки на нотифікації
• Параметр передається як /start <параметр>

Viber

• Параметр text не обов'язковий
• Перехід за посиланням достатній для підписки на нотифікації
• Параметр передається через context

Facebook Messenger

• При використанні deeplink передається команда start
• Враховуйте це, якщо ви використовуєте розгалуження сценарію з допомогою action'а get_command

Пов'язані статті

• Підписка користувача на нотифікації
• Запуск сценарію через API call_node
• Передача UTM-міток
• Що таке інтеграції
• Viber Deep Links Documentation
• Telegram Deep Linking Documentation