**גרסאות API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=he)

# Messaging Senders

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

## פעולות

## GET /messaging-senders

Read available email, SMS and WhatsApp sender configuration observations

`list_messaging_senders`

Requires messages:read. Read-only stored organisation sender observations, never a live credential/provider test. Email configurationStatus=STORED means a configuration record exists, not that SMTP fields are complete or valid: the native transport can merge system defaults. senderAddress/replyTo are sending identities, not recipient lists. No host, port, user, password, API key or session is returned. SMS uses one native organisation AUTH config; its presence, sender label and recorded quota do not verify provider availability or cost, and no campaign-specific SMS selection is implemented. Missing/invalid quota remains null, never zero. WhatsApp status and mirrorReady are stored mirrors, not a live session poll; hibernated is sleeping with retained credentials, not proof of disconnection. Unknown status/dates stay null. Only active WhatsApp accounts are listed, while whatsappRevision covers the bounded organisation account snapshot for later management CAS. dailyCap=null means native automatic warmup; 0 means unlimited; a positive integer is the recorded daily cap, not remaining quota or guaranteed deliverability. At most 200 config records and 100 WhatsApp account records are admitted; malformed, duplicate or cross-organisation identities refuse the projection. Campaign-restricted keys are refused. GET performs no provider call, QR retrieval, session creation/restart, mirror update or send. QR/pairing data requires a separate explicitly granted management action, never this ordinary read.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Allowlisted sender observation or explicit management result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSendersResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid account id, command, query or body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_SENDER_HISTORY, SENDER_READ_LIMIT_EXCEEDED, WHATSAPP_REVISION_CHANGED, WHATSAPP_OPERATION_IN_PROGRESS, IDEMPOTENCY_CONFLICT, WHATSAPP_SESSION_UNAVAILABLE or WHATSAPP_CALLBACK_UNAVAILABLE. Do not bypass a pending/uncertain operation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "MESSAGING_SENDER_UNAVAILABLE. A transport error does not establish that an account operation failed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /messaging-senders/whatsapp/accounts

Create a WhatsApp sender account through the native connection lifecycle

`create_whatsapp_sender_account`

Requires BOTH explicit opt-in whatsapp_accounts:manage AND messages:read; messages:write/send alone is insufficient. Uses only the existing native whatsapp_accounts/OpenWA connection lifecycle, not the separate assistant WhatsApp integration or legacy campaign Selenium path. Accounts and private session references are independently admitted in this organisation; campaign-restricted keys are refused. No provider API key, openwaSessionId, raw provider error or reusable credential is returned. Management can affect subsequent campaigns; it does not send a message. Read list_messaging_senders first and use its opaque whatsappRevision for an existing-account command; it is an organisation snapshot, not an account UUID or an integer. dailyCap=null resets native automatic warmup, 0 is unlimited, positive values are daily caps. Commands require UUID idempotencyKey. A principal-and-organisation-bound command journal is acknowledged before the first provider/database effect, and an organisation lock serializes this external facade. Native admin changes remain independently concurrent; CAS failures after partial multi-row/provider work are UNCERTAIN, never falsely rolled back. Identical key/payload replays never repeat effects; changed payload conflicts. SUCCEEDED acknowledges the native account-setting/lifecycle operation, not message delivery or a completed QR scan; REFUSED can mean an update lost its CAS race. UNCERTAIN or a retained organisation lock requires review through the supported owning application, never automatic new-key retries or session recreation. Uncertain locks do not expire automatically. A failed lock cleanup can also require review; do not delete locks or use internal credentials to bypass them. journalRecorded=false makes the command UNCERTAIN even when an earlier owner acknowledgement was known; it never permits automatic replay. lockCleanup=RELEASED confirms this facade lock was removed; RETAINED accompanies unresolved work; UNAVAILABLE qualifies accessory cleanup only and does not erase an already acknowledged and journalled SUCCEEDED/REFUSED outcome. NOT_OBSERVED is returned on journal replay without inspecting locks. Cleanup uncertainty never permits automatic retry or direct lock removal. No real provider is used in the isolated tests. A deterministic wa-UUID session name is passed to the native ensureSession owner, followed by registration of the existing environment-specific status/ack webhook and insertion of the native account record. The first active account becomes default. A successful creation can still require a human QR scan: use the dedicated connection action. A provider timeout can leave a remote session without a local account; UNCERTAIN does not permit recreation with a new key.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "whatsapp_accounts:manage",
  "additional": [
    "messages:read"
  ]
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "dailyCap": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "nullable": true
          }
        },
        "required": [
          "idempotencyKey",
          "label"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Allowlisted sender observation or explicit management result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid account id, command, query or body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_SENDER_HISTORY, SENDER_READ_LIMIT_EXCEEDED, WHATSAPP_REVISION_CHANGED, WHATSAPP_OPERATION_IN_PROGRESS, IDEMPOTENCY_CONFLICT, WHATSAPP_SESSION_UNAVAILABLE or WHATSAPP_CALLBACK_UNAVAILABLE. Do not bypass a pending/uncertain operation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "MESSAGING_SENDER_UNAVAILABLE. A transport error does not establish that an account operation failed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "whatsapp_accounts:manage",
  "x-unisoft-additional-scopes": [
    "messages:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /messaging-senders/whatsapp/accounts/{id}/settings

Update a WhatsApp sender label or daily cap

`update_whatsapp_sender_account`

Requires BOTH explicit opt-in whatsapp_accounts:manage AND messages:read; messages:write/send alone is insufficient. Uses only the existing native whatsapp_accounts/OpenWA connection lifecycle, not the separate assistant WhatsApp integration or legacy campaign Selenium path. Accounts and private session references are independently admitted in this organisation; campaign-restricted keys are refused. No provider API key, openwaSessionId, raw provider error or reusable credential is returned. Management can affect subsequent campaigns; it does not send a message. Read list_messaging_senders first and use its opaque whatsappRevision for an existing-account command; it is an organisation snapshot, not an account UUID or an integer. dailyCap=null resets native automatic warmup, 0 is unlimited, positive values are daily caps. Commands require UUID idempotencyKey. A principal-and-organisation-bound command journal is acknowledged before the first provider/database effect, and an organisation lock serializes this external facade. Native admin changes remain independently concurrent; CAS failures after partial multi-row/provider work are UNCERTAIN, never falsely rolled back. Identical key/payload replays never repeat effects; changed payload conflicts. SUCCEEDED acknowledges the native account-setting/lifecycle operation, not message delivery or a completed QR scan; REFUSED can mean an update lost its CAS race. UNCERTAIN or a retained organisation lock requires review through the supported owning application, never automatic new-key retries or session recreation. Uncertain locks do not expire automatically. A failed lock cleanup can also require review; do not delete locks or use internal credentials to bypass them. journalRecorded=false makes the command UNCERTAIN even when an earlier owner acknowledgement was known; it never permits automatic replay. lockCleanup=RELEASED confirms this facade lock was removed; RETAINED accompanies unresolved work; UNAVAILABLE qualifies accessory cleanup only and does not erase an already acknowledged and journalled SUCCEEDED/REFUSED outcome. NOT_OBSERVED is returned on journal replay without inspecting locks. Cleanup uncertainty never permits automatic retry or direct lock removal. No real provider is used in the isolated tests. Changes only the native label/dailyCap fields, preserving unrelated account state. No provider call occurs for this action.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "whatsapp_accounts:manage",
  "additional": [
    "messages:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^wa-[0-9a-fA-F-]{36}$"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "patch": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "dailyCap": {
                "type": "integer",
                "minimum": 0,
                "maximum": 1000000,
                "nullable": true
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision",
          "patch"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Allowlisted sender observation or explicit management result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid account id, command, query or body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_SENDER_HISTORY, SENDER_READ_LIMIT_EXCEEDED, WHATSAPP_REVISION_CHANGED, WHATSAPP_OPERATION_IN_PROGRESS, IDEMPOTENCY_CONFLICT, WHATSAPP_SESSION_UNAVAILABLE or WHATSAPP_CALLBACK_UNAVAILABLE. Do not bypass a pending/uncertain operation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "MESSAGING_SENDER_UNAVAILABLE. A transport error does not establish that an account operation failed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "whatsapp_accounts:manage",
  "x-unisoft-additional-scopes": [
    "messages:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /messaging-senders/whatsapp/accounts/{id}/default

Choose the default WhatsApp sender account

`select_default_whatsapp_sender_account`

Requires BOTH explicit opt-in whatsapp_accounts:manage AND messages:read; messages:write/send alone is insufficient. Uses only the existing native whatsapp_accounts/OpenWA connection lifecycle, not the separate assistant WhatsApp integration or legacy campaign Selenium path. Accounts and private session references are independently admitted in this organisation; campaign-restricted keys are refused. No provider API key, openwaSessionId, raw provider error or reusable credential is returned. Management can affect subsequent campaigns; it does not send a message. Read list_messaging_senders first and use its opaque whatsappRevision for an existing-account command; it is an organisation snapshot, not an account UUID or an integer. dailyCap=null resets native automatic warmup, 0 is unlimited, positive values are daily caps. Commands require UUID idempotencyKey. A principal-and-organisation-bound command journal is acknowledged before the first provider/database effect, and an organisation lock serializes this external facade. Native admin changes remain independently concurrent; CAS failures after partial multi-row/provider work are UNCERTAIN, never falsely rolled back. Identical key/payload replays never repeat effects; changed payload conflicts. SUCCEEDED acknowledges the native account-setting/lifecycle operation, not message delivery or a completed QR scan; REFUSED can mean an update lost its CAS race. UNCERTAIN or a retained organisation lock requires review through the supported owning application, never automatic new-key retries or session recreation. Uncertain locks do not expire automatically. A failed lock cleanup can also require review; do not delete locks or use internal credentials to bypass them. journalRecorded=false makes the command UNCERTAIN even when an earlier owner acknowledgement was known; it never permits automatic replay. lockCleanup=RELEASED confirms this facade lock was removed; RETAINED accompanies unresolved work; UNAVAILABLE qualifies accessory cleanup only and does not erase an already acknowledged and journalled SUCCEEDED/REFUSED outcome. NOT_OBSERVED is returned on journal replay without inspecting locks. Cleanup uncertainty never permits automatic retry or direct lock removal. No real provider is used in the isolated tests. Uses native isDefault fields and CAS over the admitted organisation accounts. It selects the existing active account for native fallback, not a specific already materialized send. No provider call occurs.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "whatsapp_accounts:manage",
  "additional": [
    "messages:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^wa-[0-9a-fA-F-]{36}$"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Allowlisted sender observation or explicit management result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid account id, command, query or body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_SENDER_HISTORY, SENDER_READ_LIMIT_EXCEEDED, WHATSAPP_REVISION_CHANGED, WHATSAPP_OPERATION_IN_PROGRESS, IDEMPOTENCY_CONFLICT, WHATSAPP_SESSION_UNAVAILABLE or WHATSAPP_CALLBACK_UNAVAILABLE. Do not bypass a pending/uncertain operation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "MESSAGING_SENDER_UNAVAILABLE. A transport error does not establish that an account operation failed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "whatsapp_accounts:manage",
  "x-unisoft-additional-scopes": [
    "messages:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /messaging-senders/whatsapp/accounts/{id}/disconnect

Disconnect a WhatsApp sender account through the native lifecycle

`disconnect_whatsapp_sender_account`

Requires BOTH explicit opt-in whatsapp_accounts:manage AND messages:read; messages:write/send alone is insufficient. Uses only the existing native whatsapp_accounts/OpenWA connection lifecycle, not the separate assistant WhatsApp integration or legacy campaign Selenium path. Accounts and private session references are independently admitted in this organisation; campaign-restricted keys are refused. No provider API key, openwaSessionId, raw provider error or reusable credential is returned. Management can affect subsequent campaigns; it does not send a message. Read list_messaging_senders first and use its opaque whatsappRevision for an existing-account command; it is an organisation snapshot, not an account UUID or an integer. dailyCap=null resets native automatic warmup, 0 is unlimited, positive values are daily caps. Commands require UUID idempotencyKey. A principal-and-organisation-bound command journal is acknowledged before the first provider/database effect, and an organisation lock serializes this external facade. Native admin changes remain independently concurrent; CAS failures after partial multi-row/provider work are UNCERTAIN, never falsely rolled back. Identical key/payload replays never repeat effects; changed payload conflicts. SUCCEEDED acknowledges the native account-setting/lifecycle operation, not message delivery or a completed QR scan; REFUSED can mean an update lost its CAS race. UNCERTAIN or a retained organisation lock requires review through the supported owning application, never automatic new-key retries or session recreation. Uncertain locks do not expire automatically. A failed lock cleanup can also require review; do not delete locks or use internal credentials to bypass them. journalRecorded=false makes the command UNCERTAIN even when an earlier owner acknowledgement was known; it never permits automatic replay. lockCleanup=RELEASED confirms this facade lock was removed; RETAINED accompanies unresolved work; UNAVAILABLE qualifies accessory cleanup only and does not erase an already acknowledged and journalled SUCCEEDED/REFUSED outcome. NOT_OBSERVED is returned on journal replay without inspecting locks. Cleanup uncertainty never permits automatic retry or direct lock removal. No real provider is used in the isolated tests. Calls the native deleteSession owner, then deactivates the account and clears its default flag. If it was default, the oldest remaining active account is selected, matching the native path. Existing campaign availability can change. An ambiguous remote disconnect keeps UNCERTAIN and blocks automatic retry.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "whatsapp_accounts:manage",
  "additional": [
    "messages:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^wa-[0-9a-fA-F-]{36}$"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Allowlisted sender observation or explicit management result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid account id, command, query or body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_SENDER_HISTORY, SENDER_READ_LIMIT_EXCEEDED, WHATSAPP_REVISION_CHANGED, WHATSAPP_OPERATION_IN_PROGRESS, IDEMPOTENCY_CONFLICT, WHATSAPP_SESSION_UNAVAILABLE or WHATSAPP_CALLBACK_UNAVAILABLE. Do not bypass a pending/uncertain operation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "MESSAGING_SENDER_UNAVAILABLE. A transport error does not establish that an account operation failed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "whatsapp_accounts:manage",
  "x-unisoft-additional-scopes": [
    "messages:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /messaging-senders/whatsapp/accounts/{id}/connection

Read the sensitive QR connection step for one existing WhatsApp sender account

`get_whatsapp_sender_connection`

Requires BOTH explicit opt-in whatsapp_accounts:manage AND messages:read. This dedicated action reads the existing native session status and QR pairing value through OpenWA; it does not create/start/restart/delete a session, change the stored mirror, select a default or send a message. Ordinary sender reads never include QR/session data. Resolve an existing active wa-UUID account first; all private session references remain server-side. The returned qr is sensitive temporary pairing material intended for the authorized human to scan in WhatsApp Linked Devices; do not log, persist, quote into general reports or treat it as reusable authentication. It can be a data image or textual QR value and may expire; qr=null means unavailable or already ready, not a fabricated pairing link. liveVerified=true means a recognized current provider status was read; ready=true requires that live status to be ready. A fallback stored status with liveVerified=false is not proof of a current connection. A human scan is still required when a QR is shown. Provider failures do not authorize session recreation or credential switching. No openwaSessionId, API key, raw provider diagnostic or other account session is returned. Campaign-restricted keys are refused. The body is exactly an empty JSON object and query parameters are forbidden.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "whatsapp_accounts:manage",
  "additional": [
    "messages:read"
  ]
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^wa-[0-9a-fA-F-]{36}$"
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "Allowlisted sender observation or explicit management result.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderConnectionResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid account id, command, query or body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentication required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE or CAMPAIGN_RESTRICTED_KEY.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_SENDER_HISTORY, SENDER_READ_LIMIT_EXCEEDED, WHATSAPP_REVISION_CHANGED, WHATSAPP_OPERATION_IN_PROGRESS, IDEMPOTENCY_CONFLICT, WHATSAPP_SESSION_UNAVAILABLE or WHATSAPP_CALLBACK_UNAVAILABLE. Do not bypass a pending/uncertain operation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "MESSAGING_SENDER_UNAVAILABLE. A transport error does not establish that an account operation failed.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "whatsapp_accounts:manage",
  "x-unisoft-additional-scopes": [
    "messages:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## סכמות

```json
{
  "components": {
    "schemas": {
      "MessagingSendersResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "email",
              "sms",
              "whatsapp",
              "whatsappRevision"
            ],
            "properties": {
              "email": {
                "type": "array",
                "maxItems": 200,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "name",
                    "senderAddress",
                    "replyTo",
                    "provider",
                    "configurationStatus",
                    "verification"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "nullable": true
                    },
                    "name": {
                      "type": "string",
                      "nullable": true
                    },
                    "senderAddress": {
                      "type": "string",
                      "nullable": true
                    },
                    "replyTo": {
                      "type": "string",
                      "nullable": true
                    },
                    "provider": {
                      "type": "string",
                      "nullable": true
                    },
                    "configurationStatus": {
                      "type": "string",
                      "enum": [
                        "STORED"
                      ]
                    },
                    "verification": {
                      "type": "string",
                      "enum": [
                        "NOT_CHECKED"
                      ]
                    }
                  }
                }
              },
              "sms": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "configurationPresent",
                  "senderLabel",
                  "quota",
                  "selection",
                  "verification"
                ],
                "properties": {
                  "configurationPresent": {
                    "type": "boolean"
                  },
                  "senderLabel": {
                    "type": "string",
                    "nullable": true
                  },
                  "quota": {
                    "type": "integer",
                    "minimum": 0,
                    "nullable": true
                  },
                  "selection": {
                    "type": "string",
                    "enum": [
                      "ORGANISATION_SINGLE_CONFIG"
                    ]
                  },
                  "verification": {
                    "type": "string",
                    "enum": [
                      "NOT_CHECKED"
                    ]
                  }
                }
              },
              "whatsapp": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/MessagingSenderAccount"
                }
              },
              "whatsappRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              }
            }
          }
        }
      },
      "MessagingSenderAccount": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "label",
          "status",
          "mirrorReady",
          "active",
          "isDefault",
          "displayNumber",
          "dailyCap",
          "connectedAt",
          "lastStatusAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^wa-[0-9a-fA-F-]{36}$"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true,
            "enum": [
              "created",
              "initializing",
              "qr_ready",
              "authenticating",
              "ready",
              "disconnected",
              "failed",
              "hibernated",
              null
            ]
          },
          "mirrorReady": {
            "type": "boolean"
          },
          "active": {
            "type": "boolean"
          },
          "isDefault": {
            "type": "boolean"
          },
          "displayNumber": {
            "type": "string",
            "nullable": true
          },
          "dailyCap": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "connectedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "lastStatusAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          }
        }
      },
      "MessagingSenderCommandResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "requestId",
              "accountId",
              "status",
              "replayed",
              "journalRecorded",
              "lockCleanup"
            ],
            "properties": {
              "requestId": {
                "type": "string",
                "format": "uuid"
              },
              "accountId": {
                "type": "string",
                "pattern": "^wa-[0-9a-fA-F-]{36}$"
              },
              "status": {
                "type": "string",
                "enum": [
                  "SUCCEEDED",
                  "REFUSED",
                  "UNCERTAIN"
                ]
              },
              "replayed": {
                "type": "boolean"
              },
              "journalRecorded": {
                "type": "boolean"
              },
              "lockCleanup": {
                "type": "string",
                "enum": [
                  "RELEASED",
                  "RETAINED",
                  "UNAVAILABLE",
                  "NOT_OBSERVED"
                ]
              }
            }
          }
        }
      },
      "MessagingSenderConnectionResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "status",
              "liveVerified",
              "ready",
              "qr"
            ],
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^wa-[0-9a-fA-F-]{36}$"
              },
              "status": {
                "type": "string",
                "nullable": true,
                "enum": [
                  "created",
                  "initializing",
                  "qr_ready",
                  "authenticating",
                  "ready",
                  "disconnected",
                  "failed",
                  "hibernated",
                  null
                ]
              },
              "liveVerified": {
                "type": "boolean"
              },
              "ready": {
                "type": "boolean"
              },
              "qr": {
                "type": "string",
                "nullable": true,
                "maxLength": 1000000
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
