# Connect : Claude et autres IA (MCP)

> Index de la documentation : https://wahasend.com/docs/fr/llms.txt · Tout en un fichier : https://wahasend.com/docs/fr.md · URL de base de l'API : https://app.wahasend.com/api/v1

Avec **Connect**, une application d'IA travaille votre numéro WhatsApp : elle lit vos conversations, rédige et envoie des réponses, prospecte, envoie et ouvre des fichiers. Elle parle MCP (Model Context Protocol) en HTTP. Adresse du serveur :

```text
https://app.wahasend.com/api/v1/mcp
```

L'IA réfléchit et écrit (dans son propre compte) ; WahaSend ne fait que transporter les messages et appliquer les [limites d'envoi](https://wahasend.com/docs/fr/connect.md#connect-limits).

<a id="connect-claude"></a>

### 1. claude.ai, Claude Desktop et l'app Claude (connexion, sans clé)

1. Dans Claude, ouvrez **Réglages → Connecteurs** et touchez **Ajouter un connecteur personnalisé**.
2. Nom : `WahaSend`. Lien : `https://app.wahasend.com/api/v1/mcp`.
3. Touchez **Se connecter**, connectez-vous à WahaSend, choisissez les numéros WhatsApp que Claude peut utiliser (un, plusieurs, ou **Tous mes numéros**, qui inclut ceux ajoutés plus tard) et touchez **Autoriser**.

Derrière, c'est de l'OAuth 2.1 standard (code d'autorisation + PKCE, enregistrement dynamique du client, portée `whatsapp`). Les jetons d'accès durent 60 minutes et se renouvellent pendant 30 jours. La connexion n'atteint que les numéros choisis, et ne marche que sur `/mcp`. Seuls les propriétaires et admins peuvent l'autoriser. La page **Connect** liste les applications connectées avec leurs numéros, permet de changer ces numéros sans se reconnecter (effet à la requête suivante) ou de les déconnecter ; un changement de mot de passe ou un départ de l'organisation les coupe aussi. Un numéro supprimé quitte les applications qui l'avaient ; une application qui n'a plus de numéro est déconnectée.

<a id="connect-key"></a>

### 2. Claude Code, Cursor, Codex (avec votre clé)

Remplacez `YOUR_KEY` par votre clé de compte (tableau de bord → **Connect**).

Claude Code:

```bash
claude mcp add --transport http wahasend https://app.wahasend.com/api/v1/mcp --header "Authorization: Bearer YOUR_KEY"
```

Claude Desktop ou Cursor (réglages MCP):

```json
{
  "mcpServers": {
    "wahasend": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.wahasend.com/api/v1/mcp",
        "--header",
        "Authorization: Bearer YOUR_KEY"
      ]
    }
  }
}
```

Codex : ~/.codex/config.toml:

```toml
[mcp_servers.wahasend]
url = "https://app.wahasend.com/api/v1/mcp"
bearer_token_env_var = "WAHASEND_API_KEY"
```

…puis, dans le terminal où vous lancez Codex:

```bash
export WAHASEND_API_KEY=YOUR_KEY
```

Codex peut aussi se connecter sans clé : `codex mcp add wahasend --url https://app.wahasend.com/api/v1/mcp` ouvre votre navigateur ; `codex mcp login wahasend` reconnecte plus tard. Tout autre client MCP : donnez le lien et envoyez la clé en `Authorization: Bearer` (ou `X-API-Key`).

<a id="connect-chatgpt"></a>

### 3. ChatGPT

1. Utilisez ChatGPT sur le web avec une offre payante (Plus, Pro, Business, Enterprise ou Education) ; l'app mobile ne peut pas ajouter d'applications.
2. Dans **Réglages**, activez le **mode développeur**.
3. Créez une application nommée `WahaSend` avec le lien `https://app.wahasend.com/api/v1/mcp` et l'authentification **OAuth**.
4. Connectez-vous à WahaSend, choisissez les numéros qu'il peut utiliser et touchez **Autoriser**. Dans une conversation, ouvrez **+** → Mode développeur → WahaSend.

<a id="connect-numbers"></a>

### Plusieurs numéros WhatsApp

Une connexion peut travailler plusieurs de vos numéros. Lesquels : une connexion Claude atteint les numéros choisis à l'autorisation (ou tous) ; la clé du compte atteint tous les numéros de l'organisation ; une clé de numéro seulement le sien. Aucun outil ne voit ni n'utilise jamais un autre numéro.

- `list_numbers` donne pour chaque numéro son id, son téléphone et son nom (libellé), s'il est connecté, si WhatsApp l'a peut-être bloqué, s'il est le numéro par défaut, et ce qu'il peut encore envoyer aujourd'hui.
- Conversations, réponses et messages disent sur quel numéro ils sont (`number` : id, téléphone, libellé). Un contact qui a écrit à deux numéros a deux conversations. `list_chats`, `read_chat`, `new_replies` et `find_contact` acceptent un `number` facultatif (id, téléphone ou libellé) pour ne regarder qu'un numéro.
- `send_message`, `send_attachment` et `send_to_many` acceptent un `from` facultatif (id, téléphone ou libellé). Sans lui, une réponse part du numéro avec lequel le contact a parlé en dernier, et un premier message de votre numéro par défaut. Quand plusieurs numéros pourraient envoyer et qu'aucun n'est celui par défaut, l'outil répond avec les candidats et l'IA vous demande. Le résultat dit quel numéro a envoyé (`number`) et pourquoi (`numberChosenBy`).
- Les limites restent par numéro : chacun a son espacement, ses plafonds par heure et par jour et sa limite de nouveaux contacts, avec les réglages de votre organisation. Un message n'est jamais déplacé vers un autre numéro parce qu'un numéro est limité, déconnecté ou peut-être bloqué (les [groupes d'envoi](https://wahasend.com/docs/fr/phone-numbers.md#several-numbers) ne s'appliquent pas à Connect). « Nouveau contact » veut dire nouveau pour le numéro qui envoie.
- `check_numbers` et `daily_allowance` acceptent un `number` facultatif ; `daily_allowance` sans lui liste tous les numéros. `open_attachment` récupère le fichier par le numéro de son message.

<a id="connect-tools"></a>

### Outils

Le serveur donne à l'IA ces outils et des règles (demander avant un premier message, répondre dans la langue du contact, ne jamais contourner une limite…). Les réponses des outils sont en JSON ; un envoi refusé dit pourquoi et jusqu'à quand. Il y a aussi un prompt `prospecting` (arguments `offer`, `language`).

Les descriptions ci-dessous sont celles que lit l'IA, en anglais, avec les limites recommandées.

#### list_numbers

List my WhatsApp numbers. The user's WhatsApp numbers this connection may use: name (label), phone, whether it is connected, whether WhatsApp may have blocked it, whether it is the default, and what it may still send today. Every other tool names numbers the same way (id, phone or label).

Aucune entrée.

#### send_message

Send a WhatsApp message. Send one text message from one of the user's WhatsApp numbers. From: pass `from` (a number's id, phone or label, see list_numbers) to choose which of the user's numbers sends; without it, a reply goes out from the number this contact last talked with, a first message from the default number — when that is unclear the result lists the numbers: ask the user. It never switches to another number by itself. Messages are spaced 30–90 s apart, capped at 60 an hour, 200 a day; the result says when it will go out. A first message to a new contact needs confirmed=true (after the user approved it) and counts against a small daily limit of that number.

- `to` string, obligatoire (1–100 chars): A phone number (+34612345678), a WhatsApp id exactly as returned (…@lid), or a contact name ("Percy")
- `text` string, obligatoire (1–4096 chars)
- `from` string, facultatif (1–100 chars): Which of the user's numbers sends (id, phone or label, see list_numbers). Omit to reply from the number the contact last talked with (or the default number for someone new).
- `confirmed` boolean, facultatif: Required for a first message to a new contact: true only after the user approved this recipient, number and text

#### send_attachment

Send a file on WhatsApp. Send one file (photo, PDF or other document, voice note, video) from one of the user's WhatsApp numbers, with an optional caption. Give exactly one source: forward_from (a message with a file in that number's chats, by the ids read_chat / new_replies return — WhatsApp forwards only within one number), url (a public https link to the file) or content_base64 + filename + mimetype (a file you made or the user gave you). The kind is chosen from the file: JPEG/PNG/WebP → photo, ogg/opus → voice note, MP4 → video, anything else allowed → document. Programs, scripts, web pages and archives are refused. From: pass `from` (a number's id, phone or label, see list_numbers) to choose which of the user's numbers sends; without it, a reply goes out from the number this contact last talked with, a first message from the default number — when that is unclear the result lists the numbers: ask the user. It never switches to another number by itself. Same rules as send_message: Messages are spaced 30–90 s apart, capped at 60 an hour, 200 a day; the result says when it will go out.

- `to` string, obligatoire (1–100 chars): A phone number (+34612345678), a WhatsApp id exactly as returned (…@lid), or a contact name ("Percy")
- `caption` string, facultatif (0–1024 chars): Text shown with the file (not for voice notes)
- `from` string, facultatif (1–100 chars): Which of the user's numbers sends (id, phone or label, see list_numbers). Omit to reply from the number the contact last talked with (or the default number for someone new).
- `confirmed` boolean, facultatif: true only after the user approved this recipient, number, file and caption. Required for a first message to a new contact, and to forward a file someone sent to another person
- `forward_from` object, facultatif
- `forward_from.chat` string, obligatoire (1–100 chars): The chat the file is in: phone, WhatsApp id (…@lid) or contact name
- `forward_from.message_id` uuid, obligatoire: The `id` of the message with the file, as read_chat / new_replies returned it
- `url` string (URL), facultatif (0–2048 chars): A public https link to the file itself
- `content_base64` string, facultatif (4–6991531 chars): The file's bytes, base64 (at most 5 MB)
- `filename` string, facultatif (1–200 chars): With content_base64: the file name, e.g. "price-list.pdf"
- `mimetype` string, facultatif (3–128 chars): With content_base64: its type, e.g. "application/pdf", "text/csv"

#### send_to_many

Send a message to several contacts. Send a text to a list of contacts, all from one of the user's numbers (from; the default number when omitted — never split across numbers). They go out one by one, 30–90 s apart; the result lists when each is scheduled and which could not be sent because a limit of that number was reached. {{name}} in the text is replaced per recipient. Requires confirmed=true, which you may only set after showing the user the recipients, the number and the text and getting their OK.

- `recipients` object[], obligatoire (1–50 items)
- `recipients[].phone` string, obligatoire (7–64 chars): Phone number in international format (+34612345678), or the WhatsApp id exactly as list_chats / new_replies returned it (e.g. 12345678901234@lid). Never strip "@lid".
- `recipients[].name` string, facultatif (0–100 chars)
- `text` string, obligatoire (1–4096 chars): May contain {{name}}
- `from` string, facultatif (1–100 chars): Which of the user's numbers sends (id, phone or label, see list_numbers). Omit to reply from the number the contact last talked with (or the default number for someone new).
- `confirmed` boolean, facultatif: Required: true only after the user approved this exact list, number and text

#### check_numbers

Check which numbers are on WhatsApp. Tell valid WhatsApp numbers from invalid ones before messaging. Does not send anything. Checked through one of the user's numbers (`number`; the default one when omitted).

- `phones` string[], obligatoire (1–500 items)
- `number` string, facultatif (1–100 chars): The user's number to check through (id, phone or label); people who already talked to it need no check

#### find_contact

Find a contact. Look someone up in the contacts of the user's numbers by name or part of their number. Returns their phone (and WhatsApp id when known) and which of the user's numbers know them. Use it before messaging someone the user names.

- `query` string, obligatoire (1–100 chars)
- `limit` integer, facultatif (1–50)
- `number` string, facultatif (1–100 chars): Only the contacts of this one of the user's numbers (id, phone or label)

#### list_chats

List conversations. Conversations of the user's numbers, newest first, with unread counts — one per contact and number (`number` says which of the user's numbers it is on). `phone` is either digits or a WhatsApp id ending in @lid; use it as-is to reply, from the same number.

- `limit` integer, facultatif (1–200)
- `search` string, facultatif (0–100 chars): Filter by phone or name
- `number` string, facultatif (1–100 chars): Only the conversations of this one of the user's numbers (id, phone or label)

#### read_chat

Read a conversation. The exchange with one contact, oldest first: what was sent (with delivery status) and what they replied. Each message has an `id` and the `number` of the user's it is on; messages with a file carry an `attachment` label — pass the id to open_attachment to see it. When the contact talked with several of the user's numbers, pass `number` to read one conversation; never mix them.

- `phone` string, obligatoire (7–64 chars): Phone number in international format (+34612345678), or the WhatsApp id exactly as list_chats / new_replies returned it (e.g. 12345678901234@lid). Never strip "@lid".
- `limit` integer, facultatif (1–500)
- `number` string, facultatif (1–100 chars): The one of the user's numbers whose conversation to read (id, phone or label)

#### open_attachment

Open an attachment. Open the file attached to one WhatsApp message: a photo is shown to you, a PDF or Word (.docx) file comes back as text, a voice note as a transcript. Videos and other files: details only. Use only when the file matters for what the user asked. The file is fetched through the number the message is on.

- `chat` string, obligatoire (1–100 chars): The contact: phone number, WhatsApp id exactly as returned (…@lid), or a contact name — the same chat you read with read_chat
- `message_id` uuid, obligatoire: The `id` of the message, as read_chat / new_replies returned it

#### new_replies

Get new replies. Everything received that has not been read yet, oldest first, each with the `number` of the user's it came in on (reply from that number). By default marks them as read so the next call returns only newer messages.

- `mark_read` boolean, facultatif (default true)
- `limit` integer, facultatif (1–500)
- `number` string, facultatif (1–100 chars): Only what came in on this one of the user's numbers (id, phone or label)

#### delivery_status

Check delivery status. Whether messages were sent, delivered, read or failed.

- `message_ids` uuid[], obligatoire (1–200 items)

#### daily_allowance

Daily allowance. What a number may still send: first messages to new contacts today, messages this hour and today, and when the next message can go out. Limits are per number. Without `number`, every number this connection may use.

- `number` string, facultatif (1–100 chars): One of the user's numbers (id, phone or label)

<a id="connect-limits"></a>

### Limites d'envoi

Chaque message envoyé par une IA passe par un limiteur par numéro : messages espacés, plafonnés par heure et par jour, et premiers messages aux nouveaux contacts plafonnés selon l'âge du numéro. Ces valeurs par défaut suivent les recommandations publiées (« environ 200 nouveaux clients par jour » de WhatsApp et la pratique des fournisseurs d'API WhatsApp). Elles ont été ajoutées après qu'un outil d'IA a envoyé 35 messages en deux minutes et que le numéro a été bloqué.

| Protection | Valeur recommandée |
| --- | --- |
| Heures d'envoi | 09:00–17:00 (Africa/Nouakchott) |
| Espacement | 30 à 90 s entre deux messages |
| Par heure | 60 messages |
| Par jour | 200 messages |
| Premiers messages aux nouveaux contacts, par jour, selon l'âge du numéro | 20 (jours 0–9), 50 (jours 10–19), 100 (jours 20–29), 200 (dès le jour 30) |
| Démarrage calme | aucun les 3 premiers jours après la liaison |
| Jour de repos | réponses seulement après 3 jours de suite de premiers messages |
| Taux de réponse | pause des premiers messages quand moins de 30 % de ceux des 7 derniers jours ont eu une réponse (à partir de 8 messages) |
| Copier-coller | le même premier message à 3 nouvelles personnes par jour au plus |
| Désinscription | jamais de message à qui a demandé d'arrêter |
| Accord | un premier message à un nouveau contact demande votre accord (`confirmed: true`) |

Le **propriétaire** de l'organisation peut modifier ou désactiver chacune (tableau de bord → **Connect** → Plus de réglages → Limites d'envoi, ou `PUT /mcp/safety` connecté ; `GET /mcp/safety` montre les valeurs actuelles et recommandées). L'IA est informée des vraies valeurs.

> WhatsApp seul décide des numéros qu'il bloque. Les valeurs recommandées réduisent le risque ; aucun outil ne peut le supprimer. Les changer est votre choix et votre responsabilité, et WahaSend n'est pas responsable d'un numéro bloqué.

<a id="connect-files"></a>

### Fichiers

- **Ouvrir** (`open_attachment`) : une photo est montrée à l'IA (3,75 Mo max), un PDF ou un Word revient en texte (30 000 caractères max), une note vocale en transcription, une vidéo en détails seulement. Fichiers jusqu'à 10 Mo. Le fichier n'est jamais stocké ; chaque ouverture est journalisée sans son contenu. Les notes vocales utilisent l'enveloppe d'IA mensuelle de Connect.
- **Envoyer** (`send_attachment`) : transférer un fichier de vos conversations, un lien **https** public (16 Mo max) ou des octets fournis par l'IA (5 Mo max). Autorisés : photos (JPEG, PNG, WebP), notes vocales (OGG/Opus), vidéos MP4 et 3GP/MOV, PDF, fichiers Office et OpenDocument sans macros, RTF, TXT, CSV, GIF, audio. Programmes, scripts, pages web, archives et fichiers à macros sont refusés ; les premiers octets doivent correspondre au type.
- Un fichier compte comme un message pour toutes les limites. Transférer à quelqu'un d'autre un fichier qu'une personne vous a envoyé demande votre accord explicite.
- WhatsApp garde les fichiers un temps limité : un vieux fichier peut répondre `ATTACHMENT_EXPIRED`.