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

# Start Session

> Start a new WhatsApp session

## Description

This endpoint initializes a new WhatsApp session. After starting the session, you will need to authenticate it using the QR Code or pairing code. You can provide custom configurations for the session storage and logs.

## URL Parameters

<ParamField path="session" type="string" required>
  Unique session ID to be started
</ParamField>

## Body

```json theme={null}
{
  "config": {
    "store": {
      "dialect": "sqlite3",
      "address": "/app/data/whatsmeow.db"
    },
    "log": {
      "level": "INFO"
    }
  }
}
```

### Body Parameters

| Property               | Type     | Required | Description                                                   |
| ---------------------- | -------- | -------- | ------------------------------------------------------------- |
| `config`               | `object` | ❌ No     | Optional session configurations                               |
| `config.store`         | `object` | ❌ No     | Session storage configurations                                |
| `config.store.dialect` | `string` | ❌ No     | Database type (default: "sqlite3")                            |
| `config.store.address` | `string` | ❌ No     | Database file path (default: "/app/data/whatsmeow\.db")       |
| `config.log`           | `object` | ❌ No     | Session log configurations                                    |
| `config.log.level`     | `string` | ❌ No     | Log level: "DEBUG", "INFO", "WARN", "ERROR" (default: "INFO") |

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "message": "Session started successfully",
    "session": "my-session"
  }
  ```
</ResponseExample>

## Status Codes

* `200` - Session started successfully
* `400` - Invalid parameters
* `409` - Session already exists and is active

## Usage Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.com.br/api/sessions/my-session/start \
    -H "Content-Type: application/json" \
    -d '{
      "config": {
        "store": {
          "dialect": "sqlite3",
          "address": "/app/data/whatsmeow.db"
        },
        "log": {
          "level": "INFO"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const session = 'my-session';
  const response = await fetch(`https://api.wappfy.com.br/api/sessions/${session}/start`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      config: {
        store: {
          dialect: 'sqlite3',
          address: '/app/data/whatsmeow.db'
        },
        log: {
          level: 'INFO'
        }
      }
    })
  });
  const data = await response.json();
  console.log(data);
  ```

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

  session = 'my-session'
  response = requests.post(
      f'https://api.wappfy.com.br/api/sessions/{session}/start',
      json={
          'config': {
              'store': {
                  'dialect': 'sqlite3',
                  'address': '/app/data/whatsmeow.db'
              },
              'log': {
                  'level': 'INFO'
              }
          }
      }
  )
  data = response.json()
  print(data)
  ```
</CodeGroup>


## OpenAPI

````yaml viewer-en.json post /api/sessions/{session}/start
openapi: 3.1.0
info:
  title: Wappfy - WhatsApp HTTP API
  version: '2.0'
  contact: {}
servers:
  - url: https://{host}
    description: Customizable Server
    variables:
      host:
        default: api.wappfy.com.br
        description: Server URL (e.g., api.wappfy.com.br or your-server.com)
security:
  - api_key: []
tags:
  - name: 🖥️ Sessions
    description: Control WhatsApp sessions (accounts)
  - name: 🔑 Auth
    description: Authentication
  - name: 🆔 Profile
    description: Your profile information
  - name: 🖼️ Screenshot
    description: Get WhatsApp screenshot and display QR code
  - name: 📤 Chatting
    description: Conversation methods
  - name: 📢 Channels
    description: Channels (newsletters) methods
  - name: 🟢 Status
    description: Status (aka stories) methods
  - name: 💬 Chats
    description: Conversations methods
  - name: 👤 Contacts
    description: |-
      Contacts methods.<br>
                      Use phone number (without +) or phone number and `@c.us` at the end as `contactId`.<br>
                      E.g: `12312312310` OR `12312312310@c.us`<br>
  - name: 👥 Groups
    description: Groups methods.<br>
  - name: ✅ Presence
    description: Presence information
  - name: 📅 Events
    description: Event Message
  - name: 🏷️ Labels
    description: Labels - available only for WhatsApp Business accounts
  - name: 🔍 Observability
    description: Other methods
  - name: 🗄️ Storage
    description: Storage methods
externalDocs:
  description: Wappfy - WhatsApp API
  url: https://docs.wappfy.com.br/
paths:
  /api/sessions/{session}/start:
    post:
      tags:
        - 🖥️ Sessions
      summary: Start the session
      description: >-
        Start the session with the given name. The session must exist.
        Idempotent operation. The {session} parameter must be the session's
        instanceName.
      operationId: SessionsController_start
      parameters:
        - name: session
          required: true
          in: path
          description: The session name (instanceName) you want to start
          example: my-session
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties: {}
            example: {}
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionDTO'
      security:
        - api_key: []
components:
  schemas:
    SessionDTO:
      type: object
      properties:
        name:
          type: string
          example: my-session
          description: Session name (instanceName)
        status:
          enum:
            - STOPPED
            - STARTING
            - SCAN_QR_CODE
            - WORKING
            - FAILED
          type: string
        config:
          $ref: '#/components/schemas/SessionConfig'
      required:
        - name
        - status
    SessionConfig:
      type: object
      properties:
        metadata:
          example:
            user.id: '123'
            user.email: email@example.com
          description: Metadata for the session. You'll get 'metadata' in all webhooks.
          allOf:
            - $ref: '#/components/schemas/Map'
        proxy:
          example: null
          allOf:
            - $ref: '#/components/schemas/ProxyConfig'
        debug:
          type: boolean
          default: false
        noweb:
          example:
            store:
              enabled: true
              fullSync: false
          allOf:
            - $ref: '#/components/schemas/NowebConfig'
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/WebhookConfig'
    Map:
      type: object
      properties: {}
    ProxyConfig:
      type: object
      properties:
        server:
          type: string
          example: localhost:3128
        username:
          type: string
          example: null
        password:
          type: string
          example: null
      required:
        - server
    NowebConfig:
      type: object
      properties:
        markOnline:
          type: boolean
          default: true
          description: Mark the session as online when it connects to the server.
        store:
          $ref: '#/components/schemas/NowebStoreConfig'
      required:
        - markOnline
    WebhookConfig:
      type: object
      properties:
        url:
          type: string
          example: https://webhook.site/11111111-1111-1111-1111-11111111
          description: >-
            You can use https://docs.webhook.site/ to test webhooks and see the
            payload
        events:
          example:
            - message
            - session.status
          type: array
          items:
            type: object
        hmac:
          example: null
          allOf:
            - $ref: '#/components/schemas/HmacConfiguration'
        retries:
          example: null
          allOf:
            - $ref: '#/components/schemas/RetriesConfiguration'
        customHeaders:
          example: null
          type: array
          items:
            $ref: '#/components/schemas/CustomHeader'
      required:
        - url
        - events
    NowebStoreConfig:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
          description: Enable or disable the store for contacts, chats, and messages.
          example: true
        fullSync:
          type: boolean
          default: false
          description: >-
            Enable full sync on session initialization (when scanning QR code).

            Full sync will download all contacts, chats, and messages from the
            phone.

            If disabled, only messages early than 90 days will be downloaded and
            some contacts may be missing.
      required:
        - enabled
        - fullSync
    HmacConfiguration:
      type: object
      properties:
        key:
          type: string
          example: your-secret-key
    RetriesConfiguration:
      type: object
      properties:
        delaySeconds:
          type: number
          example: 2
        attempts:
          type: number
          example: 15
        policy:
          enum:
            - linear
            - exponential
            - constant
          type: string
          example: linear
    CustomHeader:
      type: object
      properties:
        name:
          type: string
          example: X-My-Custom-Header
        value:
          type: string
          example: Value
      required:
        - name
        - value
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: apikey
      description: Your Wappfy API key (get it at dash.wappfy.com.br)

````