**Versions de l’API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=fr)

# Messaging Senders

OpenAPI 3.0.3 · API 2.0.0

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

## Opérations

## GET /messaging-senders

Consulter les expéditeurs Email, SMS et WhatsApp et leur configuration enregistrée

`list_messaging_senders`

messages:read est requis. Observations enregistrées des expéditeurs d’organisation en lecture seule, jamais test d’identifiants/prestataire en direct. Pour Email, configurationStatus=STORED signifie qu’un document existe, pas que les champs SMTP sont complets ou valides : le transport natif peut fusionner des valeurs système. senderAddress/replyTo sont des identités d’expédition, pas des listes destinataires. Aucun hôte, port, utilisateur, mot de passe, clé API ni session n’est retourné. SMS utilise une configuration AUTH native unique d’organisation ; sa présence, son libellé et son quota enregistré ne vérifient ni disponibilité ni coût, et aucune sélection SMS propre à une campagne n’est implémentée. Un quota absent/invalide reste null, jamais zéro. Les status/mirrorReady WhatsApp sont des miroirs enregistrés, pas une interrogation live ; hibernated signifie moteur en veille avec identifiants conservés, pas preuve de déconnexion. Les états/dates inconnus restent null. Seuls les comptes WhatsApp actifs sont listés, tandis que whatsappRevision couvre la photographie bornée des comptes d’organisation pour le CAS de gestion. dailyCap=null signifie warmup automatique natif ; 0 est illimité ; un entier positif est le plafond quotidien enregistré, pas un quota restant ni une délivrabilité garantie. Au plus 200 configurations et 100 comptes WhatsApp sont admis ; identités mal formées, dupliquées ou étrangères refusent la projection. Les clés limitées aux collectes sont refusées. GET n’appelle aucun prestataire, ne récupère aucun QR, ne crée/redémarre aucune session, ne met pas le miroir à jour et n’envoie rien. QR/appairage exige une action de gestion distincte explicitement autorisée, jamais cette lecture ordinaire.

### Authentification

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

### Permissions requises

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

### Réponses

#### HTTP 200

```json
{
  "description": "Observation d’expéditeur limitée aux champs autorisés ou résultat de gestion explicite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSendersResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identifiant de compte, commande, requête ou corps invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "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 ou 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 ou WHATSAPP_CALLBACK_UNAVAILABLE. Ne pas contourner une opération en cours/incertaine.",
  "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. Une erreur de transport ne démontre pas l’échec d’une opération de compte.",
  "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

Créer un compte expéditeur WhatsApp par le cycle natif de connexion

`create_whatsapp_sender_account`

Les deux droits messages:read et whatsapp_accounts:manage explicitement accordé sont requis ; messages:write/send seul ne suffit pas. Utilise uniquement le cycle natif de connexion whatsapp_accounts/OpenWA, pas l’intégration WhatsApp de l’assistant ni l’ancien parcours Selenium par campagne. Comptes et références de sessions privées sont admis indépendamment dans l’organisation ; les clés limitées aux collectes sont refusées. Aucune clé API prestataire, openwaSessionId, erreur brute ni identifiant réutilisable n’est renvoyé. La gestion peut affecter des campagnes ultérieures ; elle n’envoie aucun message. Lire d’abord list_messaging_senders et transmettre son whatsappRevision opaque pour une commande de compte existant ; c’est une photographie de l’organisation, pas un UUID de compte ni un entier. dailyCap=null rétablit le warmup automatique natif, 0 est illimité, les valeurs positives sont des plafonds quotidiens. Les commandes exigent un UUID idempotencyKey. Un journal lié au principal/organisation est acquitté avant le premier effet prestataire/base et un verrou d’organisation sérialise cette façade externe. L’admin natif reste indépendamment concurrent ; les échecs CAS après travail partiel multi-ligne/prestataire donnent UNCERTAIN, sans prétendre annuler le travail. Une clé/charge identique relit sans répéter les effets ; une charge différente entre en conflit. SUCCEEDED acquitte l’opération native de réglage/cycle de compte, pas la livraison de messages ni un scan QR terminé ; REFUSED peut signaler une course CAS perdue. UNCERTAIN ou un verrou retenu exige une revue dans l’application propriétaire prise en charge, jamais un réessai automatique avec nouvelle clé ni une recréation de session. Les verrous incertains n’expirent pas automatiquement. Un échec de nettoyage peut aussi exiger une revue ; ne pas supprimer de verrou ni utiliser des identifiants internes pour le contourner. journalRecorded=false rend la commande UNCERTAIN même si un acquittement natif antérieur était connu ; aucun rejeu automatique n’est autorisé. lockCleanup=RELEASED confirme le retrait du verrou de cette façade ; RETAINED accompagne une opération non résolue ; UNAVAILABLE qualifie uniquement le nettoyage accessoire et ne supprime pas un résultat SUCCEEDED/REFUSED déjà acquitté et journalisé. NOT_OBSERVED est renvoyé lors de la relecture du journal sans inspection des verrous. Une incertitude de nettoyage ne permet jamais de réessai automatique ni de retrait direct du verrou. Aucun prestataire réel n’est utilisé par les tests isolés. Un nom de session wa-UUID déterministe est transmis au propriétaire natif ensureSession, puis le webhook existant de statut/accusés de l’environnement est enregistré et le document natif inséré. Le premier compte actif devient le défaut. Une création réussie peut encore exiger un scan QR humain : utiliser l’action de connexion dédiée. Un délai prestataire peut laisser une session distante sans compte local ; UNCERTAIN n’autorise pas sa recréation avec une nouvelle clé.

### Authentification

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

### Permissions requises

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

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Observation d’expéditeur limitée aux champs autorisés ou résultat de gestion explicite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identifiant de compte, commande, requête ou corps invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "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 ou 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 ou WHATSAPP_CALLBACK_UNAVAILABLE. Ne pas contourner une opération en cours/incertaine.",
  "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. Une erreur de transport ne démontre pas l’échec d’une opération de compte.",
  "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

Modifier le libellé ou plafond quotidien d’un expéditeur WhatsApp

`update_whatsapp_sender_account`

Les deux droits messages:read et whatsapp_accounts:manage explicitement accordé sont requis ; messages:write/send seul ne suffit pas. Utilise uniquement le cycle natif de connexion whatsapp_accounts/OpenWA, pas l’intégration WhatsApp de l’assistant ni l’ancien parcours Selenium par campagne. Comptes et références de sessions privées sont admis indépendamment dans l’organisation ; les clés limitées aux collectes sont refusées. Aucune clé API prestataire, openwaSessionId, erreur brute ni identifiant réutilisable n’est renvoyé. La gestion peut affecter des campagnes ultérieures ; elle n’envoie aucun message. Lire d’abord list_messaging_senders et transmettre son whatsappRevision opaque pour une commande de compte existant ; c’est une photographie de l’organisation, pas un UUID de compte ni un entier. dailyCap=null rétablit le warmup automatique natif, 0 est illimité, les valeurs positives sont des plafonds quotidiens. Les commandes exigent un UUID idempotencyKey. Un journal lié au principal/organisation est acquitté avant le premier effet prestataire/base et un verrou d’organisation sérialise cette façade externe. L’admin natif reste indépendamment concurrent ; les échecs CAS après travail partiel multi-ligne/prestataire donnent UNCERTAIN, sans prétendre annuler le travail. Une clé/charge identique relit sans répéter les effets ; une charge différente entre en conflit. SUCCEEDED acquitte l’opération native de réglage/cycle de compte, pas la livraison de messages ni un scan QR terminé ; REFUSED peut signaler une course CAS perdue. UNCERTAIN ou un verrou retenu exige une revue dans l’application propriétaire prise en charge, jamais un réessai automatique avec nouvelle clé ni une recréation de session. Les verrous incertains n’expirent pas automatiquement. Un échec de nettoyage peut aussi exiger une revue ; ne pas supprimer de verrou ni utiliser des identifiants internes pour le contourner. journalRecorded=false rend la commande UNCERTAIN même si un acquittement natif antérieur était connu ; aucun rejeu automatique n’est autorisé. lockCleanup=RELEASED confirme le retrait du verrou de cette façade ; RETAINED accompagne une opération non résolue ; UNAVAILABLE qualifie uniquement le nettoyage accessoire et ne supprime pas un résultat SUCCEEDED/REFUSED déjà acquitté et journalisé. NOT_OBSERVED est renvoyé lors de la relecture du journal sans inspection des verrous. Une incertitude de nettoyage ne permet jamais de réessai automatique ni de retrait direct du verrou. Aucun prestataire réel n’est utilisé par les tests isolés. Modifie uniquement les champs natifs label/dailyCap, en conservant les autres états du compte. Aucun appel prestataire pour cette action.

### Authentification

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

### Permissions requises

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

### Paramètres

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

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Observation d’expéditeur limitée aux champs autorisés ou résultat de gestion explicite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identifiant de compte, commande, requête ou corps invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "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 ou 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 ou WHATSAPP_CALLBACK_UNAVAILABLE. Ne pas contourner une opération en cours/incertaine.",
  "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. Une erreur de transport ne démontre pas l’échec d’une opération de compte.",
  "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

Choisir le compte expéditeur WhatsApp par défaut

`select_default_whatsapp_sender_account`

Les deux droits messages:read et whatsapp_accounts:manage explicitement accordé sont requis ; messages:write/send seul ne suffit pas. Utilise uniquement le cycle natif de connexion whatsapp_accounts/OpenWA, pas l’intégration WhatsApp de l’assistant ni l’ancien parcours Selenium par campagne. Comptes et références de sessions privées sont admis indépendamment dans l’organisation ; les clés limitées aux collectes sont refusées. Aucune clé API prestataire, openwaSessionId, erreur brute ni identifiant réutilisable n’est renvoyé. La gestion peut affecter des campagnes ultérieures ; elle n’envoie aucun message. Lire d’abord list_messaging_senders et transmettre son whatsappRevision opaque pour une commande de compte existant ; c’est une photographie de l’organisation, pas un UUID de compte ni un entier. dailyCap=null rétablit le warmup automatique natif, 0 est illimité, les valeurs positives sont des plafonds quotidiens. Les commandes exigent un UUID idempotencyKey. Un journal lié au principal/organisation est acquitté avant le premier effet prestataire/base et un verrou d’organisation sérialise cette façade externe. L’admin natif reste indépendamment concurrent ; les échecs CAS après travail partiel multi-ligne/prestataire donnent UNCERTAIN, sans prétendre annuler le travail. Une clé/charge identique relit sans répéter les effets ; une charge différente entre en conflit. SUCCEEDED acquitte l’opération native de réglage/cycle de compte, pas la livraison de messages ni un scan QR terminé ; REFUSED peut signaler une course CAS perdue. UNCERTAIN ou un verrou retenu exige une revue dans l’application propriétaire prise en charge, jamais un réessai automatique avec nouvelle clé ni une recréation de session. Les verrous incertains n’expirent pas automatiquement. Un échec de nettoyage peut aussi exiger une revue ; ne pas supprimer de verrou ni utiliser des identifiants internes pour le contourner. journalRecorded=false rend la commande UNCERTAIN même si un acquittement natif antérieur était connu ; aucun rejeu automatique n’est autorisé. lockCleanup=RELEASED confirme le retrait du verrou de cette façade ; RETAINED accompagne une opération non résolue ; UNAVAILABLE qualifie uniquement le nettoyage accessoire et ne supprime pas un résultat SUCCEEDED/REFUSED déjà acquitté et journalisé. NOT_OBSERVED est renvoyé lors de la relecture du journal sans inspection des verrous. Une incertitude de nettoyage ne permet jamais de réessai automatique ni de retrait direct du verrou. Aucun prestataire réel n’est utilisé par les tests isolés. Utilise les champs natifs isDefault et un CAS sur les comptes d’organisation admis. Sélectionne le compte actif existant pour le repli natif, pas un envoi précis déjà matérialisé. Aucun appel prestataire.

### Authentification

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

### Permissions requises

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

### Paramètres

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

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Observation d’expéditeur limitée aux champs autorisés ou résultat de gestion explicite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identifiant de compte, commande, requête ou corps invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "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 ou 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 ou WHATSAPP_CALLBACK_UNAVAILABLE. Ne pas contourner une opération en cours/incertaine.",
  "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. Une erreur de transport ne démontre pas l’échec d’une opération de compte.",
  "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

Déconnecter un expéditeur WhatsApp par le cycle natif

`disconnect_whatsapp_sender_account`

Les deux droits messages:read et whatsapp_accounts:manage explicitement accordé sont requis ; messages:write/send seul ne suffit pas. Utilise uniquement le cycle natif de connexion whatsapp_accounts/OpenWA, pas l’intégration WhatsApp de l’assistant ni l’ancien parcours Selenium par campagne. Comptes et références de sessions privées sont admis indépendamment dans l’organisation ; les clés limitées aux collectes sont refusées. Aucune clé API prestataire, openwaSessionId, erreur brute ni identifiant réutilisable n’est renvoyé. La gestion peut affecter des campagnes ultérieures ; elle n’envoie aucun message. Lire d’abord list_messaging_senders et transmettre son whatsappRevision opaque pour une commande de compte existant ; c’est une photographie de l’organisation, pas un UUID de compte ni un entier. dailyCap=null rétablit le warmup automatique natif, 0 est illimité, les valeurs positives sont des plafonds quotidiens. Les commandes exigent un UUID idempotencyKey. Un journal lié au principal/organisation est acquitté avant le premier effet prestataire/base et un verrou d’organisation sérialise cette façade externe. L’admin natif reste indépendamment concurrent ; les échecs CAS après travail partiel multi-ligne/prestataire donnent UNCERTAIN, sans prétendre annuler le travail. Une clé/charge identique relit sans répéter les effets ; une charge différente entre en conflit. SUCCEEDED acquitte l’opération native de réglage/cycle de compte, pas la livraison de messages ni un scan QR terminé ; REFUSED peut signaler une course CAS perdue. UNCERTAIN ou un verrou retenu exige une revue dans l’application propriétaire prise en charge, jamais un réessai automatique avec nouvelle clé ni une recréation de session. Les verrous incertains n’expirent pas automatiquement. Un échec de nettoyage peut aussi exiger une revue ; ne pas supprimer de verrou ni utiliser des identifiants internes pour le contourner. journalRecorded=false rend la commande UNCERTAIN même si un acquittement natif antérieur était connu ; aucun rejeu automatique n’est autorisé. lockCleanup=RELEASED confirme le retrait du verrou de cette façade ; RETAINED accompagne une opération non résolue ; UNAVAILABLE qualifie uniquement le nettoyage accessoire et ne supprime pas un résultat SUCCEEDED/REFUSED déjà acquitté et journalisé. NOT_OBSERVED est renvoyé lors de la relecture du journal sans inspection des verrous. Une incertitude de nettoyage ne permet jamais de réessai automatique ni de retrait direct du verrou. Aucun prestataire réel n’est utilisé par les tests isolés. Appelle le propriétaire natif deleteSession, puis désactive le compte et retire son défaut. S’il était le défaut, le plus ancien compte actif restant est choisi selon le parcours natif. La disponibilité des campagnes existantes peut changer. Une déconnexion distante ambiguë conserve UNCERTAIN et bloque tout réessai automatique.

### Authentification

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

### Permissions requises

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

### Paramètres

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

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Observation d’expéditeur limitée aux champs autorisés ou résultat de gestion explicite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identifiant de compte, commande, requête ou corps invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "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 ou 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 ou WHATSAPP_CALLBACK_UNAVAILABLE. Ne pas contourner une opération en cours/incertaine.",
  "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. Une erreur de transport ne démontre pas l’échec d’une opération de compte.",
  "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

Consulter l’étape sensible de connexion QR d’un compte WhatsApp existant

`get_whatsapp_sender_connection`

Les deux droits messages:read et whatsapp_accounts:manage explicitement accordé sont requis. Cette action dédiée lit l’état et le QR de la session native existante via OpenWA ; elle ne crée, démarre, redémarre ni supprime de session, ne change pas le miroir enregistré, ne choisit pas de défaut et n’envoie rien. Les lectures ordinaires ne contiennent jamais de QR/session. Résoudre d’abord un compte wa-UUID actif existant ; ses références privées restent côté serveur. qr est un matériel d’appairage temporaire sensible destiné au scan par l’humain autorisé dans les Appareils connectés de WhatsApp ; ne pas le journaliser, le stocker, le citer dans un rapport général ni le considérer comme identifiant réutilisable. Il peut s’agir d’une image data ou d’un QR textuel et il peut expirer ; qr=null signifie indisponible ou déjà prêt, pas un lien d’appairage inventé. liveVerified=true signifie qu’un état prestataire actuel reconnu a été lu ; ready=true exige que cet état live soit ready. Un état de miroir de repli avec liveVerified=false ne prouve pas une connexion actuelle. Un scan humain reste nécessaire lorsqu’un QR est affiché. Les échecs prestataire n’autorisent ni recréation de session ni changement d’identifiants. Aucun openwaSessionId, clé API, diagnostic brut ou session d’un autre compte n’est renvoyé. Les clés limitées aux collectes sont refusées. Le corps est exactement un objet JSON vide et les paramètres de requête sont interdits.

### Authentification

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

### Permissions requises

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

### Paramètres

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

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Observation d’expéditeur limitée aux champs autorisés ou résultat de gestion explicite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessagingSenderConnectionResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identifiant de compte, commande, requête ou corps invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "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 ou 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 ou WHATSAPP_CALLBACK_UNAVAILABLE. Ne pas contourner une opération en cours/incertaine.",
  "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. Une erreur de transport ne démontre pas l’échec d’une opération de compte.",
  "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
  }
}
```

## Schémas

```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"
      }
    }
  }
}
```
