Instagram Direct Chatbot Mobile Development
Instagram Direct Messaging API is part of the Meta Business Platform ecosystem. Direct automation is available only through the official Instagram Graph API, and only for business or creator accounts connected to Meta Business Suite. Unofficial tools violate ToS.
Account Requirements and Setup
Working with Instagram Messaging API requires:
- Instagram Business or Creator account (not personal)
- Facebook Page linked to your Instagram account
-
Meta Developer App with permissions:
instagram_basic,instagram_manage_messages,pages_manage_metadata - Passing App Review for
instagram_manage_messages(mandatory for production)
App Review is the longest step: Meta reviews your app manually, taking 1–4 weeks. Without approval, the bot works only with test accounts.
Webhook: Receiving Messages
Instagram messages arrive via the same Webhooks Platform as Messenger, but with object = "instagram":
@app.post("/webhook")
async def instagram_webhook(request: Request):
body = await request.json()
if body.get("object") != "instagram":
return "ok"
for entry in body.get("entry", []):
for messaging in entry.get("messaging", []):
sender_id = messaging["sender"]["id"] # Instagram Scoped User ID
if "message" in messaging:
message = messaging["message"]
if "text" in message:
await handle_text(sender_id, message["text"])
elif "attachments" in message:
for att in message["attachments"]:
await handle_attachment(sender_id, att)
elif "reaction" in messaging:
# User reaction to message
await handle_reaction(sender_id, messaging["reaction"])
return "ok"
Sending Responses via Graph API
async def send_instagram_message(recipient_id: str, message_data: dict):
ig_account_id = "your_ig_account_id"
async with httpx.AsyncClient() as client:
response = await client.post(
f"https://graph.facebook.com/v18.0/{ig_account_id}/messages",
params={"access_token": PAGE_ACCESS_TOKEN},
json={
"recipient": {"id": recipient_id},
"message": message_data
}
)
return response.json()
# Text response
await send_instagram_message(sender_id, {"text": "Hi! Happy to see you."})
# Reaction to message (like)
await send_instagram_message(sender_id, {
"reaction": {
"reaction": "love",
"mid": original_message_id
}
})
Message Types and Limitations
Instagram Messaging API is less feature-rich than Telegram and even Messenger. It lacks:
- Persistent Menu
- Generic Template / Carousel (as of 2024–2025)
- Rich Media cards
- Location messages from the bot
It supports: text, images, stickers (via icebreakers), Quick Replies.
24-hour window is a strict limitation. After the user's last message, the bot can reply for 24 hours. After that, only via Human Agent Tag (if a live operator participated) or Message Tags. Unlike WhatsApp, there's no convenient mechanism for proactive template messages.
Auto-Replies to Story Mentions and Reactions
A user mentioned your account in Stories — this is a separate messaging_story_mentions event:
if "story_mention" in messaging:
story_url = messaging["story_mention"].get("url", "")
# Thank the user for the mention
await send_instagram_message(sender_id, {
"text": "Thank you for mentioning us in Stories! 🙌"
})
This is a legal and popular use case for e-commerce: automatic thanks for UGC.
Retrieving Media from Incoming Messages
A user sent a photo — the attachment contains payload.url. The URL is valid for limited time (~1 hour). Download and cache immediately:
async def process_image_message(sender_id: str, attachment: dict):
if attachment["type"] == "image":
image_url = attachment["payload"]["url"]
# Download via httpx with authorization token
image_data = await download_media(image_url, PAGE_ACCESS_TOKEN)
# Recognize via Vision API / ML Kit
result = await analyze_image(image_data)
await send_instagram_message(sender_id, {"text": result})
Typical use case: user sends a product photo, bot searches for similar items in catalog via vector similarity search.
Development Process
Setting up Meta App and passing App Review. Webhook with verification and event handling. Implementing replies to text and media. Auto-replies to Story mentions. CRM integration for dialog history. Testing on business account in test mode.
Timeline Estimates
A basic bot with text replies — 1–2 weeks (plus App Review time). A full bot with media handling, Story auto-replies, and CRM integration — 4–8 weeks.