{ "asyncapi": "3.1.0", "info": { "title": "OpenWA events", "version": "5.6.0", "description": "Initial public wire contracts for six runtime events. This is not an exhaustive list of internal lifecycle events. SSE and webhook policies differ; MCP provides compact summaries for three events." }, "servers": { "easyApi": { "host": "localhost:8080", "protocol": "http", "security": [ { "$ref": "#/components/securitySchemes/apiKey" } ] } }, "channels": { "sse_ack_changed": { "address": "/api/events", "description": "SSE event frame: id, event and JSON data; optional topics query filters exact runtime names. Keepalive every 20 seconds; reconnect hint 3000 ms. No history replay. API key in X-API-Key or api_key/key query.", "messages": { "event": { "$ref": "#/components/messages/sse_ack_changed" } }, "x-openwa-transport": "sse", "servers": [ { "$ref": "#/servers/easyApi" } ], "x-openwa-sse": { "event": "ack.changed", "contentType": "text/event-stream", "topics": "ack.changed" } }, "webhook_ack_changed": { "address": null, "description": "Outbound HTTP POST to the configured destination. Public non-sensitive events pass through the plugin gateway. Optional event-name filter; default 3 retries with exponential delay from 1000 ms. Optional durable journal adds Idempotency-Key and retries pending deliveries after restart. No exactly-once guarantee.", "messages": { "event": { "$ref": "#/components/messages/webhook_ack_changed" } }, "x-openwa-transport": "webhook" }, "mcp_ack_changed": { "address": null, "description": "Verified subscriber-provided HTTPS callback. Subscribe through /mcp using MCP 2026-07-28. Standard Webhooks signatures, stable event IDs and bounded transient retries. No retry on 410/413; cursor:null means no historical replay.", "messages": { "event": { "$ref": "#/components/messages/mcp_ack_changed" } }, "x-openwa-transport": "mcp", "x-openwa-subscription-schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "chatId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "sse_group_addedToGroup": { "address": "/api/events", "description": "SSE event frame: id, event and JSON data; optional topics query filters exact runtime names. Keepalive every 20 seconds; reconnect hint 3000 ms. No history replay. API key in X-API-Key or api_key/key query.", "messages": { "event": { "$ref": "#/components/messages/sse_group_addedToGroup" } }, "x-openwa-transport": "sse", "servers": [ { "$ref": "#/servers/easyApi" } ], "x-openwa-sse": { "event": "group.addedToGroup", "contentType": "text/event-stream", "topics": "group.addedToGroup" } }, "webhook_group_addedToGroup": { "address": null, "description": "Outbound HTTP POST to the configured destination. Public non-sensitive events pass through the plugin gateway. Optional event-name filter; default 3 retries with exponential delay from 1000 ms. Optional durable journal adds Idempotency-Key and retries pending deliveries after restart. No exactly-once guarantee.", "messages": { "event": { "$ref": "#/components/messages/webhook_group_addedToGroup" } }, "x-openwa-transport": "webhook" }, "sse_message_any": { "address": "/api/events", "description": "SSE event frame: id, event and JSON data; optional topics query filters exact runtime names. Keepalive every 20 seconds; reconnect hint 3000 ms. No history replay. API key in X-API-Key or api_key/key query.", "messages": { "event": { "$ref": "#/components/messages/sse_message_any" } }, "x-openwa-transport": "sse", "servers": [ { "$ref": "#/servers/easyApi" } ], "x-openwa-sse": { "event": "message.any", "contentType": "text/event-stream", "topics": "message.any" } }, "webhook_message_any": { "address": null, "description": "Outbound HTTP POST to the configured destination. Public non-sensitive events pass through the plugin gateway. Optional event-name filter; default 3 retries with exponential delay from 1000 ms. Optional durable journal adds Idempotency-Key and retries pending deliveries after restart. No exactly-once guarantee.", "messages": { "event": { "$ref": "#/components/messages/webhook_message_any" } }, "x-openwa-transport": "webhook" }, "sse_message_received": { "address": "/api/events", "description": "SSE event frame: id, event and JSON data; optional topics query filters exact runtime names. Keepalive every 20 seconds; reconnect hint 3000 ms. No history replay. API key in X-API-Key or api_key/key query.", "messages": { "event": { "$ref": "#/components/messages/sse_message_received" } }, "x-openwa-transport": "sse", "servers": [ { "$ref": "#/servers/easyApi" } ], "x-openwa-sse": { "event": "message.received", "contentType": "text/event-stream", "topics": "message.received" } }, "webhook_message_received": { "address": null, "description": "Outbound HTTP POST to the configured destination. Public non-sensitive events pass through the plugin gateway. Optional event-name filter; default 3 retries with exponential delay from 1000 ms. Optional durable journal adds Idempotency-Key and retries pending deliveries after restart. No exactly-once guarantee.", "messages": { "event": { "$ref": "#/components/messages/webhook_message_received" } }, "x-openwa-transport": "webhook" }, "mcp_message_received": { "address": null, "description": "Verified subscriber-provided HTTPS callback. Subscribe through /mcp using MCP 2026-07-28. Standard Webhooks signatures, stable event IDs and bounded transient retries. No retry on 410/413; cursor:null means no historical replay.", "messages": { "event": { "$ref": "#/components/messages/mcp_message_received" } }, "x-openwa-transport": "mcp", "x-openwa-subscription-schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "chatId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "sse_session_logout": { "address": "/api/events", "description": "SSE event frame: id, event and JSON data; optional topics query filters exact runtime names. Keepalive every 20 seconds; reconnect hint 3000 ms. No history replay. API key in X-API-Key or api_key/key query.", "messages": { "event": { "$ref": "#/components/messages/sse_session_logout" } }, "x-openwa-transport": "sse", "servers": [ { "$ref": "#/servers/easyApi" } ], "x-openwa-sse": { "event": "session.logout", "contentType": "text/event-stream", "topics": "session.logout" } }, "webhook_session_logout": { "address": null, "description": "Outbound HTTP POST to the configured destination. Public non-sensitive events pass through the plugin gateway. Optional event-name filter; default 3 retries with exponential delay from 1000 ms. Optional durable journal adds Idempotency-Key and retries pending deliveries after restart. No exactly-once guarantee.", "messages": { "event": { "$ref": "#/components/messages/webhook_session_logout" } }, "x-openwa-transport": "webhook" }, "sse_session_state_changed": { "address": "/api/events", "description": "SSE event frame: id, event and JSON data; optional topics query filters exact runtime names. Keepalive every 20 seconds; reconnect hint 3000 ms. No history replay. API key in X-API-Key or api_key/key query.", "messages": { "event": { "$ref": "#/components/messages/sse_session_state_changed" } }, "x-openwa-transport": "sse", "servers": [ { "$ref": "#/servers/easyApi" } ], "x-openwa-sse": { "event": "session.state.changed", "contentType": "text/event-stream", "topics": "session.state.changed" } }, "webhook_session_state_changed": { "address": null, "description": "Outbound HTTP POST to the configured destination. Public non-sensitive events pass through the plugin gateway. Optional event-name filter; default 3 retries with exponential delay from 1000 ms. Optional durable journal adds Idempotency-Key and retries pending deliveries after restart. No exactly-once guarantee.", "messages": { "event": { "$ref": "#/components/messages/webhook_session_state_changed" } }, "x-openwa-transport": "webhook" }, "mcp_session_state_changed": { "address": null, "description": "Verified subscriber-provided HTTPS callback. Subscribe through /mcp using MCP 2026-07-28. Standard Webhooks signatures, stable event IDs and bounded transient retries. No retry on 410/413; cursor:null means no historical replay.", "messages": { "event": { "$ref": "#/components/messages/mcp_session_state_changed" } }, "x-openwa-transport": "mcp", "x-openwa-subscription-schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": {}, "additionalProperties": false } } }, "operations": { "sse_ack_changed": { "action": "send", "channel": { "$ref": "#/channels/sse_ack_changed" }, "summary": "ack.changed over sse", "messages": [ { "$ref": "#/channels/sse_ack_changed/messages/event" } ] }, "webhook_ack_changed": { "action": "send", "channel": { "$ref": "#/channels/webhook_ack_changed" }, "summary": "ack.changed over webhook", "messages": [ { "$ref": "#/channels/webhook_ack_changed/messages/event" } ] }, "mcp_ack_changed": { "action": "send", "channel": { "$ref": "#/channels/mcp_ack_changed" }, "summary": "ack.changed over mcp", "messages": [ { "$ref": "#/channels/mcp_ack_changed/messages/event" } ] }, "sse_group_addedToGroup": { "action": "send", "channel": { "$ref": "#/channels/sse_group_addedToGroup" }, "summary": "group.addedToGroup over sse", "messages": [ { "$ref": "#/channels/sse_group_addedToGroup/messages/event" } ] }, "webhook_group_addedToGroup": { "action": "send", "channel": { "$ref": "#/channels/webhook_group_addedToGroup" }, "summary": "group.addedToGroup over webhook", "messages": [ { "$ref": "#/channels/webhook_group_addedToGroup/messages/event" } ] }, "sse_message_any": { "action": "send", "channel": { "$ref": "#/channels/sse_message_any" }, "summary": "message.any over sse", "messages": [ { "$ref": "#/channels/sse_message_any/messages/event" } ] }, "webhook_message_any": { "action": "send", "channel": { "$ref": "#/channels/webhook_message_any" }, "summary": "message.any over webhook", "messages": [ { "$ref": "#/channels/webhook_message_any/messages/event" } ] }, "sse_message_received": { "action": "send", "channel": { "$ref": "#/channels/sse_message_received" }, "summary": "message.received over sse", "messages": [ { "$ref": "#/channels/sse_message_received/messages/event" } ] }, "webhook_message_received": { "action": "send", "channel": { "$ref": "#/channels/webhook_message_received" }, "summary": "message.received over webhook", "messages": [ { "$ref": "#/channels/webhook_message_received/messages/event" } ] }, "mcp_message_received": { "action": "send", "channel": { "$ref": "#/channels/mcp_message_received" }, "summary": "message.received over mcp", "messages": [ { "$ref": "#/channels/mcp_message_received/messages/event" } ] }, "sse_session_logout": { "action": "send", "channel": { "$ref": "#/channels/sse_session_logout" }, "summary": "session.logout over sse", "messages": [ { "$ref": "#/channels/sse_session_logout/messages/event" } ] }, "webhook_session_logout": { "action": "send", "channel": { "$ref": "#/channels/webhook_session_logout" }, "summary": "session.logout over webhook", "messages": [ { "$ref": "#/channels/webhook_session_logout/messages/event" } ] }, "sse_session_state_changed": { "action": "send", "channel": { "$ref": "#/channels/sse_session_state_changed" }, "summary": "session.state.changed over sse", "messages": [ { "$ref": "#/channels/sse_session_state_changed/messages/event" } ] }, "webhook_session_state_changed": { "action": "send", "channel": { "$ref": "#/channels/webhook_session_state_changed" }, "summary": "session.state.changed over webhook", "messages": [ { "$ref": "#/channels/webhook_session_state_changed/messages/event" } ] }, "mcp_session_state_changed": { "action": "send", "channel": { "$ref": "#/channels/mcp_session_state_changed" }, "summary": "session.state.changed over mcp", "messages": [ { "$ref": "#/channels/mcp_session_state_changed/messages/event" } ] } }, "components": { "schemas": { "ack_changed": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "ctx": { "type": "object", "properties": { "correlationId": { "type": "string" }, "ts": { "type": "number" }, "attempt": { "type": "number" } }, "required": [ "correlationId", "ts" ], "additionalProperties": false }, "ack": { "type": "object", "properties": { "id": { "type": "string", "description": "Message identifier returned by a send method or message event." }, "ack": { "type": "number", "enum": [ -1, 0, 1, 2, 3, 4 ] } }, "required": [ "id", "ack" ], "additionalProperties": {} } }, "required": [ "ctx", "ack" ], "additionalProperties": false }, "ack_changed_mcp": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "sessionId": { "type": "string" }, "messageId": { "type": "string" }, "ack": { "type": "number" }, "chatId": { "type": "string" } }, "required": [ "sessionId", "messageId", "ack" ], "additionalProperties": false }, "group_addedToGroup": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "ctx": { "type": "object", "properties": { "correlationId": { "type": "string" }, "ts": { "type": "number" }, "attempt": { "type": "number" } }, "required": [ "correlationId", "ts" ], "additionalProperties": false }, "groupId": { "type": "string" }, "by": { "type": "string" } }, "required": [ "ctx", "groupId" ], "additionalProperties": false }, "message_any": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "ctx": { "type": "object", "properties": { "correlationId": { "type": "string" }, "ts": { "type": "number" }, "attempt": { "type": "number" } }, "required": [ "correlationId", "ts" ], "additionalProperties": false }, "message": { "type": "object", "properties": { "id": { "type": "string", "description": "Message identifier returned by a send method or message event." }, "body": { "type": "string" }, "type": { "type": "string", "enum": [ "chat", "audio", "ptt", "image", "video", "album", "event_creation", "event_response", "document", "sticker", "location", "vcard", "multi_vcard", "revoked", "order", "buttons_response", "list_response", "unknown" ] }, "t": { "type": "number" }, "notifyName": { "type": "string" }, "from": { "type": "string", "description": "Opaque conversation identifier. Use the exact value returned by a message event or chat lookup." }, "to": { "type": "string", "description": "Opaque conversation identifier. Use the exact value returned by a message event or chat lookup." }, "self": { "type": "string", "enum": [ "in", "out" ] }, "ack": { "type": "number", "enum": [ -1, 0, 1, 2, 3, 4 ] }, "invis": { "type": "boolean" }, "isNewMsg": { "type": "boolean" }, "star": { "type": "boolean" }, "recvFresh": { "type": "boolean" }, "broadcast": { "type": "boolean" }, "isForwarded": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "mentionedJidList": { "type": "array", "items": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." } }, "caption": { "type": "string" }, "event": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "chatId": { "type": "string", "minLength": 1 }, "creatorId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "startTime": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "endTime": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": { "type": "string" }, "location": { "type": "object", "properties": { "name": { "type": "string" }, "latitude": { "anyOf": [ { "type": "number" }, { "anyOf": [ { "type": "string", "const": "Infinity" }, { "type": "string", "const": "-Infinity" }, { "type": "string", "const": "NaN" } ] } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "anyOf": [ { "type": "string", "const": "Infinity" }, { "type": "string", "const": "-Infinity" }, { "type": "string", "const": "NaN" } ] } ] } }, "additionalProperties": false }, "joinLink": { "type": "string" }, "isScheduledCall": { "type": "boolean" }, "extraGuestsAllowed": { "type": "boolean" }, "isCanceled": { "type": "boolean" }, "fromMe": { "type": "boolean" }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 2147483647 } }, "required": [ "id", "chatId", "creatorId", "name", "startTime", "isCanceled", "fromMe", "timestamp" ], "additionalProperties": false }, "expectedImageCount": { "description": "Number of image messages declared by an album container; not a received-media count.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expectedVideoCount": { "description": "Number of video messages declared by an album container, including GIF videos.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "parentMsgKey": { "description": "Serialized parent message ID for associated media.", "anyOf": [ { "type": "string", "description": "Message identifier returned by a send method or message event." }, { "type": "null" } ] }, "associationType": { "description": "WhatsApp association type. Album media uses MEDIA_ALBUM.", "type": [ "string", "null" ] }, "isGif": { "type": "boolean" }, "sender": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "name": { "type": "string" }, "shortName": { "type": "string" }, "pushname": { "type": "string" }, "formattedName": { "type": "string" }, "isBusiness": { "type": "boolean" }, "isEnterprise": { "type": "boolean" }, "isMe": { "type": "boolean" }, "isMyContact": { "type": "boolean" }, "isPSA": { "type": "boolean" }, "isUser": { "type": "boolean" }, "isWAContact": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "msgs": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" } ] }, "profilePicThumbObj": { "type": "object", "properties": { "eurl": { "type": "string" }, "id": { "type": "object", "properties": { "server": { "type": "string" }, "user": { "type": "string" }, "_serialized": { "type": "string" } }, "required": [ "server", "user", "_serialized" ], "additionalProperties": false }, "img": { "type": "string" }, "imgFull": { "type": "string" }, "tag": { "type": "string" } }, "additionalProperties": false }, "statusMute": { "type": "boolean" }, "type": { "type": "string" }, "verifiedLevel": { "type": "number" }, "verifiedName": { "type": "string" }, "isOnline": { "type": "boolean" }, "lastSeen": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} }, "timestamp": { "type": "number" }, "content": { "type": "string" }, "isGroupMsg": { "type": "boolean" }, "isMMS": { "type": "boolean" }, "isMedia": { "type": "boolean" }, "isNotification": { "type": "boolean" }, "isPSA": { "type": "boolean" }, "fromMe": { "type": "boolean" }, "chat": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque conversation identifier. Use the exact value returned by a message event or chat lookup." }, "name": { "type": "string" }, "formattedTitle": { "type": "string" }, "isGroup": { "type": "boolean" }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "name": { "type": "string" }, "shortName": { "type": "string" }, "pushname": { "type": "string" }, "formattedName": { "type": "string" }, "isBusiness": { "type": "boolean" }, "isEnterprise": { "type": "boolean" }, "isMe": { "type": "boolean" }, "isMyContact": { "type": "boolean" }, "isPSA": { "type": "boolean" }, "isUser": { "type": "boolean" }, "isWAContact": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "msgs": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" } ] }, "profilePicThumbObj": { "type": "object", "properties": { "eurl": { "type": "string" }, "id": { "type": "object", "properties": { "server": { "type": "string" }, "user": { "type": "string" }, "_serialized": { "type": "string" } }, "required": [ "server", "user", "_serialized" ], "additionalProperties": false }, "img": { "type": "string" }, "imgFull": { "type": "string" }, "tag": { "type": "string" } }, "additionalProperties": false }, "statusMute": { "type": "boolean" }, "type": { "type": "string" }, "verifiedLevel": { "type": "number" }, "verifiedName": { "type": "string" }, "isOnline": { "type": "boolean" }, "lastSeen": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} }, { "type": "null" } ] }, "groupMetadata": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for a WhatsApp group. Use the value returned by the API." }, "subject": { "type": "string" }, "creation": { "type": "number" }, "owner": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "desc": { "type": "string" }, "descTime": { "type": "number" }, "descOwner": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "restrict": { "type": "boolean" }, "announce": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" } }, "required": [ "id", "isAdmin" ], "additionalProperties": false } } }, "required": [ "id", "subject", "creation", "participants" ], "additionalProperties": {}, "description": "Serialized group metadata returned by group lookups. Additional WhatsApp Web fields may be present." }, { "type": "null" } ] }, "presence": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "t": { "type": "number" }, "unreadCount": { "type": "number" }, "lastReceivedKey": {}, "msgs": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" } ] }, "isReadOnly": { "type": "boolean" }, "muteExpiration": { "type": "number" }, "notSpam": { "type": "boolean" }, "pin": { "type": "number" }, "ack": {} }, "required": [ "id", "isGroup", "contact" ], "additionalProperties": {}, "description": "Serialized chat returned by chat lookups and listings. Its id is an opaque ChatId; additional WhatsApp Web fields may be present." }, "chatId": { "type": "string", "description": "Opaque conversation identifier. Use the exact value returned by a message event or chat lookup." }, "author": { "type": "string" }, "clientUrl": { "type": "string" }, "deprecatedMms3Url": { "type": "string" }, "isQuotedMsgAvailable": { "type": "boolean" }, "quotedMsg": {}, "quotedMsgObj": {}, "senderId": { "type": "string" } }, "required": [ "id" ], "additionalProperties": {} } }, "required": [ "ctx", "message" ], "additionalProperties": false }, "message_received": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "ctx": { "type": "object", "properties": { "correlationId": { "type": "string" }, "ts": { "type": "number" }, "attempt": { "type": "number" } }, "required": [ "correlationId", "ts" ], "additionalProperties": false }, "message": { "type": "object", "properties": { "id": { "type": "string", "description": "Message identifier returned by a send method or message event." }, "body": { "type": "string" }, "type": { "type": "string", "enum": [ "chat", "audio", "ptt", "image", "video", "album", "event_creation", "event_response", "document", "sticker", "location", "vcard", "multi_vcard", "revoked", "order", "buttons_response", "list_response", "unknown" ] }, "t": { "type": "number" }, "notifyName": { "type": "string" }, "from": { "type": "string", "description": "Opaque conversation identifier. Use the exact value returned by a message event or chat lookup." }, "to": { "type": "string", "description": "Opaque conversation identifier. Use the exact value returned by a message event or chat lookup." }, "self": { "type": "string", "enum": [ "in", "out" ] }, "ack": { "type": "number", "enum": [ -1, 0, 1, 2, 3, 4 ] }, "invis": { "type": "boolean" }, "isNewMsg": { "type": "boolean" }, "star": { "type": "boolean" }, "recvFresh": { "type": "boolean" }, "broadcast": { "type": "boolean" }, "isForwarded": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "mentionedJidList": { "type": "array", "items": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." } }, "caption": { "type": "string" }, "event": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "chatId": { "type": "string", "minLength": 1 }, "creatorId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "startTime": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "endTime": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": { "type": "string" }, "location": { "type": "object", "properties": { "name": { "type": "string" }, "latitude": { "anyOf": [ { "type": "number" }, { "anyOf": [ { "type": "string", "const": "Infinity" }, { "type": "string", "const": "-Infinity" }, { "type": "string", "const": "NaN" } ] } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "anyOf": [ { "type": "string", "const": "Infinity" }, { "type": "string", "const": "-Infinity" }, { "type": "string", "const": "NaN" } ] } ] } }, "additionalProperties": false }, "joinLink": { "type": "string" }, "isScheduledCall": { "type": "boolean" }, "extraGuestsAllowed": { "type": "boolean" }, "isCanceled": { "type": "boolean" }, "fromMe": { "type": "boolean" }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 2147483647 } }, "required": [ "id", "chatId", "creatorId", "name", "startTime", "isCanceled", "fromMe", "timestamp" ], "additionalProperties": false }, "expectedImageCount": { "description": "Number of image messages declared by an album container; not a received-media count.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expectedVideoCount": { "description": "Number of video messages declared by an album container, including GIF videos.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "parentMsgKey": { "description": "Serialized parent message ID for associated media.", "anyOf": [ { "type": "string", "description": "Message identifier returned by a send method or message event." }, { "type": "null" } ] }, "associationType": { "description": "WhatsApp association type. Album media uses MEDIA_ALBUM.", "type": [ "string", "null" ] }, "isGif": { "type": "boolean" }, "sender": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "name": { "type": "string" }, "shortName": { "type": "string" }, "pushname": { "type": "string" }, "formattedName": { "type": "string" }, "isBusiness": { "type": "boolean" }, "isEnterprise": { "type": "boolean" }, "isMe": { "type": "boolean" }, "isMyContact": { "type": "boolean" }, "isPSA": { "type": "boolean" }, "isUser": { "type": "boolean" }, "isWAContact": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "msgs": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" } ] }, "profilePicThumbObj": { "type": "object", "properties": { "eurl": { "type": "string" }, "id": { "type": "object", "properties": { "server": { "type": "string" }, "user": { "type": "string" }, "_serialized": { "type": "string" } }, "required": [ "server", "user", "_serialized" ], "additionalProperties": false }, "img": { "type": "string" }, "imgFull": { "type": "string" }, "tag": { "type": "string" } }, "additionalProperties": false }, "statusMute": { "type": "boolean" }, "type": { "type": "string" }, "verifiedLevel": { "type": "number" }, "verifiedName": { "type": "string" }, "isOnline": { "type": "boolean" }, "lastSeen": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} }, "timestamp": { "type": "number" }, "content": { "type": "string" }, "isGroupMsg": { "type": "boolean" }, "isMMS": { "type": "boolean" }, "isMedia": { "type": "boolean" }, "isNotification": { "type": "boolean" }, "isPSA": { "type": "boolean" }, "fromMe": { "type": "boolean" }, "chat": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque conversation identifier. Use the exact value returned by a message event or chat lookup." }, "name": { "type": "string" }, "formattedTitle": { "type": "string" }, "isGroup": { "type": "boolean" }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "name": { "type": "string" }, "shortName": { "type": "string" }, "pushname": { "type": "string" }, "formattedName": { "type": "string" }, "isBusiness": { "type": "boolean" }, "isEnterprise": { "type": "boolean" }, "isMe": { "type": "boolean" }, "isMyContact": { "type": "boolean" }, "isPSA": { "type": "boolean" }, "isUser": { "type": "boolean" }, "isWAContact": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "msgs": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" } ] }, "profilePicThumbObj": { "type": "object", "properties": { "eurl": { "type": "string" }, "id": { "type": "object", "properties": { "server": { "type": "string" }, "user": { "type": "string" }, "_serialized": { "type": "string" } }, "required": [ "server", "user", "_serialized" ], "additionalProperties": false }, "img": { "type": "string" }, "imgFull": { "type": "string" }, "tag": { "type": "string" } }, "additionalProperties": false }, "statusMute": { "type": "boolean" }, "type": { "type": "string" }, "verifiedLevel": { "type": "number" }, "verifiedName": { "type": "string" }, "isOnline": { "type": "boolean" }, "lastSeen": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} }, { "type": "null" } ] }, "groupMetadata": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for a WhatsApp group. Use the value returned by the API." }, "subject": { "type": "string" }, "creation": { "type": "number" }, "owner": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "desc": { "type": "string" }, "descTime": { "type": "number" }, "descOwner": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "restrict": { "type": "boolean" }, "announce": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque WhatsApp contact identifier. Preserve the exact value returned by the API." }, "isAdmin": { "type": "boolean" }, "isSuperAdmin": { "type": "boolean" } }, "required": [ "id", "isAdmin" ], "additionalProperties": false } } }, "required": [ "id", "subject", "creation", "participants" ], "additionalProperties": {}, "description": "Serialized group metadata returned by group lookups. Additional WhatsApp Web fields may be present." }, { "type": "null" } ] }, "presence": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "t": { "type": "number" }, "unreadCount": { "type": "number" }, "lastReceivedKey": {}, "msgs": { "anyOf": [ { "type": "array", "items": {} }, { "type": "null" } ] }, "isReadOnly": { "type": "boolean" }, "muteExpiration": { "type": "number" }, "notSpam": { "type": "boolean" }, "pin": { "type": "number" }, "ack": {} }, "required": [ "id", "isGroup", "contact" ], "additionalProperties": {}, "description": "Serialized chat returned by chat lookups and listings. Its id is an opaque ChatId; additional WhatsApp Web fields may be present." }, "chatId": { "type": "string", "description": "Opaque conversation identifier. Use the exact value returned by a message event or chat lookup." }, "author": { "type": "string" }, "clientUrl": { "type": "string" }, "deprecatedMms3Url": { "type": "string" }, "isQuotedMsgAvailable": { "type": "boolean" }, "quotedMsg": {}, "quotedMsgObj": {}, "senderId": { "type": "string" } }, "required": [ "id" ], "additionalProperties": {} } }, "required": [ "ctx", "message" ], "additionalProperties": false }, "message_received_mcp": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "sessionId": { "type": "string" }, "messageId": { "type": "string" }, "chatId": { "type": "string" }, "from": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "truncated": { "type": "boolean" } }, "required": [ "sessionId", "messageId", "truncated" ], "additionalProperties": false }, "session_logout": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "correlationId": { "type": "string" }, "ts": { "type": "number" }, "attempt": { "type": "number" }, "step": { "type": "string" }, "details": { "type": "object", "properties": { "reason": { "type": "string" } }, "additionalProperties": false }, "error": { "type": "object", "properties": { "name": { "type": "string" }, "message": { "type": "string" }, "stack": { "type": "string" } }, "required": [ "name", "message" ], "additionalProperties": false }, "durationMs": { "type": "number" } }, "required": [ "correlationId", "ts", "step" ], "additionalProperties": false }, "session_state_changed": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "correlationId": { "type": "string" }, "ts": { "type": "number" }, "attempt": { "type": "number" }, "step": { "type": "string" }, "details": { "type": "object", "properties": { "prev": { "type": "string" }, "next": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "prev", "next" ], "additionalProperties": false }, "error": { "type": "object", "properties": { "name": { "type": "string" }, "message": { "type": "string" }, "stack": { "type": "string" } }, "required": [ "name", "message" ], "additionalProperties": false }, "durationMs": { "type": "number" } }, "required": [ "correlationId", "ts", "step" ], "additionalProperties": false }, "session_state_changed_mcp": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "sessionId": { "type": "string" }, "previousState": { "type": "string" }, "state": { "type": "string" } }, "required": [ "sessionId", "state" ], "additionalProperties": false } }, "messages": { "sse_ack_changed": { "name": "ack.changed", "title": "ack.changed", "summary": "Fired when a message acknowledgment is received", "contentType": "application/json", "payload": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "const": "ack.changed" }, "payload": { "$ref": "#/components/schemas/ack_changed" }, "ts": { "type": "number" }, "sessionId": { "type": "string" } }, "required": [ "id", "event", "payload", "ts", "sessionId" ], "additionalProperties": false }, "x-openwa-listener": "ack", "x-openwa-aliases": [ "onAck" ], "x-openwa-optional-runtime-listener": false }, "webhook_ack_changed": { "name": "ack.changed", "title": "ack.changed", "summary": "Fired when a message acknowledgment is received", "contentType": "application/json", "payload": { "type": "object", "properties": { "webhookId": { "type": "string" }, "sessionId": { "type": "string" }, "event": { "const": "ack.changed" }, "payload": { "$ref": "#/components/schemas/ack_changed" }, "timestamp": { "type": "number" }, "idempotencyKey": { "type": "string" } }, "required": [ "webhookId", "sessionId", "event", "payload", "timestamp" ], "additionalProperties": false }, "x-openwa-listener": "ack", "x-openwa-aliases": [ "onAck" ], "x-openwa-optional-runtime-listener": false }, "mcp_ack_changed": { "name": "ack.changed", "title": "ack.changed", "summary": "Fired when a message acknowledgment is received", "contentType": "application/json", "payload": { "type": "object", "properties": { "eventId": { "type": "string" }, "name": { "const": "ack.changed" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ack_changed_mcp" }, "cursor": { "type": "null" } }, "required": [ "eventId", "name", "timestamp", "data", "cursor" ], "additionalProperties": false }, "headers": { "type": "object", "required": [ "webhook-id", "webhook-timestamp", "webhook-signature", "X-MCP-Subscription-Id" ], "properties": { "webhook-id": { "type": "string" }, "webhook-timestamp": { "type": "string" }, "webhook-signature": { "type": "string" }, "X-MCP-Subscription-Id": { "type": "string" } } }, "x-openwa-listener": "ack", "x-openwa-aliases": [ "onAck" ], "x-openwa-optional-runtime-listener": false }, "sse_group_addedToGroup": { "name": "group.addedToGroup", "title": "group.addedToGroup", "summary": "Fired when you are added to a group", "contentType": "application/json", "payload": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "const": "group.addedToGroup" }, "payload": { "$ref": "#/components/schemas/group_addedToGroup" }, "ts": { "type": "number" }, "sessionId": { "type": "string" } }, "required": [ "id", "event", "payload", "ts", "sessionId" ], "additionalProperties": false }, "x-openwa-listener": "addedToGroup", "x-openwa-aliases": [ "onAddedToGroup" ], "x-openwa-optional-runtime-listener": true }, "webhook_group_addedToGroup": { "name": "group.addedToGroup", "title": "group.addedToGroup", "summary": "Fired when you are added to a group", "contentType": "application/json", "payload": { "type": "object", "properties": { "webhookId": { "type": "string" }, "sessionId": { "type": "string" }, "event": { "const": "group.addedToGroup" }, "payload": { "$ref": "#/components/schemas/group_addedToGroup" }, "timestamp": { "type": "number" }, "idempotencyKey": { "type": "string" } }, "required": [ "webhookId", "sessionId", "event", "payload", "timestamp" ], "additionalProperties": false }, "x-openwa-listener": "addedToGroup", "x-openwa-aliases": [ "onAddedToGroup" ], "x-openwa-optional-runtime-listener": true }, "sse_message_any": { "name": "message.any", "title": "message.any", "summary": "Fired for any message including own messages", "contentType": "application/json", "payload": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "const": "message.any" }, "payload": { "$ref": "#/components/schemas/message_any" }, "ts": { "type": "number" }, "sessionId": { "type": "string" } }, "required": [ "id", "event", "payload", "ts", "sessionId" ], "additionalProperties": false }, "x-openwa-listener": "anyMessage", "x-openwa-aliases": [ "onAnyMessage" ], "x-openwa-optional-runtime-listener": true }, "webhook_message_any": { "name": "message.any", "title": "message.any", "summary": "Fired for any message including own messages", "contentType": "application/json", "payload": { "type": "object", "properties": { "webhookId": { "type": "string" }, "sessionId": { "type": "string" }, "event": { "const": "message.any" }, "payload": { "$ref": "#/components/schemas/message_any" }, "timestamp": { "type": "number" }, "idempotencyKey": { "type": "string" } }, "required": [ "webhookId", "sessionId", "event", "payload", "timestamp" ], "additionalProperties": false }, "x-openwa-listener": "anyMessage", "x-openwa-aliases": [ "onAnyMessage" ], "x-openwa-optional-runtime-listener": true }, "sse_message_received": { "name": "message.received", "title": "message.received", "summary": "Fired when a new message is received (excluding own messages)", "contentType": "application/json", "payload": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "const": "message.received" }, "payload": { "$ref": "#/components/schemas/message_received" }, "ts": { "type": "number" }, "sessionId": { "type": "string" } }, "required": [ "id", "event", "payload", "ts", "sessionId" ], "additionalProperties": false }, "x-openwa-listener": "message", "x-openwa-aliases": [ "onMessage" ], "x-openwa-optional-runtime-listener": false }, "webhook_message_received": { "name": "message.received", "title": "message.received", "summary": "Fired when a new message is received (excluding own messages)", "contentType": "application/json", "payload": { "type": "object", "properties": { "webhookId": { "type": "string" }, "sessionId": { "type": "string" }, "event": { "const": "message.received" }, "payload": { "$ref": "#/components/schemas/message_received" }, "timestamp": { "type": "number" }, "idempotencyKey": { "type": "string" } }, "required": [ "webhookId", "sessionId", "event", "payload", "timestamp" ], "additionalProperties": false }, "x-openwa-listener": "message", "x-openwa-aliases": [ "onMessage" ], "x-openwa-optional-runtime-listener": false }, "mcp_message_received": { "name": "message.received", "title": "message.received", "summary": "Fired when a new message is received (excluding own messages)", "contentType": "application/json", "payload": { "type": "object", "properties": { "eventId": { "type": "string" }, "name": { "const": "message.received" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/message_received_mcp" }, "cursor": { "type": "null" } }, "required": [ "eventId", "name", "timestamp", "data", "cursor" ], "additionalProperties": false }, "headers": { "type": "object", "required": [ "webhook-id", "webhook-timestamp", "webhook-signature", "X-MCP-Subscription-Id" ], "properties": { "webhook-id": { "type": "string" }, "webhook-timestamp": { "type": "string" }, "webhook-signature": { "type": "string" }, "X-MCP-Subscription-Id": { "type": "string" } } }, "x-openwa-listener": "message", "x-openwa-aliases": [ "onMessage" ], "x-openwa-optional-runtime-listener": false }, "sse_session_logout": { "name": "session.logout", "title": "session.logout", "summary": "Fired when the session is logged out", "contentType": "application/json", "payload": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "const": "session.logout" }, "payload": { "$ref": "#/components/schemas/session_logout" }, "ts": { "type": "number" }, "sessionId": { "type": "string" } }, "required": [ "id", "event", "payload", "ts", "sessionId" ], "additionalProperties": false }, "x-openwa-listener": "logout", "x-openwa-aliases": [ "onLogout" ], "x-openwa-optional-runtime-listener": false }, "webhook_session_logout": { "name": "session.logout", "title": "session.logout", "summary": "Fired when the session is logged out", "contentType": "application/json", "payload": { "type": "object", "properties": { "webhookId": { "type": "string" }, "sessionId": { "type": "string" }, "event": { "const": "session.logout" }, "payload": { "$ref": "#/components/schemas/session_logout" }, "timestamp": { "type": "number" }, "idempotencyKey": { "type": "string" } }, "required": [ "webhookId", "sessionId", "event", "payload", "timestamp" ], "additionalProperties": false }, "x-openwa-listener": "logout", "x-openwa-aliases": [ "onLogout" ], "x-openwa-optional-runtime-listener": false }, "sse_session_state_changed": { "name": "session.state.changed", "title": "session.state.changed", "summary": "Fired when connection state changes", "contentType": "application/json", "payload": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "const": "session.state.changed" }, "payload": { "$ref": "#/components/schemas/session_state_changed" }, "ts": { "type": "number" }, "sessionId": { "type": "string" } }, "required": [ "id", "event", "payload", "ts", "sessionId" ], "additionalProperties": false }, "x-openwa-listener": "stateChanged", "x-openwa-aliases": [ "onStateChanged" ], "x-openwa-optional-runtime-listener": false }, "webhook_session_state_changed": { "name": "session.state.changed", "title": "session.state.changed", "summary": "Fired when connection state changes", "contentType": "application/json", "payload": { "type": "object", "properties": { "webhookId": { "type": "string" }, "sessionId": { "type": "string" }, "event": { "const": "session.state.changed" }, "payload": { "$ref": "#/components/schemas/session_state_changed" }, "timestamp": { "type": "number" }, "idempotencyKey": { "type": "string" } }, "required": [ "webhookId", "sessionId", "event", "payload", "timestamp" ], "additionalProperties": false }, "x-openwa-listener": "stateChanged", "x-openwa-aliases": [ "onStateChanged" ], "x-openwa-optional-runtime-listener": false }, "mcp_session_state_changed": { "name": "session.state.changed", "title": "session.state.changed", "summary": "Fired when connection state changes", "contentType": "application/json", "payload": { "type": "object", "properties": { "eventId": { "type": "string" }, "name": { "const": "session.state.changed" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/session_state_changed_mcp" }, "cursor": { "type": "null" } }, "required": [ "eventId", "name", "timestamp", "data", "cursor" ], "additionalProperties": false }, "headers": { "type": "object", "required": [ "webhook-id", "webhook-timestamp", "webhook-signature", "X-MCP-Subscription-Id" ], "properties": { "webhook-id": { "type": "string" }, "webhook-timestamp": { "type": "string" }, "webhook-signature": { "type": "string" }, "X-MCP-Subscription-Id": { "type": "string" } } }, "x-openwa-listener": "stateChanged", "x-openwa-aliases": [ "onStateChanged" ], "x-openwa-optional-runtime-listener": false } }, "securitySchemes": { "apiKey": { "type": "httpApiKey", "name": "X-API-Key", "in": "header", "description": "Easy API instance API key. Callback signing secrets are per subscription and are never included in this document." } } } }