Facebook Messenger and Instagram

Messages to your Facebook Page (from Facebook, Messenger or an m.me link) and Direct messages to your Instagram professional account (including replies to your stories and mentions of your account in theirs) are two channels with one setup: a Meta app of your own, a Page access token that does not expire and the app's app secret. Agents, bots, chatbot flows and the AI agent answer them like any other conversation. Instagram here means the Messenger Platform's Instagram messaging: the account must be a professional (business or creator) account linked to a Facebook Page, and Kommio uses that Page's token.

Set it up

1. Prepare the Page and the app

   You need a Facebook Page you administer and, for Instagram, a professional account linked to it (Meta Business Suite › Settings › Instagram accounts) with Allow access to messages on in the Instagram app (Settings › Messages and story replies › Message controls › Connected tools). Create a Meta app of type Business in Meta for Developers and add the Messenger product; Instagram messaging is configured under Messenger › Instagram settings. One app can serve a Messenger inbox and an Instagram inbox of the same Page, but the app's webhook points at one address per object, so plan one Page per app and product.

2. Get a Page access token

   Grant the app, for the Page, pages_messaging and pages_manage_metadata (Messenger) or instagram_basic, instagram_manage_messages and pages_manage_metadata (Instagram), plus pages_show_list to find the Page's token. For production, add a system user in Meta Business Suite › Settings › Users › System users, assign it the app (Manage) and the Page (Full control), generate a token with those permissions and expiry Never, then turn it into the Page's token with GET https://graph.facebook.com/v23.0/me/accounts?access_token=<system user token> and copy the Page's access_token. For a quick start, the Graph API Explorer gives a user token with the same permissions; exchange it for a long-lived one and read /me/accounts the same way. The app secret is under App settings › Basic › App secret › Show.

3. Connect

   Settings › Marketplace › Facebook Messenger (or Instagram) › Install in this workspace, or Settings › Inboxes › New inbox › Facebook Messenger (or Instagram). Paste the Page access token and the app secret and press Test connection: Kommio asks Meta who the app is (which also proves the secret belongs to the token's app), checks that the token is a valid Page token with the permissions and when it expires, and shows the Page, the app and, for Instagram, the account linked to the Page (you may give the account's numeric id to have it checked).

4. Point the webhook at Kommio

   Leave Point the app's webhook at Kommio on (the default): when the inbox is created Kommio sets the app's webhook for the Page object (Messenger) or the Instagram object to the inbox's own address, with a verify token of its own, and subscribes the Page to the app. Meta verifies the address at once, so Kommio must be reachable from the internet. Turn it off to set the webhook yourself: the inbox page shows the Callback URL (https://<your kommio address>/api/public/channel-hooks/<inbox key>), the Verify token and the fields to subscribe for App Dashboard › Webhooks.

5. Try it

   Name the inbox and choose its agents. The last step shows the Page's m.me link, or the account's ig.me link, with a button: send a message, it arrives in the inbox, and your reply comes back. While the app is in development mode only people with a role on it (administrators, developers, testers) can write and get answers.

Token and secret are stored encrypted and never returned by the API. After a new token or a reset app secret, paste both on the inbox's page (Replace the credentials); saving the inbox sets the webhook and the Page subscription again, which is also how to point the webhook back after someone changed it in the App Dashboard. Kommio proves the app secret on every call to Meta, so you may turn on Require App Secret in the app's advanced settings. A second Page on the same app would post to the first inbox; Kommio does not mix them up (its events are not stored and the inbox shows a notice), but use one app per Page, or leave the webhook option off on the second inbox.

What is supported

Customers are contacts with a Messenger or Instagram identity. Meta gives each person a different id per Page and per Instagram account, so the same person writing to two Pages is two identities (merge the contacts to see them as one). The name, the Instagram user name (contact attribute instagram_username) and the picture come from Meta's profile API; people who have not granted the app access keep a placeholder name such as "Messenger user 654321". A message the Page or account sends from somewhere else (Meta Business Suite's inbox, the Instagram app) appears in the conversation marked "outside Kommio"; replies Kommio sends are never shown twice.

The 24-hour window and message tags

Meta lets a business answer a customer within 24 hours of the customer's last message, and the composer shows when the window closes. After that the composer offers Meta's tags: HUMAN_AGENT lets a person (not a bot or automation) answer for up to 7 days after the customer's last message, and needs the Human Agent permission approved in App Review; Messenger also accepts ACCOUNT_UPDATE, CONFIRMED_EVENT_UPDATE and POST_PURCHASE_UPDATE for those non-promotional updates only, Instagram HUMAN_AGENT only. A reply without a tag is refused before it is queued, with the reason; a reply still queued when the window closes fails for good; satisfaction surveys are sent only while the window is open. Bots and flows cannot start conversations: the customer writes first.

Pausing, deleting, health

A paused inbox refuses Meta's deliveries; Meta retries for a while and then drops them. Pausing leaves Meta as it is (a Messenger and an Instagram inbox of one Page share the Page's subscription), and resuming sets the webhook and the subscription again. After deleting an inbox, remove the webhook or the Page from the app in the App Dashboard if nothing else uses it.

Every five minutes Kommio asks Meta about the token (still valid, with a warning a week before it expires), the Page's subscription to the app (subscribed again when it is gone) and, when Kommio set it, the app's webhook (pointed elsewhere, or turned off by Meta after too many failed deliveries). A token Meta refuses marks the inbox and its installation under Settings › Marketplace › Installed for a reconnect. If nothing arrives, check App Dashboard › Webhooks (the object's callback is the inbox's address and its fields are subscribed), that the sender has a role on the app while it is in development mode and, for Instagram, that "Allow access to messages" is on; 401s in Meta's webhook log mean the app secret on the inbox is not the app's. "(#10) outside of allowed window" means the 24 hours have passed; "(#551) This person isn't available" that the customer blocked the Page or deleted their account.

API

# check the credentials: the app, the Page and, for Instagram, the linked account
curl -X POST "$KOMMIO_URL/channels/messenger/test" -H "Authorization: Bearer $KOMMIO_KEY" -H "Content-Type: application/json" \
  -d '{"config": {"page_access_token": "EAAGm0PX4ZCpsBAJZCZB1pgMlxuvYkn8Q1b5f", "app_secret": "<app secret>"}}'

# create the inbox ("channel_kind": "instagram" for Instagram, optionally with "instagram_account_id": "17841405822304914")
curl -X POST "$KOMMIO_URL/inboxes" -H "Authorization: Bearer $KOMMIO_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Messenger", "channel_kind": "messenger", "config": {"page_access_token": "EAAGm0PX4ZCpsBAJZCZB1pgMlxuvYkn8Q1b5f", "app_secret": "<app secret>"}}'

The inbox's config then carries page_id, page_name, app_id, app_name, for Instagram instagram_account_id and instagram_username, the webhook address Kommio set and the inbox's verify_token; configure_webhook: false leaves the app's webhook alone. Replying outside the window without a tag returns 422 with the reason.