IotaBot logo
Developer docs

IotaBot WhatsApp API

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

Get an API key

Receive WhatsApp messages with a webhook

Every customer message is POSTed to your webhook the moment it arrives.

POST/v1/webhook-endpointswebhooks:manageThe API key needs the webhooks:manage permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

Add a webhook endpoint

Or add it in **Developers → Webhooks**. The secret is returned once.

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": [
    "whatsapp"
  ],
  "events": [
    "message.received",
    "message.status"
  ]
}'
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

Answer 2xx within 10 seconds. Check the IotaBot-Signature header.

{
  "id": "evt_6a4ba40bc3f1a2b3c4d5e750",
  "object": "event",
  "type": "message.received",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T09:15:02.881Z",
  "livemode": true,
  "channel": "whatsapp",
  "website_id": "6a4b3fbbe291bce5bf701c5c",
  "data": {
    "message": {
      "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"
    },
    "conversation": {
      "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": [],
      "integration_replies": true,
      "message_count": 3,
      "created_at": "2026-10-01T09:12:44.120Z",
      "last_message_at": "2026-10-01T09:15:02.881Z"
    }
  }
}
POST/v1/messagesmessages:sendThe API key needs the messages:send permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

Reply to it

Request
curl -X POST "https://api.iotabot.com/v1/messages" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
  "text": "Thanks — checking now."
}' \
  -H "Idempotency-Key: order-1042-shipped"
Response · 202
{
  "data": {
    "id": "6a4ba0f1c3f1a2b3c4d5e733",
    "object": "message",
    "status": "queued",
    "channel": "whatsapp",
    "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7",
    "created_at": "2026-10-01T09:16:10.004Z"
  }
}
Errors
window_closedtemplate_not_approvedconversation_closedintegration_pausedrecipient_opted_outinvalid_phonefile_already_usedattachments_too_largeapi_quota_exceededidempotency_key_reusedidempotency_in_progress