​

Instagram

​

Send a message

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! Our team will be in touch shortly." }
  }'

​

messaging_type

​

message

// Text
{ "to": "<recipient_igsid>", "messaging_type": "RESPONSE", "message": { "text": "Hello!" } }

// Media attachment — type is one of image | audio | video | file
{
  "to": "<recipient_igsid>",
  "messaging_type": "RESPONSE",
  "message": {
    "attachment": {
      "type": "image",
      "payload": { "url": "https://cdn.example.com/welcome.png" }
    }
  }
}

​

Generic templates

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": "Here are your order options" },
    "metadata": {
      "template_type": "generic",
      "elements": "[{\"title\":\"Order #1024\",\"subtitle\":\"Ships tomorrow\",\"image_url\":\"https://cdn.example.com/order.png\",\"buttons\":[{\"type\":\"web_url\",\"url\":\"https://example.com/orders/1024\",\"title\":\"Track\"}]}]"
    }
  }'

​

Response

{
  "data": {
    "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-reply postbacks (inbound) — when a user taps a quick-reply button you presented to them, the tap is delivered as a message.received webhook event with quick_reply.payload populated. Attaching quick-reply buttons to an outbound DM is not currently supported by the send API.
• Generic templates — multi-card carousels with image, title, subtitle, and buttons. Triggered on a send via metadata fields — see Generic templates below.
• 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 — delivered as standard message.received webhook events. A story mention carries metadata.story_mention.url; a story reply carries metadata.story_reply (url and/or id). There are no dedicated instagram.story.* event types — subscribe to message.received and branch on the metadata fields.
• Inbound webhooks — DMs and postbacks are POSTed to your registered webhook endpoint. Because Instagram messaging runs on Meta’s platform, these callbacks are signed with Meta’s X-Hub-Signature-256 header (the same scheme as WhatsApp), not the Standard Webhooks / Svix scheme Orbit uses for its own outbound webhooks. The header value is sha256=<hex>, where <hex> is HMAC-SHA256(rawBody) keyed with your Meta app secret. Verify it by recomputing the HMAC over the raw request body and comparing with a timing-safe check; requests with a missing or invalid signature are rejected with 401 INVALID_SIGNATURE.

​

Rate limits

​

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://api.orbit.devotel.io/api/v1/webhooks/inbound/instagram.

​

Common errors

​

Pricing