IotaBot logo
Developer docs

IotaBot Instagram API

Every DM and comment on your webhook. Reply from your code.

Get an API key

Read and route Instagram conversations via API

Read threads and route them.

GET/v1/conversationsconversations:readThe API key needs the conversations:read permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

Instagram conversations

Parameters
channelQuery — website, whatsapp, instagram or email
statusQuery — open or closed
website_idQuery
updated_sinceQuery — ISO 8601 date — conversations with a message since then
limitQuery — 1–100, default 25
starting_afterQuery — the next_cursor of the previous page
Request
curl -X GET "https://api.iotabot.com/v1/conversations?channel=instagram&status=open" \
  -H "Authorization: Bearer $IOTABOT_API_KEY"
Response · 200
{
  "data": {
    "items": [
      {
        "id": "6a4b9e21c3f1a2b3c4d5e6f7",
        "object": "conversation",
        "channel": "instagram",
        "website_id": "6a4b3fbbe291bce5bf701c5c",
        "status": "open",
        "mode": "ai",
        "subject": null,
        "contact": {
          "name": "Priya Sharma",
          "email": null,
          "phone": null,
          "external_id": "17841452803019203"
        },
        "assigned_agent_id": null,
        "tags": [
          "vip"
        ],
        "integration_replies": true,
        "message_count": 4,
        "created_at": "2026-10-01T09:12:44.120Z",
        "last_message_at": "2026-10-01T09:15:02.881Z"
      }
    ],
    "has_more": true,
    "next_cursor": "6a4b9e21c3f1a2b3c4d5e6f7"
  }
}
Errors
invalid_channelchannel_not_allowedwebsite_not_allowedinvalid_limitinvalid_cursor
PATCH/v1/conversations/{id}conversations:writeThe API key needs the conversations:write permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

Hand to your team

Parameters
idrequiredIn the path
Request
curl -X PATCH "https://api.iotabot.com/v1/conversations/CONVERSATION_ID" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "human"
}'
Response · 200
{
  "data": {
    "id": "6a4b9e21c3f1a2b3c4d5e6f7",
    "object": "conversation",
    "channel": "instagram",
    "website_id": "6a4b3fbbe291bce5bf701c5c",
    "status": "open",
    "mode": "queued_for_human",
    "subject": null,
    "contact": {
      "name": "Priya Sharma",
      "email": null,
      "phone": null,
      "external_id": "17841452803019203"
    },
    "assigned_agent_id": null,
    "tags": [
      "vip",
      "refund"
    ],
    "integration_replies": true,
    "message_count": 4,
    "created_at": "2026-10-01T09:12:44.120Z",
    "last_message_at": "2026-10-01T09:15:02.881Z"
  }
}
Errors
conversation_not_foundconversation_closedagent_not_found