> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Envoyer un message WhatsApp libre

> Envoie un message WhatsApp en texte libre au sein d'une session active de 24 heures via Famulor

<Warning>
  **API Famulor 1.0 (héritée).** Cette page concerne uniquement Famulor 1.0 (`app.famulor.de`) et est conservée pour la compatibilité. Pour la plateforme actuelle, consultez la [référence API Famulor 2.0](/fr/api-reference/introduction).
</Warning>

Envoie un message WhatsApp libre (texte libre) à un destinataire à l'aide de votre expéditeur WhatsApp Famulor. Contrairement aux messages modèles, les messages libres peuvent contenir n'importe quel texte, mais **nécessitent une fenêtre de messagerie de 24 heures active** — c'est-à-dire que le destinataire doit avoir envoyé un message à votre expéditeur WhatsApp au cours des dernières 24 heures.

<Warning>
  Les messages libres ne peuvent être envoyés que pendant une fenêtre de messagerie de 24 heures active. Si la session a expiré, vous devez d'abord envoyer un [message modèle](/fr/api-v1/whatsapp/send-template) pour relancer la conversation. Utilisez le point de terminaison [Statut de session](/fr/api-v1/whatsapp/session-status) pour vérifier si une session est active.
</Warning>

<Note>
  Ce point de terminaison est limité à **5 requêtes par seconde** par utilisateur.
</Note>

### Corps de la requête

<ParamField body="sender_id" type="integer" required>
  L'ID de l'expéditeur WhatsApp depuis lequel envoyer (obtenu via le point de terminaison [Récupérer les expéditeurs](/fr/api-v1/whatsapp/get-senders))
</ParamField>

<ParamField body="recipient_phone" type="string" required>
  Le numéro de téléphone du destinataire au format international (par ex. `+1234567890`)
</ParamField>

<ParamField body="message" type="string" required>
  Le contenu du message à envoyer (4096 caractères maximum)
</ParamField>

### Champs de réponse

<ResponseField name="success" type="boolean">
  Indique si le message a été envoyé avec succès
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  L'ID de la conversation associée à ce message
</ResponseField>

<ResponseField name="message_id" type="integer">
  L'ID de l'enregistrement du message de conversation
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  L'ID de l'enregistrement du message WhatsApp
</ResponseField>

<ResponseField name="message_sid" type="string">
  Le SID de message Twilio pour le suivi de la livraison
</ResponseField>

<ResponseField name="session_status" type="object">
  Statut de session mis à jour après l'envoi du message

  <Expandable title="Propriétés du statut de session">
    <ResponseField name="is_open" type="boolean">
      Indique si la fenêtre de messagerie de 24 heures est actuellement ouverte
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Indique si des messages libres peuvent être envoyés dès maintenant
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Indique si un message modèle est requis
    </ResponseField>

    <ResponseField name="message" type="string">
      Description lisible de l'état de la session
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Minutes restantes dans la fenêtre de 24 heures
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      Horodatage ISO 8601 de l'expiration de la session
    </ResponseField>
  </Expandable>
</ResponseField>

### Réponses d'erreur

<ResponseField name="402 Insufficient Balance">
  <Expandable title="Réponse d'erreur">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Insufficient balance. Please top up your account.`</ResponseField>
    <ResponseField name="error_code" type="string">`INSUFFICIENT_BALANCE`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="403 Session Expired">
  <Expandable title="Réponse d'erreur">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Message indiquant que la fenêtre de messagerie de 24 heures a expiré</ResponseField>
    <ResponseField name="error_code" type="string">`SESSION_EXPIRED`</ResponseField>

    <ResponseField name="session_status" type="object">
      Statut de session actuel avec les champs `is_open`, `can_send_freeform`, `requires_template` et `message`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Not Found">
  <Expandable title="Réponse d'erreur">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found or does not belong to you`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="503 Sender Offline">
  <Expandable title="Réponse d'erreur">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Message indiquant que l'expéditeur est actuellement hors ligne</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_OFFLINE`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl -X POST "https://app.famulor.de/api/user/whatsapp/send-freeform" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "recipient_phone": "+1234567890",
      "message": "Thank you for your inquiry! Our team will review your request and get back to you within 2 hours."
    }'
  ```

  ```javascript JavaScript theme={null} theme={null}
  const response = await fetch(
    'https://app.famulor.de/api/user/whatsapp/send-freeform',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sender_id: 12,
        recipient_phone: '+1234567890',
        message: 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null} theme={null}
  import requests

  response = requests.post(
      'https://app.famulor.de/api/user/whatsapp/send-freeform',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'recipient_phone': '+1234567890',
          'message': 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      }
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null} theme={null}
  {
    "success": true,
    "conversation_id": 1234,
    "message_id": 567,
    "whatsapp_message_id": 890,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "session_status": {
      "is_open": true,
      "can_send_freeform": true,
      "requires_template": false,
      "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.",
      "minutes_remaining": 1425,
      "expires_at": "2026-02-25T10:30:00+00:00"
    }
  }
  ```

  ```json 402 Insufficient Balance theme={null} theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 403 Session Expired theme={null} theme={null}
  {
    "success": false,
    "error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.",
    "error_code": "SESSION_EXPIRED",
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Session expired. Send a template or wait for customer to reply.",
      "expired_at": "2026-02-23T10:30:00+00:00"
    }
  }
  ```

  ```json 404 Sender Not Found theme={null} theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 422 Invalid Phone theme={null} theme={null}
  {
    "success": false,
    "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 503 Sender Offline theme={null} theme={null}
  {
    "success": false,
    "error": "Sender is not online. Current status: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### Fenêtre de messagerie de 24 heures

WhatsApp applique une politique de **fenêtre de messagerie de 24 heures** :

1. Lorsqu'un client envoie un message à votre numéro WhatsApp Business, une fenêtre de 24 heures s'ouvre.
2. Pendant cette fenêtre, vous pouvez envoyer des messages libres sans restriction.
3. Une fois la fenêtre expirée, vous devez utiliser un [message modèle](/fr/api-v1/whatsapp/send-template) pour relancer la conversation.
4. Chaque nouveau message du client réinitialise le minuteur de 24 heures.

Utilisez le point de terminaison [Statut de session](/fr/api-v1/whatsapp/session-status) pour vérifier si une session est active avant d'essayer d'envoyer un message libre.

### Remarques

* La longueur maximale du message est de **4 096 caractères** (limite WhatsApp).
* L'expéditeur doit être `online`. Les expéditeurs hors ligne renvoient une erreur `503`.
* Le coût des messages est automatiquement déduit du solde de votre compte Famulor.
* Limite de débit : 5 requêtes par seconde par utilisateur.