{ "openapi": "3.1.0", "info": { "title": "IotaBot API", "version": "2026-10-01", "description": "One REST API over website chat, WhatsApp, Instagram and email. Guides: https://iotabot.com/docs/api" }, "servers": [ { "url": "https://api.iotabot.com/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Conversations", "description": "List and read conversations across website chat, WhatsApp, Instagram and email; close, reopen, hand to a human, assign and tag them." }, { "name": "Messages", "description": "Send messages on any channel with one endpoint — text, WhatsApp templates and marketing messages, and email with HTML and attachments — read delivery status, and check whose messaging window is open." }, { "name": "Contacts", "description": "Read, create and update the customers your workspace knows across channels, including their opt-outs." }, { "name": "Webhooks API", "description": "Manage webhook endpoints as code, re-read an event, list deliveries and replay one." }, { "name": "Channels & usage", "description": "The websites, numbers, accounts and mailboxes a key can use, and this month's API quota." }, { "name": "Sandbox", "description": "Build and test against the real API with test keys: sandbox data only, nothing ever sent, no quota — and simulated customer messages on any channel." } ], "paths": { "/channels": { "get": { "operationId": "channels", "summary": "The websites, WhatsApp numbers, Instagram accounts and email addresses this key can use", "description": "Use it to discover ids you need elsewhere — a whatsapp_account_id to start a WhatsApp conversation, or a website_id to filter conversations.", "tags": [ "Channels & usage" ], "parameters": [ { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "The websites, WhatsApp numbers, Instagram accounts and email addresses this key can use", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "websites": [ { "id": "6a4b3fbbe291bce5bf701c5c", "name": "Acme store", "domains": [ "https://acme.com" ] } ], "whatsapp": [ { "id": "6a4c01aa…", "website_id": "6a4b3fbbe291bce5bf701c5c", "phone_number": "+91 98123 45678", "name": "Acme", "status": "connected", "marketing_messages": "ONBOARDED" } ], "instagram": [ { "id": "6a4c02bb…", "website_id": "6a4b3fbbe291bce5bf701c5c", "username": "acme", "status": "connected" } ], "email": [ { "id": "support", "website_id": "6a4b3fbbe291bce5bf701c5c", "address": "support@acme.com", "forwarding_active": true } ] } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/usage": { "get": { "operationId": "usage", "summary": "API messages used this month, the limit, and when it resets", "description": "Only messages the channel accepted count. Webhooks never count.", "tags": [ "Channels & usage" ], "parameters": [ { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "API messages used this month, the limit, and when it resets", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "period": "2026-10", "messages_used": 312, "messages_limit": 1000, "resets_at": "2026-11-01T00:00:00.000Z" } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/conversations": { "get": { "operationId": "listConversations", "summary": "List conversations, newest first", "tags": [ "Conversations" ], "x-iotabot-scope": "conversations:read", "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "website, whatsapp, instagram or email", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "open or closed", "schema": { "type": "string" } }, { "name": "website_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 date — conversations with a message since then", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1–100, default 25", "schema": { "type": "string" } }, { "name": "starting_after", "in": "query", "required": false, "description": "the next_cursor of the previous page", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "List conversations, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "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" } } } } }, "400": { "description": "invalid_version, invalid_limit, invalid_cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_limit": { "summary": "limit must be between 1 and 100.", "value": { "error": { "code": "invalid_limit", "message": "limit must be between 1 and 100.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_cursor": { "summary": "starting_after is not a cursor this API returned.", "value": { "error": { "code": "invalid_cursor", "message": "starting_after is not a cursor this API returned.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope, channel_not_allowed, website_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "channel_not_allowed": { "summary": "The key is limited to other channels.", "value": { "error": { "code": "channel_not_allowed", "message": "The key is limited to other channels.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "website_not_allowed": { "summary": "The key is limited to other websites.", "value": { "error": { "code": "website_not_allowed", "message": "The key is limited to other websites.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/conversations/{id}": { "get": { "operationId": "getConversation", "summary": "One conversation with its contact and mode", "tags": [ "Conversations" ], "x-iotabot-scope": "conversations:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "One conversation with its contact and mode", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "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" } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "404": { "description": "conversation_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conversation_not_found": { "summary": "No conversation with that id that this key can see.", "value": { "error": { "code": "conversation_not_found", "message": "No conversation with that id that this key can see.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } }, "patch": { "operationId": "updateConversation", "summary": "Close, reopen, hand to a human or back to the AI, assign, tag", "description": "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.", "tags": [ "Conversations" ], "x-iotabot-scope": "conversations:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "mode": "human", "tags": [ "vip", "refund" ] } } } }, "responses": { "200": { "description": "Close, reopen, hand to a human or back to the AI, assign, tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "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" } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "404": { "description": "conversation_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conversation_not_found": { "summary": "No conversation with that id that this key can see.", "value": { "error": { "code": "conversation_not_found", "message": "No conversation with that id that this key can see.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "422": { "description": "conversation_closed, agent_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conversation_closed": { "summary": "Website chats accept messages only while open; reopen a conversation before changing its mode.", "value": { "error": { "code": "conversation_closed", "message": "Website chats accept messages only while open; reopen a conversation before changing its mode.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "agent_not_found": { "summary": "assigned_agent_id is not an active agent in this workspace.", "value": { "error": { "code": "agent_not_found", "message": "assigned_agent_id is not an active agent in this workspace.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/conversations/{id}/messages": { "get": { "operationId": "listMessages", "summary": "The thread, oldest first", "description": "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.", "tags": [ "Conversations" ], "x-iotabot-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "The thread, oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "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 } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "404": { "description": "conversation_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "conversation_not_found": { "summary": "No conversation with that id that this key can see.", "value": { "error": { "code": "conversation_not_found", "message": "No conversation with that id that this key can see.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/messages": { "post": { "operationId": "sendMessage", "summary": "Send on any channel — checked now, delivered in the background", "description": "Reply in an existing conversation with conversation_id — on an Instagram comment thread that is a public reply under the customer's latest comment, or a private DM to them with reply_as: \"dm\" — or start one: WhatsApp with channel, to (a phone number) and an approved template; email with channel, to, from (one of your verified addresses) and subject. Everything the channel would refuse is refused here with a specific code. Attach files with attachments (uploaded file_ids or inline base64, 10 MB in all): any file on email and WhatsApp, images, video and audio on Instagram. An accepted message returns 202 with status: \"queued\"; its outcome arrives as a message.status webhook and on GET /messages/{id}. Send an Idempotency-Key header so a retry never sends twice.", "tags": [ "Messages" ], "x-iotabot-scope": "messages:send", "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7", "text": "Your order #1042 shipped yesterday — it arrives Friday." } } } }, "responses": { "202": { "description": "Send on any channel — checked now, delivered in the background", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "id": "6a4ba0f1c3f1a2b3c4d5e733", "object": "message", "status": "queued", "channel": "whatsapp", "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7", "created_at": "2026-10-01T09:16:10.004Z" } } } } }, "400": { "description": "invalid_version, invalid_phone, unsupported_attachment, file_already_used, attachments_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_phone": { "summary": "Give phone numbers with their country code, e.g. +919812345678.", "value": { "error": { "code": "invalid_phone", "message": "Give phone numbers with their country code, e.g. +919812345678.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "unsupported_attachment": { "summary": "Instagram takes images, video and audio only.", "value": { "error": { "code": "unsupported_attachment", "message": "Instagram takes images, video and audio only.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "file_already_used": { "summary": "An uploaded file can be attached to one message only.", "value": { "error": { "code": "file_already_used", "message": "An uploaded file can be attached to one message only.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "attachments_too_large": { "summary": "Attachments may total 10 MB per message.", "value": { "error": { "code": "attachments_too_large", "message": "Attachments may total 10 MB per message.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "409": { "description": "integration_paused, idempotency_in_progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "integration_paused": { "summary": "An agent paused integration replies on this conversation. Stop retrying; a conversation.updated event tells you when it resumes.", "value": { "error": { "code": "integration_paused", "message": "An agent paused integration replies on this conversation. Stop retrying; a conversation.updated event tells you when it resumes.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still being processed. Retry shortly.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still being processed. Retry shortly.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "422": { "description": "window_closed, template_not_approved, conversation_closed, private_reply_expired, private_reply_used, sender_not_verified, sender_not_found, recipient_suppressed, recipient_unsubscribed, recipient_opted_out, idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "window_closed": { "summary": "More than 24 hours since the customer last wrote. On WhatsApp send an approved template; on Instagram you must wait for them to write.", "value": { "error": { "code": "window_closed", "message": "More than 24 hours since the customer last wrote. On WhatsApp send an approved template; on Instagram you must wait for them to write.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "template_not_approved": { "summary": "No approved template with that name and language on this number (GET /whatsapp/templates).", "value": { "error": { "code": "template_not_approved", "message": "No approved template with that name and language on this number (GET /whatsapp/templates).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "conversation_closed": { "summary": "Website chats accept messages only while open; reopen a conversation before changing its mode.", "value": { "error": { "code": "conversation_closed", "message": "Website chats accept messages only while open; reopen a conversation before changing its mode.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "private_reply_expired": { "summary": "Instagram allows a private reply (reply_as: \"dm\") only within 7 days of the comment. Reply publicly instead.", "value": { "error": { "code": "private_reply_expired", "message": "Instagram allows a private reply (reply_as: \"dm\") only within 7 days of the comment. Reply publicly instead.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "private_reply_used": { "summary": "The comment already has its private reply — Instagram allows one per comment. Once the customer answers, reply in their DM conversation.", "value": { "error": { "code": "private_reply_used", "message": "The comment already has its private reply — Instagram allows one per comment. Once the customer answers, reply in their DM conversation.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "sender_not_verified": { "summary": "The email domain is not verified yet, so nothing can be sent from it.", "value": { "error": { "code": "sender_not_verified", "message": "The email domain is not verified yet, so nothing can be sent from it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "sender_not_found": { "summary": "from is not one of your email addresses this key can use (GET /email/senders).", "value": { "error": { "code": "sender_not_found", "message": "from is not one of your email addresses this key can use (GET /email/senders).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "recipient_suppressed": { "summary": "An address bounced permanently or reported your email as spam, so nothing can be sent to it.", "value": { "error": { "code": "recipient_suppressed", "message": "An address bounced permanently or reported your email as spam, so nothing can be sent to it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "recipient_unsubscribed": { "summary": "The address unsubscribed: you can answer their emails, but not start a new thread.", "value": { "error": { "code": "recipient_unsubscribed", "message": "The address unsubscribed: you can answer their emails, but not start a new thread.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "recipient_opted_out": { "summary": "The customer opted out of this channel (they replied STOP, or the contact is marked opted out). Nothing can be sent to them there.", "value": { "error": { "code": "recipient_opted_out", "message": "The customer opted out of this channel (they replied STOP, or the contact is marked opted out). Nothing can be sent to them there.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "idempotency_key_reused": { "summary": "The Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited, api_quota_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "api_quota_exceeded": { "summary": "The workspace used its monthly API messages. It resets on the 1st; the plan sets the limit.", "value": { "error": { "code": "api_quota_exceeded", "message": "The workspace used its monthly API messages. It resets on the 1st; the plan sets the limit.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/messages/{id}": { "get": { "operationId": "getMessage", "summary": "One message and its delivery status", "description": "status is queued, sent, delivered, read or failed for messages you sent, and received for customer messages.", "tags": [ "Messages" ], "x-iotabot-scope": "messages:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "One message and its delivery status", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "id": "6a4ba0f1c3f1a2b3c4d5e733", "object": "message", "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7", "channel": "whatsapp", "direction": "outbound", "sender": { "type": "api", "name": "API · CRM sync" }, "type": "text", "text": "Your order #1042 shipped yesterday — it arrives Friday.", "html": null, "html_raw": null, "attachments": [], "status": "delivered", "delivery": { "status": "delivered", "at": "2026-10-01T09:16:12.410Z" }, "created_at": "2026-10-01T09:15:02.881Z" } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "404": { "description": "message_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "message_not_found": { "summary": "No message with that id that this key can see.", "value": { "error": { "code": "message_not_found", "message": "No message with that id that this key can see.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/messaging-window": { "get": { "operationId": "windowList", "summary": "Everyone you can message right now, soonest-closing window first", "description": "WhatsApp and Instagram allow a free-form message only within 24 hours of the customer's last message. This lists every WhatsApp and Instagram DM conversation whose window is open now — opted-out customers and conversations where an agent paused integration replies are left out — with window_closes_at and seconds_left, sorted so the windows closing first come first. closes_within_minutes keeps only those closing soon. Use it to reach people before their window shuts; send with POST /messages. Instagram comment threads are not listed (their private reply has its own 7-day clock — check one with POST /messaging-window/check).", "tags": [ "Messages" ], "x-iotabot-scope": "conversations:read", "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "whatsapp or instagram — both when left out", "schema": { "type": "string" } }, { "name": "closes_within_minutes", "in": "query", "required": false, "description": "1–1440: only windows closing within this many minutes", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1–100, default 25", "schema": { "type": "string" } }, { "name": "starting_after", "in": "query", "required": false, "description": "the next_cursor of the previous page", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Everyone you can message right now, soonest-closing window first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "checked_at": "2026-10-02T09:00:58.000Z", "items": [ { "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f8", "channel": "instagram", "thread": "dm", "account_id": "6a4c02bb…", "contact": { "name": "priya.styles", "phone": null, "email": null, "external_id": "17841400000000001" }, "window_closes_at": "2026-10-02T14:05:00.000Z", "seconds_left": 18342, "last_customer_message_at": "2026-10-01T14:05:00.000Z", "can_send": true, "reason": null } ], "has_more": false, "next_cursor": null } } } } }, "400": { "description": "invalid_version, invalid_limit, invalid_cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_limit": { "summary": "limit must be between 1 and 100.", "value": { "error": { "code": "invalid_limit", "message": "limit must be between 1 and 100.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_cursor": { "summary": "starting_after is not a cursor this API returned.", "value": { "error": { "code": "invalid_cursor", "message": "starting_after is not a cursor this API returned.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/messaging-window/check": { "post": { "operationId": "windowCheck", "summary": "Can these people be messaged now, and until when?", "description": "Up to 100 people in one call, each named by one of conversation_id, instagram_username, instagram_user_id or phone (WhatsApp) — mix them freely. Add instagram_account_id or whatsapp_account_id to an item to look on one of your accounts only. Each row says can_send (a free-form message would be accepted now), window_closes_at, seconds_left and, when it cannot, reason: window_closed, no_conversation (they never wrote to you), opted_out, integration_paused, ambiguous (the username or number matches on several of your accounts — matches lists them), channel_not_allowed, invalid_phone, conversation_not_found, invalid_item (not exactly one identifier), and for comment threads private_reply_used or no_comment. On WhatsApp template_allowed says whether an approved template can still go — it can at any time, window or not. On an Instagram comment thread (thread: \"comment\") the window is the private reply's: once per comment, within 7 days. Usernames are matched as IotaBot last saw them, so a renamed account may show no_conversation — instagram_user_id (from webhooks) always matches. Email and website chat have no window (window_closes_at: null). Rows come back in the order sent; one bad item never fails the rest. Checks use no API quota.", "tags": [ "Messages" ], "x-iotabot-scope": "conversations:read", "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "items": [ { "instagram_username": "priya.styles" }, { "phone": "+919812345678" }, { "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7" } ] } } } }, "responses": { "200": { "description": "Can these people be messaged now, and until when?", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "checked_at": "2026-10-02T09:00:58.000Z", "items": [ { "input": { "instagram_username": "priya.styles" }, "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f8", "channel": "instagram", "thread": "dm", "account_id": "6a4c02bb…", "contact": { "name": "priya.styles", "phone": null, "email": null, "external_id": "17841400000000001" }, "window_closes_at": "2026-10-02T14:05:00.000Z", "seconds_left": 18342, "last_customer_message_at": "2026-10-01T14:05:00.000Z", "can_send": true, "reason": null }, { "input": { "phone": "+919812345678" }, "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7", "channel": "whatsapp", "account_id": "6a4c01aa…", "contact": { "name": "Priya Sharma", "phone": "+919812345678", "email": null, "external_id": "919812345678" }, "window_closes_at": null, "seconds_left": 0, "last_customer_message_at": "2026-09-28T09:15:02.881Z", "can_send": false, "reason": "window_closed", "template_allowed": true }, { "input": { "instagram_username": "arjun.k" }, "conversation_id": null, "channel": "instagram", "can_send": false, "window_closes_at": null, "seconds_left": null, "last_customer_message_at": null, "reason": "no_conversation" } ] } } } } }, "400": { "description": "invalid_version, invalid_request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_request": { "summary": "The body or parameters do not make sense together — the message says which.", "value": { "error": { "code": "invalid_request", "message": "The body or parameters do not make sense together — the message says which.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/whatsapp/marketing-messages": { "post": { "operationId": "waMarketing", "summary": "Send a WhatsApp marketing template through Meta's Marketing Messages API", "description": "For promotions, offers and announcements: an approved MARKETING template (see GET /whatsapp/templates — category), to a phone number with to or in an existing WhatsApp conversation with conversation_id. Meta delivers it through its Marketing Messages API, with delivery optimised for marketing — the same route IotaBot campaigns use. A number not yet onboarded to it (marketing_messages on GET /channels) still sends: Meta falls back to the Cloud API. Utility and authentication templates are refused with template_not_marketing; send those with POST /messages. Everything else is as POST /messages: checked now, 202 with status: \"queued\", the outcome as a message.status webhook and on GET /messages/{id}, and an Idempotency-Key header makes retries safe.", "tags": [ "Messages" ], "x-iotabot-scope": "messages:send", "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "to": "+919812345678", "whatsapp_account_id": "6a4c01aa…", "template": { "name": "festive_offer", "language": "en_US", "parameters": [ "Priya" ] } } } } }, "responses": { "202": { "description": "Send a WhatsApp marketing template through Meta's Marketing Messages API", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "id": "6a4ba0f1c3f1a2b3c4d5e735", "object": "message", "status": "queued", "channel": "whatsapp", "via": "marketing_messages", "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7", "created_at": "2026-10-01T09:16:10.004Z" } } } } }, "400": { "description": "invalid_version, invalid_phone, whatsapp_account_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_phone": { "summary": "Give phone numbers with their country code, e.g. +919812345678.", "value": { "error": { "code": "invalid_phone", "message": "Give phone numbers with their country code, e.g. +919812345678.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "whatsapp_account_required": { "summary": "The key reaches several WhatsApp numbers — say which with whatsapp_account_id.", "value": { "error": { "code": "whatsapp_account_required", "message": "The key reaches several WhatsApp numbers — say which with whatsapp_account_id.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "409": { "description": "integration_paused, idempotency_in_progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "integration_paused": { "summary": "An agent paused integration replies on this conversation. Stop retrying; a conversation.updated event tells you when it resumes.", "value": { "error": { "code": "integration_paused", "message": "An agent paused integration replies on this conversation. Stop retrying; a conversation.updated event tells you when it resumes.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "idempotency_in_progress": { "summary": "A request with this Idempotency-Key is still being processed. Retry shortly.", "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still being processed. Retry shortly.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "422": { "description": "template_not_marketing, template_not_approved, recipient_opted_out, no_whatsapp_account, idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "template_not_marketing": { "summary": "POST /whatsapp/marketing-messages sends MARKETING templates only. Send utility and authentication templates with POST /messages.", "value": { "error": { "code": "template_not_marketing", "message": "POST /whatsapp/marketing-messages sends MARKETING templates only. Send utility and authentication templates with POST /messages.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "template_not_approved": { "summary": "No approved template with that name and language on this number (GET /whatsapp/templates).", "value": { "error": { "code": "template_not_approved", "message": "No approved template with that name and language on this number (GET /whatsapp/templates).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "recipient_opted_out": { "summary": "The customer opted out of this channel (they replied STOP, or the contact is marked opted out). Nothing can be sent to them there.", "value": { "error": { "code": "recipient_opted_out", "message": "The customer opted out of this channel (they replied STOP, or the contact is marked opted out). Nothing can be sent to them there.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "no_whatsapp_account": { "summary": "This key cannot reach any connected WhatsApp number.", "value": { "error": { "code": "no_whatsapp_account", "message": "This key cannot reach any connected WhatsApp number.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "idempotency_key_reused": { "summary": "The Idempotency-Key was already used with a different request.", "value": { "error": { "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited, api_quota_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "api_quota_exceeded": { "summary": "The workspace used its monthly API messages. It resets on the 1st; the plan sets the limit.", "value": { "error": { "code": "api_quota_exceeded", "message": "The workspace used its monthly API messages. It resets on the 1st; the plan sets the limit.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/whatsapp/templates": { "get": { "operationId": "waTemplates", "summary": "Approved WhatsApp templates you can send", "tags": [ "Messages" ], "x-iotabot-scope": "messages:send", "parameters": [ { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Approved WhatsApp templates you can send", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "items": [ { "name": "order_update", "language": "en_US", "category": "UTILITY", "whatsapp_account_id": "6a4c01aa…", "inputs": { "body": [ "order number", "delivery date" ] } }, { "name": "festive_offer", "language": "en_US", "category": "MARKETING", "whatsapp_account_id": "6a4c01aa…", "inputs": { "body": [ "customer name" ] } } ] } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/email/senders": { "get": { "operationId": "emailSenders", "summary": "Email addresses you can send from", "tags": [ "Messages" ], "x-iotabot-scope": "messages:send", "parameters": [ { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Email addresses you can send from", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "items": [ { "address": "support@acme.com", "website_id": "6a4b3fbbe291bce5bf701c5c", "domain": "acme.com", "can_send": true } ] } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/files": { "post": { "operationId": "uploadFile", "summary": "Upload an attachment (base64, up to 10 MB) and use its id in POST /messages", "tags": [ "Messages" ], "x-iotabot-scope": "messages:send", "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "filename": "invoice.pdf", "content_type": "application/pdf", "content_base64": "JVBERi0xLjQK…" } } } }, "responses": { "201": { "description": "Upload an attachment (base64, up to 10 MB) and use its id in POST /messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "id": "6a4ba1c0c3f1a2b3c4d5e741", "object": "file", "filename": "invoice.pdf", "content_type": "application/pdf", "size": 48213, "created_at": "2026-10-01T09:17:00.000Z" } } } } }, "400": { "description": "invalid_version, file_rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "file_rejected": { "summary": "The file type is not allowed, the file is empty, or it is over 10 MB.", "value": { "error": { "code": "file_rejected", "message": "The file type is not allowed, the file is empty, or it is over 10 MB.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "Contacts across channels, newest first", "description": "Contacts belong to the whole workspace, so keys limited to some websites cannot use them.", "tags": [ "Contacts" ], "x-iotabot-scope": "contacts:read", "parameters": [ { "name": "email", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Contacts across channels, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "items": [ { "id": "6a4b9e00c3f1a2b3c4d5e600", "object": "contact", "name": "Priya Sharma", "email": "priya@example.com", "phone": "+919812345678", "instagram_user_id": null, "opt_outs": { "whatsapp": false, "email": false, "instagram": false }, "email_suppressed": null, "first_seen_channel": "whatsapp", "source": "captured", "created_at": "2026-09-12T10:00:00.000Z", "last_seen_at": "2026-10-01T09:15:02.881Z" } ], "has_more": false, "next_cursor": null } } } } }, "400": { "description": "invalid_version, invalid_phone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_phone": { "summary": "Give phone numbers with their country code, e.g. +919812345678.", "value": { "error": { "code": "invalid_phone", "message": "Give phone numbers with their country code, e.g. +919812345678.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope, contacts_need_all_websites", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "contacts_need_all_websites": { "summary": "Contacts belong to the whole workspace; use a key that is not limited to some websites.", "value": { "error": { "code": "contacts_need_all_websites", "message": "Contacts belong to the whole workspace; use a key that is not limited to some websites.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } }, "post": { "operationId": "createContact", "summary": "Create a contact (email or phone)", "tags": [ "Contacts" ], "x-iotabot-scope": "contacts:write", "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "Priya Sharma", "email": "priya@example.com", "phone": "+919812345678" } } } }, "responses": { "201": { "description": "Create a contact (email or phone)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "invalid_version, invalid_phone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "invalid_phone": { "summary": "Give phone numbers with their country code, e.g. +919812345678.", "value": { "error": { "code": "invalid_phone", "message": "Give phone numbers with their country code, e.g. +919812345678.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "409": { "description": "contact_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contact_exists": { "summary": "Another contact already has this email or phone; the message includes its id.", "value": { "error": { "code": "contact_exists", "message": "Another contact already has this email or phone; the message includes its id.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/contacts/{id}": { "get": { "operationId": "getContact", "summary": "One contact", "tags": [ "Contacts" ], "x-iotabot-scope": "contacts:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "One contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "404": { "description": "contact_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contact_not_found": { "summary": "No contact with that id.", "value": { "error": { "code": "contact_not_found", "message": "No contact with that id.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } }, "patch": { "operationId": "updateContact", "summary": "Update a contact or its opt-outs", "tags": [ "Contacts" ], "x-iotabot-scope": "contacts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "Priya S.", "whatsapp_opt_out": true } } } }, "responses": { "200": { "description": "Update a contact or its opt-outs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "404": { "description": "contact_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contact_not_found": { "summary": "No contact with that id.", "value": { "error": { "code": "contact_not_found", "message": "No contact with that id.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "409": { "description": "contact_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contact_exists": { "summary": "Another contact already has this email or phone; the message includes its id.", "value": { "error": { "code": "contact_exists", "message": "Another contact already has this email or phone; the message includes its id.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/webhook-endpoints": { "get": { "operationId": "listEndpoints", "summary": "Your webhook endpoints, and the IP addresses webhooks come from", "tags": [ "Webhooks API" ], "x-iotabot-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Your webhook endpoints, and the IP addresses webhooks come from", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "items": [ { "id": "6a4bb0…", "object": "webhook_endpoint", "url": "https://crm.acme.com/iotabot", "description": "CRM", "channels": [ "whatsapp" ], "events": [ "message.received" ], "website_ids": [], "metadata_only": false, "test_events": false, "status": "active", "verified_at": "2026-10-01T09:00:00.000Z", "created_at": "2026-10-01T09:00:00.000Z" } ], "egress_ips": [ "16.16.181.103" ] } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } }, "post": { "operationId": "createEndpoint", "summary": "Add an endpoint — verified straight away; the signing secret is returned once", "description": "The URL must answer the endpoint.verification event before it receives anything. metadataOnly: true sends ids and status without content or customer details; testEvents: true also sends sandbox events.", "tags": [ "Webhooks API" ], "x-iotabot-scope": "webhooks:manage", "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "url": "https://crm.acme.com/iotabot", "description": "CRM", "channels": [ "whatsapp", "email" ], "events": [ "message.received", "message.status" ], "metadataOnly": false, "testEvents": false } } } }, "responses": { "201": { "description": "Add an endpoint — verified straight away; the signing secret is returned once", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "id": "6a4bb0…", "object": "webhook_endpoint", "url": "https://crm.acme.com/iotabot", "status": "active", "secret": "whsec_…", "verification": { "verified": true, "reason": null } } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/webhook-endpoints/{id}": { "patch": { "operationId": "updateEndpoint", "summary": "Change URL (re-verifies), events, channels, websites or switch it on or off", "tags": [ "Webhooks API" ], "x-iotabot-scope": "webhooks:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "events": [ "message.received", "message.sent" ], "enabled": true } } } }, "responses": { "200": { "description": "Change URL (re-verifies), events, channels, websites or switch it on or off", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } }, "delete": { "operationId": "deleteEndpoint", "summary": "Delete an endpoint — deliveries still retrying are dropped", "tags": [ "Webhooks API" ], "x-iotabot-scope": "webhooks:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Delete an endpoint — deliveries still retrying are dropped", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "id": "6a4bb0…", "deleted": true } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/webhook-endpoints/{id}/roll-secret": { "post": { "operationId": "rollEndpointSecret", "summary": "New signing secret; the old one keeps co-signing for grace_hours (0–168)", "tags": [ "Webhooks API" ], "x-iotabot-scope": "webhooks:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "grace_hours": 24 } } } }, "responses": { "200": { "description": "New signing secret; the old one keeps co-signing for grace_hours (0–168)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/test/inbound": { "post": { "operationId": "simulateInbound", "summary": "A customer message on any channel, as if it had just arrived (test keys only)", "description": "Use a test key (ib_test_…). Add comment: true on Instagram to simulate a comment instead of a DM. The message lands in a sandbox conversation — the same from continues it — and produces the same webhooks a real one would, marked livemode: false, for endpoints with test events on. Reply to it with POST /messages and the same test key.", "tags": [ "Sandbox" ], "parameters": [ { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "channel": "whatsapp", "from": "+15550000001", "name": "Priya Sharma", "text": "Hi, where is my order #1042?" } } } }, "responses": { "201": { "description": "A customer message on any channel, as if it had just arrived (test keys only)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "livemode": false, "conversation": { "id": "6a4bc1…", "object": "conversation", "channel": "whatsapp", "status": "open", "mode": "ai" }, "message": { "id": "6a4bc2…", "object": "message", "direction": "inbound", "text": "Hi, where is my order #1042?", "status": "received" } } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope, test_key_required, channel_not_allowed, website_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "test_key_required": { "summary": "Simulated messages need a test key (ib_test_…).", "value": { "error": { "code": "test_key_required", "message": "Simulated messages need a test key (ib_test_…).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "channel_not_allowed": { "summary": "The key is limited to other channels.", "value": { "error": { "code": "channel_not_allowed", "message": "The key is limited to other channels.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "website_not_allowed": { "summary": "The key is limited to other websites.", "value": { "error": { "code": "website_not_allowed", "message": "The key is limited to other websites.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/events/{id}": { "get": { "operationId": "getEvent", "summary": "Re-read a webhook event — the same envelope your endpoint received", "tags": [ "Webhooks API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "evt_…", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Re-read a webhook event — the same envelope your endpoint received", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/webhook-deliveries": { "get": { "operationId": "listDeliveries", "summary": "Webhook delivery log, newest first", "tags": [ "Webhooks API" ], "x-iotabot-scope": "webhooks:manage", "parameters": [ { "name": "endpoint_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "pending, retrying, succeeded, failed", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" } ], "responses": { "200": { "description": "Webhook delivery log, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } }, "example": { "data": { "items": [ { "id": "whd_6a4ba2…", "object": "webhook_delivery", "endpoint_id": "6a4ba3…", "event_id": "evt_6a4ba4…", "event_type": "message.received", "status": "succeeded", "attempts": 1, "last_response_status": 200, "last_error": null, "next_attempt_at": null, "replay_of": null, "created_at": "2026-10-01T09:15:03.100Z" } ], "has_more": false, "next_cursor": null } } } } }, "400": { "description": "invalid_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } }, "/webhook-deliveries/{id}/replay": { "post": { "operationId": "replayDelivery", "summary": "Send a delivery's event to its endpoint again", "tags": [ "Webhooks API" ], "x-iotabot-scope": "webhooks:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "whd_…", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Version" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Send a delivery's event to its endpoint again", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "description": "invalid_version, endpoint_disabled, event_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_version": { "summary": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "value": { "error": { "code": "invalid_version", "message": "The IotaBot-Version header names a version the API does not serve. Leave it out to use the key's own version.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "endpoint_disabled": { "summary": "The webhook endpoint is off or deleted, so it cannot be replayed to.", "value": { "error": { "code": "endpoint_disabled", "message": "The webhook endpoint is off or deleted, so it cannot be replayed to.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "event_expired": { "summary": "The event is past your log retention period.", "value": { "error": { "code": "event_expired", "message": "The event is past your log retention period.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "401": { "description": "invalid_api_key, key_revoked, key_expired, key_rolled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "value": { "error": { "code": "invalid_api_key", "message": "The key is missing, malformed or unknown. Send it as Authorization: Bearer ib_live_….", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_revoked": { "summary": "The key was revoked. Create a new one.", "value": { "error": { "code": "key_revoked", "message": "The key was revoked. Create a new one.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_expired": { "summary": "The key passed its expiry date. Roll or replace it.", "value": { "error": { "code": "key_expired", "message": "The key passed its expiry date. Roll or replace it.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "key_rolled": { "summary": "This is a rolled-away secret whose grace period ended. Use the new secret.", "value": { "error": { "code": "key_rolled", "message": "This is a rolled-away secret whose grace period ended. Use the new secret.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "403": { "description": "account_inactive, ip_not_allowed, insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_inactive": { "summary": "The workspace is suspended or closed.", "value": { "error": { "code": "account_inactive", "message": "The workspace is suspended or closed.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "ip_not_allowed": { "summary": "The request came from an address outside the key's IP allowlist.", "value": { "error": { "code": "ip_not_allowed", "message": "The request came from an address outside the key's IP allowlist.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } }, "insufficient_scope": { "summary": "The key lacks the permission this endpoint needs (shown on each endpoint).", "value": { "error": { "code": "insufficient_scope", "message": "The key lacks the permission this endpoint needs (shown on each endpoint).", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "value": { "error": { "code": "rate_limited", "message": "Over the key's rate limit (20 a second and 300 a minute on paid plans). Wait for Retry-After seconds.", "request_id": "0f6047d9-bf3d-4ca7-adac-33011910b01d" } } } } } } } } } } }, "webhooks": { "message.received": { "post": { "operationId": "onMessageReceived", "summary": "A visitor or customer sent a message.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "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" } } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "message.sent": { "post": { "operationId": "onMessageSent", "summary": "The bot, an agent or the API sent a message.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "message.sent", "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": "outbound", "sender": { "type": "ai", "name": null }, "type": "text", "text": "It shipped yesterday and arrives Friday.", "html": null, "html_raw": null, "attachments": [], "status": "sent", "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" } } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "message.status": { "post": { "operationId": "onMessageStatus", "summary": "A sent message was delivered, read or failed (with the reason).", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "message.status", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "whatsapp", "website_id": "6a4b3fbbe291bce5bf701c5c", "data": { "message_id": "6a4ba0f1c3f1a2b3c4d5e733", "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7", "status": "delivered", "error": null } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "conversation.created": { "post": { "operationId": "onConversationCreated", "summary": "A new conversation started.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "conversation.created", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "whatsapp", "website_id": "6a4b3fbbe291bce5bf701c5c", "data": { "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" } } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "conversation.assigned": { "post": { "operationId": "onConversationAssigned", "summary": "A conversation was assigned to an agent.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "conversation.assigned", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "whatsapp", "website_id": "6a4b3fbbe291bce5bf701c5c", "data": { "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": "6a4b1e…", "tags": [], "integration_replies": true, "message_count": 3, "created_at": "2026-10-01T09:12:44.120Z", "last_message_at": "2026-10-01T09:15:02.881Z" }, "changed": [ "assignedAgentId" ], "agent_id": "6a4b1e…" } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "conversation.handoff_requested": { "post": { "operationId": "onConversationHandoff_requested", "summary": "The bot handed the conversation to a human.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "conversation.handoff_requested", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "whatsapp", "website_id": "6a4b3fbbe291bce5bf701c5c", "data": { "conversation": { "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": [], "integration_replies": true, "message_count": 3, "created_at": "2026-10-01T09:12:44.120Z", "last_message_at": "2026-10-01T09:15:02.881Z" }, "changed": [ "mode", "handoff.requestedAt" ], "reason": "Customer asked for a person" } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "conversation.updated": { "post": { "operationId": "onConversationUpdated", "summary": "Mode, tags or status changed, or an agent paused or resumed integration replies.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "conversation.updated", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "whatsapp", "website_id": "6a4b3fbbe291bce5bf701c5c", "data": { "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": false, "message_count": 3, "created_at": "2026-10-01T09:12:44.120Z", "last_message_at": "2026-10-01T09:15:02.881Z" }, "changed": [ "integrationRepliesPaused" ] } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "conversation.closed": { "post": { "operationId": "onConversationClosed", "summary": "A conversation was closed.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "conversation.closed", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "whatsapp", "website_id": "6a4b3fbbe291bce5bf701c5c", "data": { "conversation": { "id": "6a4b9e21c3f1a2b3c4d5e6f7", "object": "conversation", "channel": "whatsapp", "website_id": "6a4b3fbbe291bce5bf701c5c", "status": "closed", "mode": "closed", "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" }, "changed": [ "status", "mode", "closedAt" ] } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "contact.updated": { "post": { "operationId": "onContactUpdated", "summary": "Visitor details were collected or identified.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "contact.updated", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "whatsapp", "website_id": "6a4b3fbbe291bce5bf701c5c", "data": { "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" }, "changed": [ "visitor.email" ], "contact": { "name": "Priya Sharma", "email": "priya@example.com", "phone": "+919812345678", "external_id": "919812345678" } } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "contact.deleted": { "post": { "operationId": "onContactDeleted", "summary": "A contact was deleted from the workspace. Sent to every endpoint subscribed to it, whatever its channels; forget the contact in your system.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "contact.deleted", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "all", "website_id": null, "data": { "contact": { "id": "6a4b9e00c3f1a2b3c4d5e600" } } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "form.submitted": { "post": { "operationId": "onFormSubmitted", "summary": "A website form was submitted. Fields marked sensitive arrive as \"[redacted]\".", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "id": "evt_6a4ba40bc3f1a2b3c4d5e750", "object": "event", "type": "form.submitted", "api_version": "2026-10-01", "created_at": "2026-10-01T09:15:02.881Z", "livemode": true, "channel": "website", "website_id": "6a4b3fbbe291bce5bf701c5c", "data": { "submission_id": "fs_9x2…", "conversation_id": "6a4b9e21c3f1a2b3c4d5e6f7", "form": { "id": "6a4b77…", "name": "Book a demo", "slug": "book-a-demo" }, "fields": { "name": "Priya Sharma", "email": "priya@example.com" }, "submitted_at": "2026-10-01T09:20:00.000Z" } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } }, "comment.received": { "post": { "operationId": "onCommentReceived", "summary": "A comment landed on an Instagram post.", "parameters": [ { "name": "IotaBot-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" } ], "requestBody": { "content": { "application/json": { "example": { "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": "+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" } } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds is success" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key: ib_live_… or ib_test_… (sandbox)" } }, "parameters": { "Version": { "name": "IotaBot-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-10-01" }, "description": "Use this API version for the request instead of the key's own. Echoed on every response." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "A retry with the same key and body returns the first result instead of acting twice. Kept 24 hours." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "key_revoked", "key_expired", "key_rolled", "test_key_required", "step_up_required", "plan_upgrade_required", "account_inactive", "ip_not_allowed", "insufficient_scope", "channel_not_allowed", "website_not_allowed", "contacts_need_all_websites", "invalid_request", "invalid_version", "invalid_limit", "invalid_cursor", "invalid_phone", "text_required", "from_required", "subject_required", "invalid_email", "whatsapp_account_required", "invalid_attachment", "file_not_found", "invalid_idempotency_key", "file_rejected", "unsupported_attachment", "file_already_used", "attachments_too_large", "conversation_not_found", "message_not_found", "contact_not_found", "integration_paused", "contact_exists", "idempotency_in_progress", "window_closed", "no_whatsapp_account", "endpoint_disabled", "event_expired", "template_not_approved", "template_not_marketing", "conversation_closed", "sender_not_verified", "sender_not_found", "recipient_suppressed", "recipient_unsubscribed", "private_reply_expired", "private_reply_used", "recipient_opted_out", "no_recipient", "agent_not_found", "idempotency_key_reused", "rate_limited", "api_quota_exceeded" ] }, "message": { "type": "string" }, "details": { "type": "array", "items": {} }, "request_id": { "type": "string", "description": "Also in the X-Request-Id header. Quote it when contacting support." } } } } } } } }