Instagram Onboarding Playbook

This guide walks you from an empty Instagram channel to a working setup — connect, verify, send your first reply, and handle the window rules and errors that trip up first-timers. It complements the Instagram channel page, which is the API reference; this guide is the ordered path you follow the first time, and re-run whenever you attach an additional Instagram account. There is no Meta app review to wait on and no registration cycle. The only hard gates are that the Instagram account is a Business or Creator account and that it is linked to a Facebook Page you administer — Meta enforces both, not Orbit.

1. Prerequisites

Before you open the dashboard, confirm:

An Instagram Business or Creator account. Personal profiles cannot be connected — Meta rejects their messages. Convert in the Instagram app under Settings → Account type if the profile is still personal.
A Facebook Page linked to that Instagram account, with your Facebook user as a Page admin. The link lives in the Instagram app under Settings → Linked accounts → Facebook. Meta’s OAuth dialog only lists accounts reachable through Pages you control; an unlinked Instagram account never appears.
A Meta Business Manager account at business.facebook.com, if your org centralises Meta assets there. Not strictly required for a single brand, but most portfolio setups run through it.
A dashboard role that can connect channels. The user running Connect must hold a role with channel-connect permission (Owner or Admin by default) — an agent or billing-only role will not see the Connect button.

You do not need a Meta developer app or any contracted Meta seats. Instagram messaging is billed per-conversation on Meta’s tiers — see Pricing below.

2. Connect Instagram in Orbit

Do this once per Instagram account. One Orbit account can carry several connected accounts (regional brands, sub-brands); repeat these steps for each, and each shows up as its own channel entry.

In the dashboard, go to Channels → Instagram.
Click Connect Instagram. Meta’s OAuth dialog opens and requests four scopes: instagram_basic, instagram_manage_messages, pages_messaging, and pages_show_list.
- instagram_basic identifies the professional account itself; instagram_manage_messages is the send/receive grant; the two pages_* scopes exist because Instagram messaging is delivered through Page-level plumbing.
Select the Instagram Business / Creator account to attach. If several Pages are linked, pick the account tied to the right Page.
Orbit subscribes the webhook automatically — the inbound callback is registered for you and points at Orbit’s inbound endpoint. You do not wire anything by hand in Meta’s app dashboard.
The new channel entry appears under Channels → Instagram with the connected account’s handle. If more than one account is attached, sends address whichever account owns the conversation — the connected sender is resolved from your API key, not a from field.

OAuth is dashboard-only; there is no API endpoint for the Meta sign-in itself.

3. Verify the connection and the inbound webhook

Confirm inbound delivery before you build on the channel — a connect that never pushes an inbound event usually means the wrong account got linked.

From a personal Instagram account, send a DM to the connected business account. The inbound event fires as message.received on your registered webhook endpoint and the message lands in the Inbox with the sender’s Instagram-scoped ID attached to the contact.
Send a story mention (tag the account in a story) and a story reply from the same personal account. Both arrive as message.received as well — a mention carries metadata.story_mention.url; a reply carries metadata.story_reply (url and/or id).
If you filter on quick replies later, tap a quick-reply button in a thread where one was presented — the tap arrives as message.received with quick_reply.payload populated.

A typical inbound DM webhook payload looks like:

{
  "event": "message.received",
  "channel": "instagram",
  "message": {
    "text": "Do you ship internationally?",
    "from": "<sender_igsid>"
  },
  "timestamp": "2026-08-27T09:14:03Z"
}

Two verification traps:

The sender’s IGSID is what you send to. Capture message.from (the Instagram-scoped ID) from this inbound event onto the contact — that value is the to of every outbound send.
Signature scheme. Instagram webhooks are signed with Meta’s X-Hub-Signature-256 header (the same HMAC scheme as WhatsApp), not the Standard Webhooks scheme Orbit uses for its own outbound webhooks. Verify per the channel page’s signature section before trusting the body.

4. Send your first outbound message

Inside the 24-hour window, a reply is a single call:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/instagram \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "<recipient_igsid>",
    "messaging_type": "RESPONSE",
    "message": { "text": "Thanks for reaching out! We are checking your order now." }
  }'

A queued response means Orbit accepted the send; delivery itself is reported by the webhook lifecycle on the channel page.

Window rules

The messaging_type field is not decoration — Meta enforces it, and misuse is the single most common Instagram send failure:

`messaging_type`	Use it when	Constraint
`RESPONSE`	Replying within 24h of the user’s last inbound.	Any content; this is conversational default.
`UPDATE`	A proactive, non-promotional update inside the window.	Still gated by the 24h window.
`MESSAGE_TAG`	Sending outside the 24h window.	Requires a top-level `tag` from Meta’s approved list (`HUMAN_AGENT`, `ACCOUNT_UPDATE`, `POST_PURCHASE_UPDATE`, `CONFIRMED_EVENT_UPDATE`) and only transactional content.

Rule of thumb: work inside RESPONSE whenever you can. When a reply slips past 24 hours, wait for re-engagement (re-opens the window) or switch to MESSAGE_TAG with a genuinely transactional tag — do not retry the same call and expect the window to ignore you. HUMAN_AGENT extends the reply window to seven days for human support, and is worth naming when you design an inbox SLA.

5. Handle media and quick-reply postbacks

Outbound media goes through the attachment field instead of text:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/instagram \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "<recipient_igsid>",
    "messaging_type": "RESPONSE",
    "message": {
      "attachment": {
        "type": "image",
        "payload": { "url": "https://cdn.example.com/size-guide.png" }
      }
    }
  }'

attachment.type is one of image, audio, video, file; the URL must be publicly fetchable by Meta. For a structured carousel, Orbit supports the generic template via two metadata keys — template_type: generic and a JSON-encoded elements string. The exact shape (and the fallback to plain text when elements is malformed) is on the channel page. Inbound, media and story interactions arrive as the same message.received event family, and quick-reply taps surface as postbacks with quick_reply.payload set — branch on that payload in your webhook consumer or in an inbox automation flow. Attaching quick-reply buttons to outbound DMs is not currently supported by the send API; quick replies you react to originate from flows you run behind Meta surfaces you already expose.

6. Common errors and fixes

The send API returns one of three error.code values; MESSAGE_SEND_FAILED is the umbrella under which Meta-side rejections hide, with upstream detail in details.provider_status.

INVALID_RECIPIENT (422) — the to field was missing or empty, or treated a username/phone number as a recipient. to must be the Instagram-scoped ID captured from an inbound message.received; store it on the contact at the moment it arrives. A first-send INVALID_RECIPIENT almost always means the capture step was skipped and a placeholder was sent instead.
Unlinked Page / non-professional account (MESSAGE_SEND_FAILED) — the Instagram account was never linked to the Facebook Page, so Meta cannot route its messages; or the account is still a personal profile. Link the account under Instagram Settings → Linked accounts, convert it to Business or Creator, then reconnect from Channels → Instagram → Reconnect.
Insufficient scopes (MESSAGE_SEND_FAILED) — one of the four OAuth scopes was declined during Connect, so Orbit cannot send or receive on the account’s behalf. Reconnect and accept instagram_basic, instagram_manage_messages, pages_messaging, and pages_show_list in full.
Expired page token (MESSAGE_SEND_FAILED with a 401-class provider_status) — Meta rotated the token. Reconnect from Channels → Instagram → Reconnect; no other side of the integration needs to change.
Window closed (MESSAGE_SEND_FAILED) — a RESPONSE/UPDATE more than 24h after the last inbound, or a MESSAGE_TAG without an approved tag. Send with a valid tag for transactional traffic, or wait for re-engagement.
RATE_LIMIT_EXCEEDED (429) — the send would exceed the per-tenant hourly Instagram quota (200/hour by default, matching Meta’s current cap per account). Back off and retry later; for planned batches, use the campaigns API, which paces sends, rather than a tight single-message loop.

7. Pricing

Instagram messaging follows Meta’s per-conversation pricing tiers — conversations are metered by Meta, and Orbit bills pass-through on the same model. International destinations vary; the dashboard shows the exact rate per destination before send. Public starter rates are on the pricing page.

Where to go next

Instagram channel page — full API reference: generic templates, signature verification, rate limits, error tables.
Send and receive messages — the cross-channel send pattern once you run more than one channel.
Inbox setup — route inbound Instagram traffic to your team.
Messenger onboarding — the parallel playbook if you also attach the brand’s Facebook Page.
Best practices — platform-wide sending hygiene.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Instagram onboarding playbook

Instagram Onboarding Playbook

1. Prerequisites

2. Connect Instagram in Orbit

3. Verify the connection and the inbound webhook

4. Send your first outbound message

Window rules

5. Handle media and quick-reply postbacks

6. Common errors and fixes

7. Pricing

Where to go next

​Instagram Onboarding Playbook

​1. Prerequisites

​2. Connect Instagram in Orbit

​3. Verify the connection and the inbound webhook

​4. Send your first outbound message

​Window rules

​5. Handle media and quick-reply postbacks

​6. Common errors and fixes

​7. Pricing

​Where to go next

Instagram Onboarding Playbook

1. Prerequisites

2. Connect Instagram in Orbit

3. Verify the connection and the inbound webhook

4. Send your first outbound message

Window rules

5. Handle media and quick-reply postbacks

6. Common errors and fixes

7. Pricing

Where to go next