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

# Получаване на статус на сесията

> Проверка на статуса на 24-часовия прозорец за съобщения за WhatsApp разговор

Този endpoint проверява дали съществува активен 24-часов прозорец за съобщения между вашия WhatsApp изпращач и конкретен получател. Използвайте го, за да определите дали можете да изпращате [свободни съобщения](/api-reference/whatsapp/send-freeform) или трябва да използвате [шаблонно съобщение](/api-reference/whatsapp/send-template).

### Query параметри

<ParamField query="sender_id" type="integer" required>
  ID на WhatsApp изпращача (получено от endpoint-а [Получаване на изпращачи](/api-reference/whatsapp/get-senders))
</ParamField>

<ParamField query="recipient_phone" type="string" required>
  Телефонният номер на получателя в международен формат (например `+1234567890`)
</ParamField>

### Полета в отговора

<ResponseField name="success" type="boolean">
  Дали заявката е била успешна
</ResponseField>

<ResponseField name="has_conversation" type="boolean">
  Дали съществува разговор с този получател
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  ID на разговора (присъства само когато `has_conversation` е `true`)
</ResponseField>

<ResponseField name="customer_name" type="string">
  Името на клиента, ако е налично (присъства само когато `has_conversation` е `true`)
</ResponseField>

<ResponseField name="last_customer_message_at" type="string">
  ISO 8601 timestamp на последното съобщение на клиента (присъства само когато `has_conversation` е `true`)
</ResponseField>

<ResponseField name="session_status" type="object">
  <Expandable title="Свойства на статуса на сесията">
    <ResponseField name="is_open" type="boolean">
      Дали 24-часовият прозорец за съобщения в момента е отворен
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Дали свободни (не-шаблонни) съобщения могат да бъдат изпращани в момента
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Дали е необходимо шаблонно съобщение за да се изпрати съобщение до този получател
    </ResponseField>

    <ResponseField name="message" type="string">
      Описание на текущото състояние на сесията, четимо от човек
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Оставащи минути в 24-часовия прозорец (присъства само когато сесията е отворена)
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      ISO 8601 timestamp кога сесията изтича (присъства когато сесията е отворена или не съществува съобщение от клиента)
    </ResponseField>

    <ResponseField name="expired_at" type="string">
      ISO 8601 timestamp кога сесията е изтекла (присъства само когато сесията е изтекла)
    </ResponseField>
  </Expandable>
</ResponseField>

### Грешки в отговора

<ResponseField name="404 Not Found">
  <Expandable title="Отговор при грешка">
    <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}
  curl -X GET "https://call.aiployees.com/api/user/whatsapp/session-status?sender_id=12&recipient_phone=+1234567890" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  const response = await fetch(
    `https://call.aiployees.com/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}
  import requests

  response = requests.get(
      'https://call.aiployees.com/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}
  {
    "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}
  {
    "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}
  {
    "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}
  {
    "success": false,
    "error": "Sender not found",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```
</ResponseExample>

### Типичен работен процес

Използвайте този endpoint като част от процеса за изпращане на съобщения:

1. **Проверете статуса на сесията** преди да изпратите съобщение
2. Ако `can_send_freeform` е `true` → използвайте [Изпращане на свободно съобщение](/api-reference/whatsapp/send-freeform)
3. Ако `requires_template` е `true` → използвайте [Изпращане на шаблонно съобщение](/api-reference/whatsapp/send-template)

### Забележки

* 24-часовият прозорец се базира на timestamp-а на последното входящо съобщение от клиента.
* Всяко ново съобщение от клиента нулира 24-часовия таймер.
* Този endpoint не консумира никакъв баланс — това е само проверка на статуса за четене.

***