Розробка бота для Instagram з інтеграцією Бітрікс24

Розробка бота для Instagram з інтеграцією Bitrix24

Instagram Direct — основний канал комунікації для e-commerce, beauty, fashion та інших B2C-сегментів. Бот обробляє вхідні повідомлення в Direct, відповідає за сценарієм і створює ліда в Bitrix24. Менеджер продовжує діалог із CRM, не виходячи в Instagram.

Технічні умови: Instagram Messaging API

Instagram Messaging API працює через платформу Meta. Вимоги:

• Акаунт Instagram Business або Creator, прив'язаний до Facebook-сторінки.
• Facebook Developer App із продуктами Messenger + Instagram.
• Дозволи: instagram_basic, instagram_manage_messages, pages_manage_metadata.
• HTTPS-сервер для webhook.

Instagram Messaging API — це той самий Messenger Platform, але вхідні повідомлення мають тип instagram_id відправника, а не Facebook PSID. Webhook підписується на об'єкт instagram у налаштуваннях програми.

Що вміє бот в Instagram

Instagram Direct підтримує:

• Текстові повідомлення — основний потік.
• Швидкі відповіді (quick replies) — кнопки-підказки.
• Story mentions — користувач згадав бізнес-акаунт у Stories. Бот отримує подію та може відповісти автоматично.
• Ice breakers — запитання-стартери, які користувач бачить при першому відкритті діалогу.

Чого немає: каруселі Generic Template в Instagram обмежені — підтримується лише media_share і прості кнопки з посиланнями.

Приймання повідомлень через webhook

{
  "entry": [{
    "id": "IG_ACCOUNT_ID",
    "messaging": [{
      "sender": { "id": "IG_USER_IGSID" },
      "recipient": { "id": "IG_ACCOUNT_ID" },
      "timestamp": 1710000000000,
      "message": {
        "mid": "aWdfZAG9...",
        "text": "Скільки коштує доставка?"
      }
    }]
  }]
}

IGSID (Instagram-Scoped ID) — унікальний ID користувача для вашої програми. Це не публічний Instagram ID.

Отримання профілю користувача Instagram

$profile = json_decode(file_get_contents(
    "https://graph.instagram.com/{$igsid}?fields=name,username&access_token=" . IG_ACCESS_TOKEN
), true);
// Повертає: name (відображуване ім'я), username (@handle)

Автовідповідь на згадки в Stories

Коли користувач згадує ваш акаунт у Stories, надходить webhook-подія messaging_referral з type=STORY_MENTION. Бот може автоматично подякувати:

if ($event['type'] === 'STORY_MENTION') {
    sendIgMessage($igsid, "Дякуємо, що згадали нас у Stories! Хочете дізнатися про актуальні акції?");
    logLeadSource($igsid, 'story_mention');
}

Story mentions — теплі ліди: людина вже взаємодіяла з брендом.

Сценарій кваліфікації ліда

Вхідне повідомлення
    ↓
Стан = null → привітання + швидкі відповіді
    ↓
Вибір: "Хочу замовити"
    ↓
Запит телефону / email
    ↓
Створення ліда в Б24 + повідомлення менеджера
    ↓
Повідомлення: "Менеджер зв'яжеться з вами протягом години"

Стани діалогу зберігаються в Redis за ключем ig_dialog:{igsid}. TTL — 24 години (вікно активності в Instagram).

Інтеграція з Bitrix24

function createInstagramLead(string $igsid, string $username, array $data): int {
    return $b24->callMethod('crm.lead.add', [
        'fields' => [
            'TITLE'              => "Instagram: @{$username}",
            'SOURCE_ID'          => 'WEBFORM',
            'SOURCE_DESCRIPTION' => 'Instagram Direct',
            'PHONE'              => !empty($data['phone']) ? [['VALUE' => $data['phone'], 'VALUE_TYPE' => 'WORK']] : [],
            'EMAIL'              => !empty($data['email']) ? [['VALUE' => $data['email'], 'VALUE_TYPE' => 'WORK']] : [],
            'COMMENTS'           => "Instagram: @{$username}\nIGSID: {$igsid}",
            'UF_CRM_IG_IGSID'   => $igsid,
        ],
    ])['result'];
}

// Історія переписки — в активність
$b24->callMethod('crm.activity.add', [
    'fields' => [
        'OWNER_TYPE_ID' => 1,
        'OWNER_ID'      => $leadId,
        'TYPE_ID'       => 4,
        'SUBJECT'       => "Instagram Direct: @{$username}",
        'DESCRIPTION'   => implode("\n", $dialogMessages),
    ],
]);

Ice breakers: запитання при першому відкритті діалогу

Через API програми налаштовуються підказки, які користувач бачить при першому відкритті діалогу з бізнес-акаунтом:

callMetaApi('me/messenger_profile', 'POST', [
    'platform'     => 'instagram',
    'ice_breakers' => [
        ['call_to_actions' => [
            ['type' => 'postback', 'title' => 'Дізнатися про доставку', 'payload' => 'DELIVERY_INFO'],
            ['type' => 'postback', 'title' => 'Залишити заявку',        'payload' => 'LEAVE_REQUEST'],
            ['type' => 'postback', 'title' => 'Переглянути каталог',    'payload' => 'CATALOG'],
        ]],
    ],
]);

Обмеження платформи Meta для Instagram

• Повідомлення від бота приймаються лише протягом 24 годин після останнього повідомлення користувача.
• Не можна ініціювати діалог самостійно (бот не може написати першим).
• Програма проходить ревʼю Meta: instagram_manage_messages — розширений дозвіл, що вимагає перевірки.
• Масові розсилки заборонені умовами платформи.

Терміни

Разом: 2–3 тижні з урахуванням ревʼю Meta. Якщо програма вже пройшла ревʼю для Messenger-бота, дозволи Instagram додаються швидше.