VoxLink.ai
Start Free

API Reference

Get Session Status

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

Updated 24 Mar 2026
On this page

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 or need to use a template message.

Query Parameters

sender_idintegerrequired

The ID of the WhatsApp sender (obtained from the Get Senders endpoint)

recipient_phonestringrequired

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

Response Fields

successboolean

Whether the request was successful

has_conversationboolean

Whether a conversation exists with this recipient

conversation_idinteger

The conversation ID (only present when has_conversation is true)

customer_namestring

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

last_customer_message_atstring

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

session_statusobject

is_openboolean

  Whether the 24-hour messaging window is currently open

can_send_freeformboolean

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

requires_templateboolean

  Whether a template message is required to message this recipient

messagestring

  Human-readable description of the current session state

minutes_remaininginteger

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

expires_atstring

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

expired_atstring

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

Error Responses

404 Not Found

successboolean

false

errorstring

Sender not found

error_codestring

SENDER_NOT_FOUND

curl -X GET "https://app.voxlink.ai/api/user/whatsapp/session-status?sender_id=12&recipient_phone=+1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  sender_id: '12',
  recipient_phone: '+1234567890'
});

const response = await fetch(
  `https://app.voxlink.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');
}

import requests

response = requests.get(
    'https://app.voxlink.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')

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

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

{
  "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."
  }
}

{
  "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
  3. If requires_template is true → use Send Template Message

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.

Related guides

API Reference

Introduction

Welcome to the VoxLink API

Read guide →

API Reference

Authentication

Learn how to authenticate your API requests

Read guide →

API Reference

Get current user

Get the authenticated user's profile information

Read guide →

API Reference

List assistants

List all assistants for the authenticated user with pagination

Read guide →