IotaBot logo
Developer docs

IotaBot WhatsApp API

Send and receive WhatsApp messages from your code — on every number you connected.

Get an API key

Read and route WhatsApp conversations via API

Read threads, and decide who answers — your code, the AI or your team.

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

WhatsApp 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=whatsapp&status=open" \
  -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}/messagesmessages:readThe API key needs the messages:read permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

A conversation's messages

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
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

The AI stops replying.

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": "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