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

# Create a session

> Create or start a WhatsApp session.

A **session** is a WhatsApp number managed by D-API. Use `type:
"unofficial"` for unofficial WhatsApp (via QR code) or `type: "cloud_api"`
for the Official API.

You can set the `webhookUrl` at creation time to receive events in real
time (messages, status, connection). See the [webhooks
documentation](https://docs.d-api.cloud/en/whatsapp/webhooks/visao-geral.md).

> [!TIP]
>
> Choose a stable, unique `sessionId` per number — it is used in
> virtually every other endpoint.


## OpenAPI

````yaml api-reference/openapi.en.json POST /api/v1/sessions
openapi: 3.1.0
info:
  title: D-API - Complete WhatsApp Infrastructure
  description: >-
    A scalable, robust solution for automation managers, SaaS products and end
    users who need a reliable WhatsApp integration. It offers multiple
    simultaneous instances, real-time webhooks, an intuitive dashboard and a
    documented REST API with 99.9% uptime and latency under 30ms.
  version: 1.2.1
  contact:
    name: Suporte D-API
    email: suporte@d-api.cloud
    url: https://d-api.cloud
servers:
  - url: https://api.d-api.cloud
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Home
    description: Base endpoints
  - name: Sessions
    description: Endpoints for managing sessions
  - name: Messages
    description: Endpoints for sending messages
  - name: Cloud API
    description: >-
      WhatsApp Official API (Meta Cloud API): manual connection, template
      management (list/create/delete) and template sending.
  - name: IVR Calls
    description: 'Voice call dispatch (IVR): single or bulk, with audio or an IVR flow.'
  - name: SMS
    description: 'SMS sending: single or bulk.'
  - name: Commands
    description: >-
      Look up asynchronous commands (async: true) by the commandId returned when
      enqueued.
paths:
  /api/v1/sessions:
    post:
      tags:
        - Sessions
      summary: Create or start a WhatsApp session
      description: >-
        Creates an unofficial WhatsApp connection or starts an existing one. For
        the Official API, use the Cloud API connection routes.
      operationId: postApiV1Sessions
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sessionId
              properties:
                sessionId:
                  type: string
                  minLength: 1
                  description: >-
                    Connection identifier you choose. Use the same value in the
                    other routes.
                connectionMode:
                  type: string
                  enum:
                    - qr
                    - pair
                  default: qr
                  description: >-
                    How to pair the number: `qr` (QR code) or `pair` (pairing
                    code).
                pairPhone:
                  type: string
                  description: >-
                    Number to pair, with country code, digits only. Required
                    when `connectionMode` is `pair`.
                webhookUrl:
                  type: string
                  description: >-
                    URL that receives the connection's events (messages,
                    statuses, calls).
                webhookConfig:
                  type: object
                  required:
                    - enabled
                    - type
                    - events
                  description: >-
                    Which events the webhook receives and at which URL. A
                    missing event or one with `enabled: false` is not sent.
                  properties:
                    enabled:
                      type: boolean
                      description: Turns on event delivery by webhook.
                    type:
                      type: string
                      enum:
                        - single
                        - per_event
                      description: >-
                        `single`: every event goes to the same URL. `per_event`:
                        each event has its own `webhookUrl`.
                    events:
                      type: object
                      description: One entry per event type.
                      properties:
                        messages.received:
                          type: object
                          description: Message received.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        messages.sent:
                          type: object
                          description: >-
                            Message sent by the connection (API, panel or
                            phone).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        message.delivered:
                          type: object
                          description: Message delivered to the recipient.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        message.read:
                          type: object
                          description: Message read by the recipient.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        message.update:
                          type: object
                          description: Message edited or status changed.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        message.deleted:
                          type: object
                          description: Message deleted.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        contacts.upsert:
                          type: object
                          description: New contact.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        contacts.update:
                          type: object
                          description: Contact updated (name, picture).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        chats.upsert:
                          type: object
                          description: New chat.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        chats.update:
                          type: object
                          description: Chat updated (archived, pinned, muted).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        presence:
                          type: object
                          description: Typing, recording audio, online.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        groups_participants.join:
                          type: object
                          description: Participant joined the group.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        groups_participants.leave:
                          type: object
                          description: Participant left or was removed from the group.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        groups_participants.promote:
                          type: object
                          description: Participant became admin.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        groups_participants.demote:
                          type: object
                          description: Participant is no longer admin.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        group_participants.join-request:
                          type: object
                          description: Request to join the group.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        group_participants.join-request.approved:
                          type: object
                          description: Join request approved.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        group_participants.join-request.revoked:
                          type: object
                          description: Join request revoked.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        labels.edit:
                          type: object
                          description: Label created, edited or deleted.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        labels.association.chat:
                          type: object
                          description: Label added to or removed from a chat.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        labels.association.message:
                          type: object
                          description: Label added to or removed from a message.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        appstate.label.edit:
                          type: object
                          description: Label changed (raw WhatsApp event).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        appstate.label.association.chat:
                          type: object
                          description: Chat label (raw WhatsApp event).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        appstate.label.association.message:
                          type: object
                          description: Message label (raw WhatsApp event).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        appstate.agent.update:
                          type: object
                          description: WhatsApp Business agent changed (raw event).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        history_sync:
                          type: object
                          description: History sync progress (requires historySync).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        history.message.upsert:
                          type: object
                          description: Message from the synced history.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        history.message.received:
                          type: object
                          description: Received message from the history.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        history.messages.sent:
                          type: object
                          description: Sent message from the history.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        connection.qrcode:
                          type: object
                          description: New QR code to pair.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        connection.paircode:
                          type: object
                          description: Pairing code (connectionMode pair).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        connection.status:
                          type: object
                          description: Connection status changed (connected, disconnected).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        logged_out:
                          type: object
                          description: The number was logged out from the device.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        call.offer:
                          type: object
                          description: Incoming call ringing (requires receiveCalls).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        call.accepted:
                          type: object
                          description: Incoming call answered on another device.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        call.rejected:
                          type: object
                          description: Incoming call rejected.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        call.ringing:
                          type: object
                          description: Placed call is ringing at the destination.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        call.connected:
                          type: object
                          description: Call answered, audio live.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        call.ended:
                          type: object
                          description: Call ended.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        call.not_answered:
                          type: object
                          description: Placed call was not answered.
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                        call.audio:
                          type: object
                          description: >-
                            Call audio chunks (high volume; enable only to
                            record).
                          required:
                            - enabled
                            - webhookUrl
                          properties:
                            enabled:
                              type: boolean
                            webhookUrl:
                              type: string
                ignoreGroups:
                  type: boolean
                  default: true
                  description: Doesn't send events for group messages.
                ignoreStatus:
                  type: boolean
                  default: true
                  description: Doesn't send status (stories) events.
                historySync:
                  type: boolean
                  default: false
                  description: Syncs the device's chat history on connect.
                receiveCalls:
                  type: boolean
                  default: false
                  description: >-
                    Receives calls made to the number (`call.offer` events) to
                    answer or reject through the API.
            example:
              sessionId: teste-12345
              connectionMode: qr
              webhookUrl: https://seu.webhook.com
              webhookConfig:
                enabled: true
                type: single
                events:
                  messages.received:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  messages.sent:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  message.delivered:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  message.read:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  message.update:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  message.deleted:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  contacts.upsert:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  contacts.update:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  chats.upsert:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  chats.update:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  presence:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  groups_participants.join:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  groups_participants.leave:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  groups_participants.promote:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  groups_participants.demote:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  group_participants.join-request:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  group_participants.join-request.approved:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  group_participants.join-request.revoked:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  labels.edit:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  labels.association.chat:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  labels.association.message:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  appstate.label.edit:
                    enabled: false
                    webhookUrl: https://seu.webhook.com
                  appstate.label.association.chat:
                    enabled: false
                    webhookUrl: https://seu.webhook.com
                  appstate.label.association.message:
                    enabled: false
                    webhookUrl: https://seu.webhook.com
                  appstate.agent.update:
                    enabled: false
                    webhookUrl: https://seu.webhook.com
                  history_sync:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  history.message.upsert:
                    enabled: false
                    webhookUrl: https://seu.webhook.com
                  history.message.received:
                    enabled: false
                    webhookUrl: https://seu.webhook.com
                  history.messages.sent:
                    enabled: false
                    webhookUrl: https://seu.webhook.com
                  connection.qrcode:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  connection.paircode:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  connection.status:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  logged_out:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  call.offer:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  call.accepted:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  call.rejected:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  call.ringing:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  call.connected:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  call.ended:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  call.not_answered:
                    enabled: true
                    webhookUrl: https://seu.webhook.com
                  call.audio:
                    enabled: false
                    webhookUrl: https://seu.webhook.com
              ignoreGroups: true
              ignoreStatus: true
              historySync: true
      responses:
        '200':
          description: Successful response
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key for authentication. Format: <API_KEY>'

````

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