Developing an Instagram bot with Bitrix24 integration

Instagram Bot Development with Bitrix24 Integration

Instagram Direct is the primary communication channel for e-commerce, beauty, fashion and other B2C segments. The bot processes incoming Direct messages, responds according to a scenario and creates a lead in Bitrix24. The manager continues the conversation from the CRM without leaving to Instagram.

Technical Requirements: Instagram Messaging API

Instagram Messaging API works through the Meta platform. Requirements:

• Instagram Business or Creator account linked to a Facebook Page.
• Facebook Developer App with Messenger + Instagram products.
• Permissions: instagram_basic, instagram_manage_messages, pages_manage_metadata.
• HTTPS server for webhook.

Instagram Messaging API is the same Messenger Platform, but incoming messages have an instagram_id sender type rather than a Facebook PSID. The webhook subscribes to the instagram object in the app settings.

What the Bot Can Do on Instagram

Instagram Direct supports:

• Text messages — the main flow.
• Quick replies — hint buttons.
• Story mentions — a user mentioned the business account in Stories. The bot receives the event and can respond automatically.
• Ice breakers — starter questions the user sees when first opening a conversation.

What is missing: Generic Template carousels in Instagram are limited — only media_share and simple link buttons are supported.

Receiving Messages via Webhook

{
  "entry": [{
    "id": "IG_ACCOUNT_ID",
    "messaging": [{
      "sender": { "id": "IG_USER_IGSID" },
      "recipient": { "id": "IG_ACCOUNT_ID" },
      "timestamp": 1710000000000,
      "message": {
        "mid": "aWdfZAG9...",
        "text": "How much does delivery cost?"
      }
    }]
  }]
}

IGSID (Instagram-Scoped ID) is a unique user ID for your app. This is not the public Instagram ID.

Retrieving an Instagram User's Profile

$profile = json_decode(file_get_contents(
    "https://graph.instagram.com/{$igsid}?fields=name,username&access_token=" . IG_ACCESS_TOKEN
), true);
// Returns: name (display name), username (@handle)

Auto-Reply to Story Mentions

When a user mentions your account in Stories, a webhook event messaging_referral with type=STORY_MENTION arrives. The bot can automatically send a thank-you:

if ($event['type'] === 'STORY_MENTION') {
    sendIgMessage($igsid, "Thanks for mentioning us in your Stories! Want to know about our current offers?");
    logLeadSource($igsid, 'story_mention');
}

Story mentions are warm leads: the person has already interacted with the brand.

Lead Qualification Scenario

Incoming message
    ↓
State = null → greeting + quick replies
    ↓
Choice: "I want to order"
    ↓
Request phone / email
    ↓
Create lead in B24 + notify manager
    ↓
Message: "A manager will contact you within an hour"

Conversation states are stored in Redis under the key ig_dialog:{igsid}. TTL — 24 hours (Instagram activity window).

Bitrix24 Integration

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'];
}

// Conversation history — as an activity
$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: Questions at First Dialog Open

Through the app API, hints are configured that the user sees when first opening a conversation with the business account:

callMetaApi('me/messenger_profile', 'POST', [
    'platform'     => 'instagram',
    'ice_breakers' => [
        ['call_to_actions' => [
            ['type' => 'postback', 'title' => 'Delivery info',    'payload' => 'DELIVERY_INFO'],
            ['type' => 'postback', 'title' => 'Leave a request',  'payload' => 'LEAVE_REQUEST'],
            ['type' => 'postback', 'title' => 'Browse catalogue', 'payload' => 'CATALOG'],
        ]],
    ],
]);

Meta Platform Limitations for Instagram

• The bot's messages are only accepted within 24 hours of the user's last message.
• Initiating a conversation is not possible (the bot cannot write first).
• The app goes through Meta review: instagram_manage_messages is an extended permission requiring verification.
• Mass messaging is prohibited by platform terms.

Timelines

Total: 2–3 weeks including Meta review. If the app has already passed review for a Messenger bot, Instagram permissions are added faster.