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

# Obter Status da Sessão

> Verificar o status da janela de mensagens de 24 horas para uma conversa do WhatsApp

Este endpoint verifica se existe uma janela de mensagens ativa de 24 horas entre seu remetente WhatsApp e um destinatário específico. Use isto para determinar se você pode enviar [mensagens livres](/api-reference/whatsapp/send-freeform) ou precisa usar uma [mensagem de template](/api-reference/whatsapp/send-template).

### Parâmetros de Query

<ParamField query="sender_id" type="integer" required>
  O ID do remetente WhatsApp (obtido do endpoint [Obter Remetentes](/api-reference/whatsapp/get-senders))
</ParamField>

<ParamField query="recipient_phone" type="string" required>
  O número de telefone do destinatário em formato internacional (ex: `+1234567890`)
</ParamField>

### Campos da Resposta

<ResponseField name="success" type="boolean">
  Se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="has_conversation" type="boolean">
  Se existe uma conversa com este destinatário
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  O ID da conversa (presente apenas quando `has_conversation` é `true`)
</ResponseField>

<ResponseField name="customer_name" type="string">
  O nome do cliente se disponível (presente apenas quando `has_conversation` é `true`)
</ResponseField>

<ResponseField name="last_customer_message_at" type="string">
  Timestamp ISO 8601 da última mensagem do cliente (presente apenas quando `has_conversation` é `true`)
</ResponseField>

<ResponseField name="session_status" type="object">
  <Expandable title="Propriedades do status da sessão">
    <ResponseField name="is_open" type="boolean">
      Se a janela de mensagens de 24 horas está atualmente aberta
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Se mensagens livres (não-template) podem ser enviadas agora
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Se uma mensagem de template é necessária para mensagear este destinatário
    </ResponseField>

    <ResponseField name="message" type="string">
      Descrição legível do estado atual da sessão
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Minutos restantes na janela de 24 horas (presente apenas quando a sessão está aberta)
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      Timestamp ISO 8601 de quando a sessão expira (presente quando a sessão está aberta ou nenhuma mensagem do cliente existe)
    </ResponseField>

    <ResponseField name="expired_at" type="string">
      Timestamp ISO 8601 de quando a sessão expirou (presente apenas quando a sessão expirou)
    </ResponseField>
  </Expandable>
</ResponseField>

### Respostas de Erro

<ResponseField name="404 Não Encontrado">
  <Expandable title="Resposta de Erro">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Remetente não encontrado`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://suasofia.online/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://suasofia.online/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('Sessão está ativa — mensagens livres permitidas');
  } else {
    console.log('Sessão expirou — use uma mensagem de template');
  }
  ```

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

  response = requests.get(
      'https://suasofia.online/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('Sessão está ativa — mensagens livres permitidas')
  else:
      print('Sessão expirou — use uma mensagem de template')
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Sessão Ativa theme={null}
  {
    "success": true,
    "has_conversation": true,
    "conversation_id": 1234,
    "customer_name": "João Silva",
    "last_customer_message_at": "2026-02-24T10:30:00+00:00",
    "session_status": {
      "is_open": true,
      "can_send_freeform": true,
      "requires_template": false,
      "message": "Sessão aberta (23 hr 45 min restantes). Mensagens livres ilimitadas permitidas.",
      "minutes_remaining": 1425,
      "expires_at": "2026-02-25T10:30:00+00:00"
    }
  }
  ```

  ```json 200 Sessão Expirada theme={null}
  {
    "success": true,
    "has_conversation": true,
    "conversation_id": 1234,
    "customer_name": "João Silva",
    "last_customer_message_at": "2026-02-22T14:00:00+00:00",
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Sessão expirou. Envie um template ou aguarde o cliente responder.",
      "expired_at": "2026-02-23T14:00:00+00:00"
    }
  }
  ```

  ```json 200 Nenhuma Conversa theme={null}
  {
    "success": true,
    "has_conversation": false,
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Nenhuma conversa existe com este destinatário. Envie uma mensagem de template primeiro."
    }
  }
  ```

  ```json 404 Remetente Não Encontrado theme={null}
  {
    "success": false,
    "error": "Remetente não encontrado",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```
</ResponseExample>

### Fluxo Típico

Use este endpoint como parte de um fluxo de envio de mensagens:

1. **Verificar status da sessão** antes de enviar uma mensagem
2. Se `can_send_freeform` for `true` → use [Enviar Mensagem Livre](/api-reference/whatsapp/send-freeform)
3. Se `requires_template` for `true` → use [Enviar Mensagem de Template](/api-reference/whatsapp/send-template)

### Observações

* A janela de 24 horas é baseada no timestamp da última mensagem recebida do cliente.
* Cada nova mensagem do cliente reinicia o timer de 24 horas.
* Este endpoint não consome nenhum saldo — é apenas uma verificação de status somente leitura.