How to connect Instagram to a CRM

The short answer

Step by step

1. 1

   Prepare the account

   Switch the Instagram account to Business or Creator — personal accounts are not supported. Link a Facebook Page only if you use Facebook Login or need Lead Ads.

2. 2

   Create the Meta app

   Open an app in Meta for Developers, add the Instagram and Webhooks products, and store the app secret somewhere safe.

3. 3

   Request permissions

   instagram_manage_messages (or instagram_business_manage_messages with Instagram Login) for conversations; leads_retrieval, pages_manage_ads and ads_management for leads; pages_show_list, pages_read_engagement and pages_manage_metadata for Pages and webhooks. Ask only for what you use.

4. 4

   Write the OAuth flow

   A “Connect Instagram” button in the CRM sends the user to the chosen login dialog (Facebook or Instagram). Exchange the returned code for a token on the server: with Facebook Login store the Pages and each linked Instagram account ID, with Instagram Login store the Instagram user ID.

5. 5

   Wire up the webhook

   Expose an HTTPS endpoint with a valid certificate, answer the hub.challenge check (verify_challenge), verify X-Hub-Signature-256 on the raw body (verify_request) and subscribe each Page to your app (fb.subscribe_page). Comment webhooks need Advanced Access and the app in Live mode.

6. 6

   Map the events

   New conversation → contact and deal; lead form → lead; comment → task. Tag every record with its source.

7. 7

   Close the reply loop

   Let reps answer from inside the CRM. That works within the 24-hour window — surface the window in the UI. Outside the window a human_agent tag allows replies for up to 7 days (requires the Human Agent feature); ig.send_message() sends no tag.

OAuth callback — Pages and Instagram accounts

Facebook Login path: the code is exchanged for a token and each Page is stored with its linked Instagram account.

import asyncio
from socialift import Facebook

async def main(code: str):
    # FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, SOCIALIFT_LICENSE_KEY — env
    async with Facebook.from_env() as fb:
        token = await fb.exchange_code(code, redirect_uri="https://your-domain/cb")
        for page in await fb.pages(token.access_token):
            # the Page, its token (store it encrypted) and the linked Instagram account
            crm.save_connection(page.id, page.access_token, page.instagram_id)

asyncio.run(main("CODE_FROM_CALLBACK"))

Turning conversations into CRM contacts

import asyncio, os
from socialift import Instagram

async def main():
    async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
        chats = await ig.conversations(page_token, page_id=PAGE_ID, ig_user_id=IG_USER_ID)
        for chat in chats["data"]:
            c = chat["contact"]
            if not c:
                continue
            crm.upsert_contact(external_id=c["id"], name=c.get("name") or c.get("username"),
                               source="instagram_direct", followers=c.get("follower_count"),
                               is_follower=c.get("is_user_follow_business"))

asyncio.run(main())

The mistakes people make most

• ▸The account is still personal (not Business or Creator) — the API does not work at all.
• ▸App Review was skipped: what worked for accounts with a role on the app fails for other customers.
• ▸The app was never set to Live or the Page was never subscribed — webhooks do not arrive.
• ▸The webhook signature was computed over re-serialised JSON.
• ▸Events were not deduplicated — duplicate deals appeared in the CRM.
• ▸The 24-hour window was ignored — replies bounced back unsent.
• ▸Token expiry was not tracked — the integration stopped silently.

How long it takes