Receive Instagram DMs and comments with a webhook

Subscribe once; both arrive with their conversation_id.

POST/v1/webhook-endpointswebhooks:manage

Add a webhook endpoint

Request

curl -X POST "https://api.iotabot.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://crm.acme.com/iotabot",
  "channels": [
    "instagram"
  ],
  "events": [
    "message.received",
    "comment.received"
  ]
}'

Response · 201

{
  "data": {
    "id": "6a4bb0…",
    "object": "webhook_endpoint",
    "url": "https://crm.acme.com/iotabot",
    "status": "active",
    "secret": "whsec_…",
    "verification": {
      "verified": true,
      "reason": null
    }
  }
}

WEBHOOKmessage.received

A DM.

{
  "id": "evt_6a4ba40bc3f1a2b3c4d5e750",
  "object": "event",
  "type": "message.received",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T09:15:02.881Z",
  "livemode": true,
  "channel": "instagram",
  "website_id": "6a4b3fbbe291bce5bf701c5c",
  "data": {
    "message": {
      "id": "6a4b9e5dc3f1a2b3c4d5e701",
      "object": "message",
      "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
      "channel": "instagram",
      "direction": "inbound",
      "sender": {
        "type": "visitor",
        "name": null
      },
      "type": "text",
      "text": "Hi, where is my order #1042?",
      "html": null,
      "html_raw": null,
      "attachments": [],
      "status": "received",
      "delivery": null,
      "created_at": "2026-10-01T09:15:02.881Z"
    },
    "conversation": {
      "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": [],
      "integration_replies": true,
      "message_count": 3,
      "created_at": "2026-10-01T09:12:44.120Z",
      "last_message_at": "2026-10-01T09:15:02.881Z"
    }
  }
}

WEBHOOKcomment.received

A comment on one of your posts.

{
  "id": "evt_6a4ba40bc3f1a2b3c4d5e750",
  "object": "event",
  "type": "comment.received",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T09:15:02.881Z",
  "livemode": true,
  "channel": "instagram",
  "website_id": "6a4b3fbbe291bce5bf701c5c",
  "data": {
    "message": {
      "id": "6a4b9e5dc3f1a2b3c4d5e701",
      "object": "message",
      "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
      "channel": "instagram",
      "direction": "inbound",
      "sender": {
        "type": "visitor",
        "name": null
      },
      "type": "text",
      "text": "Is this available in blue?",
      "html": null,
      "html_raw": null,
      "attachments": [],
      "status": "received",
      "delivery": null,
      "created_at": "2026-10-01T09:15:02.881Z"
    },
    "conversation": {
      "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": [],
      "integration_replies": true,
      "message_count": 3,
      "created_at": "2026-10-01T09:12:44.120Z",
      "last_message_at": "2026-10-01T09:15:02.881Z"
    }
  }
}