Check the Instagram 24-hour messaging window via API

Who you can DM right now, and how long you have left — for one person or your whole list.

Instagram allows a DM only within 24 hours of the customer's last message. After that, nothing can be sent until they write again.
Check people by instagram_username, instagram_user_id or conversation_id — up to 100 per call, mixed.
Each answer has can_send, window_closes_at and seconds_left, or a reason it cannot be sent.
Usernames match as IotaBot last saw them; instagram_user_id from your webhooks always matches.

GET/v1/messaging-windowconversations:read

Everyone you can DM now

Closing soonest first. closes_within_minutes keeps only those about to close.

Parameters

channel	Query — whatsapp or instagram — both when left out
closes_within_minutes	Query — 1–1440: only windows closing within this many minutes
limit	Query — 1–100, default 25
starting_after	Query — the next_cursor of the previous page

Request

curl -X GET "https://api.iotabot.com/v1/messaging-window?channel=instagram&closes_within_minutes=180" \
  -H "Authorization: Bearer $IOTABOT_API_KEY"

Response · 200

{
  "data": {
    "checked_at": "2026-10-02T09:00:58.000Z",
    "items": [
      {
        "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f8",
        "channel": "instagram",
        "thread": "dm",
        "account_id": "6a4c02bb…",
        "contact": {
          "name": "priya.styles",
          "phone": null,
          "email": null,
          "external_id": "17841400000000001"
        },
        "window_closes_at": "2026-10-02T14:05:00.000Z",
        "seconds_left": 18342,
        "last_customer_message_at": "2026-10-01T14:05:00.000Z",
        "can_send": true,
        "reason": null
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}

Errors

invalid_channelinvalid_limitinvalid_cursor

POST/v1/messaging-window/checkconversations:read

Check usernames

Request

curl -X POST "https://api.iotabot.com/v1/messaging-window/check" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "instagram_username": "priya.styles"
    },
    {
      "instagram_username": "@arjun.k"
    },
    {
      "instagram_user_id": "17841400000000001"
    }
  ]
}'

Response · 200

{
  "data": {
    "checked_at": "2026-10-02T09:00:58.000Z",
    "items": [
      {
        "input": {
          "instagram_username": "priya.styles"
        },
        "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f8",
        "channel": "instagram",
        "thread": "dm",
        "account_id": "6a4c02bb…",
        "contact": {
          "name": "priya.styles",
          "phone": null,
          "email": null,
          "external_id": "17841400000000001"
        },
        "window_closes_at": "2026-10-02T14:05:00.000Z",
        "seconds_left": 18342,
        "last_customer_message_at": "2026-10-01T14:05:00.000Z",
        "can_send": true,
        "reason": null
      },
      {
        "input": {
          "phone": "+919812345678"
        },
        "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
        "channel": "instagram",
        "account_id": "6a4c01aa…",
        "contact": {
          "name": "Priya Sharma",
          "phone": "+919812345678",
          "email": null,
          "external_id": "919812345678"
        },
        "window_closes_at": null,
        "seconds_left": 0,
        "last_customer_message_at": "2026-09-28T09:15:02.881Z",
        "can_send": false,
        "reason": "window_closed",
        "template_allowed": true
      },
      {
        "input": {
          "instagram_username": "arjun.k"
        },
        "conversation_id": null,
        "channel": "instagram",
        "can_send": false,
        "window_closes_at": null,
        "seconds_left": null,
        "last_customer_message_at": null,
        "reason": "no_conversation"
      }
    ]
  }
}

Errors

invalid_request

POST/v1/messagesmessages:send

Then DM them

With the conversation_id from the check.

Request

curl -X POST "https://api.iotabot.com/v1/messages" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
  "text": "Our festive sale ends tonight — 20% off with code DIWALI20."
}' \
  -H "Idempotency-Key: order-1042-shipped"

Response · 202

{
  "data": {
    "id": "6a4ba0f1c3f1a2b3c4d5e733",
    "object": "message",
    "status": "queued",
    "channel": "instagram",
    "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
    "created_at": "2026-10-01T09:16:10.004Z"
  }
}

Errors

window_closedconversation_closedintegration_pausedprivate_reply_expiredprivate_reply_usedrecipient_opted_outunsupported_attachmentfile_already_usedattachments_too_largeapi_quota_exceededidempotency_key_reusedidempotency_in_progress

A comment thread's window is its private reply: once per comment, within 7 days. Check it by its conversation_id.

The answer is a snapshot. A window can close between the check and the send — the send is still checked and refused with window_closed.