Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orbit-docs.devotel.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Instagram

Instagram messaging connects your business to users via the Instagram Graph API. Orbit handles the OAuth onboarding, page-level permission scopes, and the async webhook fan-in for inbound DMs, story replies, and quick-reply postbacks. A single Orbit account can attach multiple connected Instagram Business or Creator accounts; messages are billed per-conversation per Meta’s pricing tiers.

​
Send a message

curl -X POST https://orbit-api.devotel.io/api/v1/messages/instagram \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "<recipient_igsid>",
    "from": "<your_ig_business_account_id>",
    "type": "text",
    "text": "Thanks for reaching out! Our team will be in touch shortly."
  }'

​
Response

{
  "data": {
    "message_id": "msg_ig_abc123",
    "status": "queued",
    "channel": "instagram"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

​
Capabilities

  • Text + media — text, image, video, audio, file attachments (up to Meta’s per-type size caps).
  • Quick replies — up to 13 buttons; postbacks are delivered as message.received webhook events with quick_reply.payload populated.
  • Generic templates — multi-card carousels with image, title, subtitle, and buttons.
  • 24-hour messaging window — inside the standard messaging window, replies are free; outside the window, only MESSAGE_TAGS (HUMAN_AGENT, ACCOUNT_UPDATE, POST_PURCHASE_UPDATE, CONFIRMED_EVENT_UPDATE) can be used.
  • Story mention + story reply — surfaced via instagram.story.mention and instagram.story.reply webhook events.
  • Inbound webhooks — DMs and postbacks are POSTed to your registered webhook endpoint with the same Standard-Webhooks signature scheme used across Orbit.

​
Onboarding flow

  1. From the dashboard, navigate to Channels → Instagram.
  2. Click Connect Instagram and authorise via Meta’s OAuth dialog. The dialog requests instagram_basic, instagram_manage_messages, pages_messaging, and pages_show_list scopes.
  3. Select the Instagram Business / Creator account you want to attach.
  4. Verify the inbound webhook subscription registered automatically; the webhook URL points to https://orbit-api.devotel.io/api/v1/webhooks/inbound/instagram.

​
Common errors

CodeHTTPCauseFix
IG_NOT_AUTHORIZED401The connected page’s access token has expired or been revoked.Reconnect via Channels → Instagram → Reconnect.
IG_OUTSIDE_MESSAGING_WINDOW422Outbound message sent more than 24 hours after the user’s last message.Use a MESSAGE_TAG for transactional / customer-care exceptions, or wait for the user to message first.
IG_NOT_BUSINESS_ACCOUNT422The attached Instagram account is a personal profile, not Business / Creator.Convert to a Business or Creator account in the Instagram app settings, then reconnect.
IG_RECIPIENT_OPTED_OUT422The user has blocked your account or unfollowed you.Skip the send; this is permanent until the user re-engages.
IG_RATE_LIMITED429Per-page rate limit exceeded (varies by Meta tier).Back off and retry after Retry-After; consider batching via the campaigns API.

​
Pricing

Pay-as-you-go conversation pricing per Meta’s Messaging Tiers. International destinations vary; the dashboard shows the exact rate per destination before send. See the pricing page for public starter rates.