> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lacy.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](https://docs.lacy.ai/api-reference/whatsapp/send-freeform.md) or need to use a [template message](https://docs.lacy.ai/api-reference/whatsapp/send-template.md).

### Query Parameters

**sender\_id** `integer` *required*

The ID of the WhatsApp sender (obtained from the [Get Senders](https://docs.lacy.ai/api-reference/whatsapp/get-senders.md) endpoint)

**recipient\_phone** `string` *required*

The recipient's phone number in international format (e.g., `+1234567890`)

### Response Fields

**success** `boolean`

Whether the request was successful

**has\_conversation** `boolean`

Whether a conversation exists with this recipient

**conversation\_id** `integer`

The conversation ID (only present when `has_conversation` is `true`)

**customer\_name** `string`

The customer's name if available (only present when `has_conversation` is `true`)

**last\_customer\_message\_at** `string`

ISO 8601 timestamp of the customer's last message (only present when `has_conversation` is `true`)

**session\_status** `object`

**Session status properties**

**is\_open** `boolean`

Whether the 24-hour messaging window is currently open

**can\_send\_freeform** `boolean`

Whether freeform (non-template) messages can be sent right now

**requires\_template** `boolean`

Whether a template message is required to message this recipient

**message** `string`

Human-readable description of the current session state

**minutes\_remaining** `integer`

Minutes remaining in the 24-hour window (only present when session is open)

**expires\_at** `string`

ISO 8601 timestamp when the session expires (present when session is open or no customer message exists)

**expired\_at** `string`

ISO 8601 timestamp when the session expired (only present when session has expired)

### Error Responses

**404 Not Found**

**Error Response**

**success** `boolean`

`false`

**error** `string`

`Sender not found`

**error\_code** `string`

`SENDER_NOT_FOUND`

```bash cURL theme={null}
curl -X GET "https://app.lacy.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.lacy.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.lacy.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')
```

```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"
}
```

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.