IotaBot logo
API documentation

Conversations API

List and read conversations across website chat, WhatsApp, Instagram and email; close, reopen, hand to a human, assign and tag 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

List conversations, newest first

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" \
  -H "Authorization: Bearer $IOTABOT_API_KEY"
Response · 200
{
  "data": {
    "items": [
      {
        "id": "6a4b9e21c3f1a2b3c4d5e6f7",
        "object": "conversation",
        "channel": "whatsapp",
        "website_id": "6a4b3fbbe291bce5bf701c5c",
        "status": "open",
        "mode": "ai",
        "subject": null,
        "contact": {
          "name": "Priya Sharma",
          "email": null,
          "phone": "+919812345678",
          "external_id": "919812345678"
        },
        "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
GET/v1/conversations/{id}conversations:readThe API key needs the conversations:read permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

One conversation with its contact and mode

Parameters
idrequiredIn the path
Request
curl -X GET "https://api.iotabot.com/v1/conversations/CONVERSATION_ID" \
  -H "Authorization: Bearer $IOTABOT_API_KEY"
Response · 200
{
  "data": {
    "id": "6a4b9e21c3f1a2b3c4d5e6f7",
    "object": "conversation",
    "channel": "whatsapp",
    "website_id": "6a4b3fbbe291bce5bf701c5c",
    "status": "open",
    "mode": "ai",
    "subject": null,
    "contact": {
      "name": "Priya Sharma",
      "email": null,
      "phone": "+919812345678",
      "external_id": "919812345678"
    },
    "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"
  }
}
Errors
conversation_not_found
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

Close, reopen, hand to a human or back to the AI, assign, tag

status: "closed" closes it (a website visitor is asked for a rating); status: "open" reopens it with the AI. mode: "human" puts it in the agent queue so the AI stops; mode: "ai" gives it back. assigned_agent_id is a team member's user id, or null to unassign. tags replaces the tags.

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",
  "tags": [
    "vip",
    "refund"
  ]
}'
Response · 200
{
  "data": {
    "id": "6a4b9e21c3f1a2b3c4d5e6f7",
    "object": "conversation",
    "channel": "whatsapp",
    "website_id": "6a4b3fbbe291bce5bf701c5c",
    "status": "open",
    "mode": "queued_for_human",
    "subject": null,
    "contact": {
      "name": "Priya Sharma",
      "email": null,
      "phone": "+919812345678",
      "external_id": "919812345678"
    },
    "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
GET/v1/conversations/{id}/messagesmessages:readThe API key needs the messages:read permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

The thread, oldest first

Email messages carry html — sanitised, safe to show in a browser — and html_raw, the body exactly as it arrived, plus email with from, to, cc, in_reply_to and references.

Parameters
idrequiredIn the path
limitQuery
starting_afterQuery
Request
curl -X GET "https://api.iotabot.com/v1/conversations/CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $IOTABOT_API_KEY"
Response · 200
{
  "data": {
    "items": [
      {
        "id": "6a4b9e5dc3f1a2b3c4d5e701",
        "object": "message",
        "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
        "channel": "whatsapp",
        "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"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}
Errors
conversation_not_found