Skip to main content

Instagram DM

Connect your Instagram Business Account to SendSeven to send and receive Direct Messages. Instagram DM supports text, images, video, buttons, carousel, and reactions.

Prerequisites​

  • An Instagram Business or Creator account (no Facebook Page required)
  • Instagram Login OAuth completed in the SendSeven dashboard
  • A SendSeven API token with channels:create scope

Setup​

Instagram channels are configured through the SendSeven dashboard using Instagram's own login ("Instagram API with Instagram Login"):

  1. Log in to SendSeven
  2. Navigate to Settings > Channels
  3. Click Connect Instagram
  4. Sign in with the Instagram professional account and grant the requested permissions
info

Webhooks are subscribed directly on the Instagram account -- no Facebook Page is involved. SendSeven configures this automatically when the channel is created.

caution

"Allow access to messages" must be enabled in the Instagram app (Settings > Messages and story replies > Connected tools). Without it the channel connects but no webhooks arrive.

Instagram Capabilities​

FeatureSupported
TextYes
ImageYes
VideoYes
AudioNo
DocumentNo
ButtonsYes
List messagesNo
CarouselYes (generic template, up to 10 cards, see below)
ReactionsYes
Read receiptsYes
Comments to private replyYes (beta) — text, buttons and quick replies; no images

Comments on your posts​

Instagram channels can also receive comments on your posts and reels, and answer the commenter with a one-time private reply. This requires the instagram_business_manage_comments permission, which is granted at connect time — an account connected earlier must be reconnected.

See Comments to Private Replies.

Contact Identifiers​

Instagram contacts are stored with two identifiers:

FieldDescription
instagram_idInstagram-scoped ID used for API calls
instagram_usernameThe @handle used for display purposes

Required Scopes​

ScopePurpose
channels:createCreate an Instagram channel
channels:readView channel details
messages:createSend messages through Instagram DM

Send an Instagram DM​

curl -X POST "https://api.sendseven.com/api/v1/messages" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_ig_789",
    "channel_id": "ch_ig_001",
    "text": "Thanks for your interest! Here is more info about our products.",
    "message_type": "text"
  }'
warning

Instagram has its own messaging window rules. You can respond to a user's message within 24 hours. After that, messaging may be restricted depending on the type of interaction.

Send up to 10 scrollable cards with POST /messages/send/carousel, using the elements field (the same shape as Messenger):

curl -X POST "https://api.sendseven.com/api/v1/messages/send/carousel" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_ig_789",
    "channel_id": "ch_ig_001",
    "elements": [
      {
        "title": "Summer Sneaker",
        "subtitle": "EUR 89, sizes 36 to 46",
        "image_url": "https://shop.example.com/images/sneaker.jpg",
        "buttons": [
          {"type": "web_url", "title": "Shop now", "url": "https://shop.example.com/sneaker"},
          {"type": "postback", "title": "Ask a question", "payload": "ASK_SNEAKER"}
        ]
      }
    ]
  }'

Instagram limits, checked by SendSeven before sending:

  • 1 to 10 cards; title required, title and subtitle up to 80 characters
  • every card needs a subtitle, image, tap action (default_action) or button besides its title
  • up to 3 buttons per card, web_url and postback only (no phone_number), labels up to 20 characters, postback payload up to 1000 characters
  • images as absolute http(s) URLs, PNG or JPEG up to 8 MB
  • shown in the Instagram mobile app only, not on desktop

A carousel that breaks a rule is rejected with 400 and a code such as CAROUSEL_BUTTON_UNSUPPORTED in detail.error (full list in Carousel messages). When the contact taps a postback button, you receive an inbound message with your payload in meta.button_id, just like a Messenger button tap.

Channel health​

If Meta rejects several messages to different contacts with a permission error (#10 or #200), the channel stays active but is reported as degraded: degraded_reason, degraded_since and degraded_error_code on the channel, and a connection_status: "degraded" item in GET /api/v1/channels/health. It clears with the next successful send. See Permission warning.

Next Steps​