IotaBot logo
Developer docs

IotaBot Chat API

Your website chat, in your code: every message in, live replies out.

Get an API key

Close, assign and tag website chats via API

Close, reopen, assign, tag, or hand between the AI and your team.

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

The visitor is asked to rate the chat.

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 '{
  "status": "closed"
}'
Response · 200
{
  "data": {
    "id": "6a4b9e21c3f1a2b3c4d5e6f7",
    "object": "conversation",
    "channel": "website",
    "website_id": "6a4b3fbbe291bce5bf701c5c",
    "status": "open",
    "mode": "queued_for_human",
    "subject": null,
    "contact": {
      "name": "Priya Sharma",
      "email": "priya@example.com",
      "phone": null,
      "external_id": "user_8421"
    },
    "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
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

Assign and tag

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 '{
  "assigned_agent_id": "6a4b1e…",
  "tags": [
    "vip"
  ]
}'
Response · 200
{
  "data": {
    "id": "6a4b9e21c3f1a2b3c4d5e6f7",
    "object": "conversation",
    "channel": "website",
    "website_id": "6a4b3fbbe291bce5bf701c5c",
    "status": "open",
    "mode": "queued_for_human",
    "subject": null,
    "contact": {
      "name": "Priya Sharma",
      "email": "priya@example.com",
      "phone": null,
      "external_id": "user_8421"
    },
    "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/conversationsconversations:readThe API key needs the conversations:read permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

Open chats

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=website&status=open" \
  -H "Authorization: Bearer $IOTABOT_API_KEY"
Response · 200
{
  "data": {
    "items": [
      {
        "id": "6a4b9e21c3f1a2b3c4d5e6f7",
        "object": "conversation",
        "channel": "website",
        "website_id": "6a4b3fbbe291bce5bf701c5c",
        "status": "open",
        "mode": "ai",
        "subject": null,
        "contact": {
          "name": "Priya Sharma",
          "email": "priya@example.com",
          "phone": null,
          "external_id": "user_8421"
        },
        "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