> ## 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.

# WhatsApp-Session-Status abrufen

> Prüfen, ob das 24-Stunden-Messaging-Fenster für eine WhatsApp-Konversation über Famulor offen ist

# WhatsApp-Session-Status abrufen

> Den Status des 24-Stunden-Messaging-Fensters für eine WhatsApp-Konversation prüfen

Dieser Endpunkt prüft, ob ein aktives 24-Stunden-Messaging-Fenster zwischen deinem WhatsApp-Sender und einem bestimmten Empfänger besteht. Verwende ihn, um zu entscheiden, ob du [Freiform-Nachrichten](/de/api-reference/whatsapp/send-freeform) senden kannst oder zunächst eine [Template-Nachricht](/de/api-reference/whatsapp/send-template) nutzen musst.

### Query-Parameter

<ParamField query="sender_id" type="integer" required>
  Die ID des WhatsApp-Senders (erhalten über [WhatsApp-Sender abrufen](/de/api-reference/whatsapp/get-senders))
</ParamField>

<ParamField query="recipient_phone" type="string" required>
  Die Telefonnummer des Empfängers im internationalen Format (z.B. `+1234567890`)
</ParamField>

### Antwort-Felder

<ResponseField name="success" type="boolean">
  Ob die Anfrage erfolgreich war
</ResponseField>

<ResponseField name="has_conversation" type="boolean">
  Ob bereits eine Konversation mit diesem Empfänger existiert
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  Die Konversations-ID (nur vorhanden, wenn `has_conversation` `true` ist)
</ResponseField>

<ResponseField name="customer_name" type="string">
  Der Name des Kunden, sofern verfügbar (nur vorhanden, wenn `has_conversation` `true` ist)
</ResponseField>

<ResponseField name="last_customer_message_at" type="string">
  ISO-8601-Timestamp der letzten Nachricht des Kunden (nur vorhanden, wenn `has_conversation` `true` ist)
</ResponseField>

<ResponseField name="session_status" type="object">
  <Expandable title="Session-Status Eigenschaften">
    <ResponseField name="is_open" type="boolean">
      Ob das 24-Stunden-Messaging-Fenster aktuell geöffnet ist
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Ob derzeit Freiform- (nicht-Template-) Nachrichten gesendet werden können
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Ob eine Template-Nachricht erforderlich ist, um diesen Empfänger zu kontaktieren
    </ResponseField>

    <ResponseField name="message" type="string">
      Menschlich lesbare Beschreibung des aktuellen Session-Status
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Verbleibende Minuten im 24-Stunden-Fenster (nur vorhanden, wenn die Session geöffnet ist)
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      ISO-8601-Timestamp, wann die Session abläuft (vorhanden, wenn die Session geöffnet ist oder noch keine Kundennachricht existiert)
    </ResponseField>

    <ResponseField name="expired_at" type="string">
      ISO-8601-Timestamp, wann die Session abgelaufen ist (nur vorhanden, wenn die Session bereits abgelaufen ist)
    </ResponseField>
  </Expandable>
</ResponseField>

### Fehler-Antworten

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://app.famulor.de/api/user/whatsapp/session-status?sender_id=12&recipient_phone=+1234567890" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null} theme={null}
  const params = new URLSearchParams({
    sender_id: '12',
    recipient_phone: '+1234567890'
  });

  const response = await fetch(
    `https://app.famulor.de/api/user/whatsapp/session-status?${params}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  if (data.session_status.can_send_freeform) {
    console.log('Session is active — freeform messages allowed');
  } else {
    console.log('Session expired — use a template message');
  }
  ```

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

  response = requests.get(
      'https://app.famulor.de/api/user/whatsapp/session-status',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'sender_id': 12,
          'recipient_phone': '+1234567890'
      }
  )

  data = response.json()
  session = data['session_status']

  if session['can_send_freeform']:
      print('Session is active — freeform messages allowed')
  else:
      print('Session expired — use a template message')
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Active Session theme={null} theme={null}
  {
    "success": true,
    "has_conversation": true,
    "conversation_id": 1234,
    "customer_name": "John Doe",
    "last_customer_message_at": "2026-02-24T10:30:00+00:00",
    "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 200 Expired Session theme={null} theme={null}
  {
    "success": true,
    "has_conversation": true,
    "conversation_id": 1234,
    "customer_name": "John Doe",
    "last_customer_message_at": "2026-02-22T14:00:00+00:00",
    "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-23T14:00:00+00:00"
    }
  }
  ```

  ```json 200 No Conversation theme={null} theme={null}
  {
    "success": true,
    "has_conversation": false,
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "No conversation exists with this recipient. Send a template message first."
    }
  }
  ```

  ```json 404 Sender Not Found theme={null} theme={null}
  {
    "success": false,
    "error": "Sender not found",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```
</ResponseExample>

### Typical Workflow

Use this endpoint as part of a message-sending flow:

1. **Check session status** before sending a message
2. If `can_send_freeform` is `true` → use [Send Freeform Message](/de/api-reference/whatsapp/send-freeform)
3. If `requires_template` is `true` → use [Send Template Message](/de/api-reference/whatsapp/send-template)

### Notes

* The 24-hour window is based on the customer's last inbound message timestamp.
* Each new customer message resets the 24-hour timer.
* This endpoint does not consume any balance — it's a read-only status check.