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

# Criar Sessão

> Cria uma nova sessão do WhatsApp

Cria uma nova sessão que pode ser conectada a uma conta do WhatsApp.

<Note>
  A sessão é criada com status `disconnected`. Você precisa chamar o endpoint de [conectar](/api-reference/sessions/connect) para obter o QR Code.
</Note>

## Request Body

<ParamField body="name" type="string" required>
  Nome identificador da sessão. Deve ser único dentro do tenant.

  **Exemplo:** `"atendimento-principal"`
</ParamField>

<ParamField body="allowGroup" default="true" type="boolean">
  Se a sessão deve processar mensagens de grupos.
</ParamField>

<ParamField body="webhookUrl" type="string">
  URL que receberá eventos via webhook (HTTPS obrigatório em produção).

  **Exemplo:** `"https://seu-servidor.com/webhook"`
</ParamField>

<ParamField body="webhookEvents" type="string[]">
  Lista de eventos que o webhook receberá. Se não especificado, recebe todos.

  **Valores possíveis:**

  * `message.received`
  * `message.sent`
  * `message.status`
  * `session.connected`
  * `session.disconnected`
</ParamField>

<ParamField body="webhookSecret" type="string">
  Secret para validação de assinatura dos webhooks.
</ParamField>

## Resposta

<ResponseField name="id" type="string">
  ID único da sessão (UUID).
</ResponseField>

<ResponseField name="name" type="string">
  Nome da sessão.
</ResponseField>

<ResponseField name="status" type="string">
  Status atual da sessão (`disconnected`).
</ResponseField>

<ResponseField name="allowGroup" type="boolean">
  Se mensagens de grupo estão habilitadas.
</ResponseField>

<ResponseField name="webhookUrl" type="string">
  URL do webhook configurado.
</ResponseField>

<ResponseField name="hasWebhook" type="boolean">
  Se há webhook configurado.
</ResponseField>

<ResponseField name="createdAt" type="string">
  Data de criação (ISO 8601).
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST "https://api.oxenty.api.br/api/sessions" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "atendimento-principal",
      "allowGroup": true,
      "webhookUrl": "https://seu-servidor.com/webhook",
      "webhookEvents": ["message.received", "message.status"]
    }'
  ```

  ```typescript TypeScript theme={"system"}
  const session = await client.sessions.create({
    name: 'atendimento-principal',
    allowGroup: true,
    webhookUrl: 'https://seu-servidor.com/webhook',
    webhookEvents: ['message.received', 'message.status'],
  });
  ```

  ```python Python theme={"system"}
  session = client.sessions.create(
      name='atendimento-principal',
      allow_group=True,
      webhook_url='https://seu-servidor.com/webhook',
      webhook_events=['message.received', 'message.status']
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={"system"}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "atendimento-principal",
    "status": "disconnected",
    "allowGroup": true,
    "webhookUrl": "https://seu-servidor.com/webhook",
    "webhookEvents": ["message.received", "message.status"],
    "hasWebhook": true,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
  ```

  ```json 400 Bad Request theme={"system"}
  {
    "statusCode": 400,
    "error": "VALIDATION_ERROR",
    "message": "O campo 'name' é obrigatório"
  }
  ```

  ```json 409 Conflict theme={"system"}
  {
    "statusCode": 409,
    "error": "SESSION_ALREADY_EXISTS",
    "message": "Já existe uma sessão com o nome 'atendimento-principal'"
  }
  ```

  ```json 403 Forbidden theme={"system"}
  {
    "statusCode": 403,
    "error": "SESSION_LIMIT_REACHED",
    "message": "Limite de sessões do plano atingido (3/3)"
  }
  ```
</ResponseExample>