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

# Get Session Status

> Check the 24-hour messaging window status for a WhatsApp conversation

This endpoint checks whether an active 24-hour messaging window exists between your WhatsApp sender and a specific recipient. Use this to determine whether you can send [freeform messages](/api-reference/whatsapp/send-freeform) or need to use a [template message](/api-reference/whatsapp/send-template).

### Query Parameters

<ParamField query="sender_id" type="integer" required>
  The ID of the WhatsApp sender (obtained from the [Get Senders](/api-reference/whatsapp/get-senders) endpoint)
</ParamField>

<ParamField query="recipient_phone" type="string" required>
  The recipient's phone number in international format (e.g., `+1234567890`)
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="has_conversation" type="boolean">
  Whether a conversation exists with this recipient
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  The conversation ID (only present when `has_conversation` is `true`)
</ResponseField>

<ResponseField name="customer_name" type="string">
  The customer's name if available (only present when `has_conversation` is `true`)
</ResponseField>

<ResponseField name="last_customer_message_at" type="string">
  ISO 8601 timestamp of the customer's last message (only present when `has_conversation` is `true`)
</ResponseField>

<ResponseField name="session_status" type="object">
  <Expandable title="Session status properties">
    <ResponseField name="is_open" type="boolean">
      Whether the 24-hour messaging window is currently open
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Whether freeform (non-template) messages can be sent right now
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Whether a template message is required to message this recipient
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable description of the current session state
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Minutes remaining in the 24-hour window (only present when session is open)
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      ISO 8601 timestamp when the session expires (present when session is open or no customer message exists)
    </ResponseField>

    <ResponseField name="expired_at" type="string">
      ISO 8601 timestamp when the session expired (only present when session has expired)
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<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}
  curl -X GET "https://app.autocalls.ai/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://app.autocalls.ai/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://app.autocalls.ai/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>

### 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](/api-reference/whatsapp/send-freeform)
3. If `requires_template` is `true` → use [Send Template Message](/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.