wapiworld-com Instances API

openapi: 3.2.0
info:
  title: Wapiworld Instances API
  version: 1.0.0
  description: 'Public REST API for Wapiworld — WhatsApp API as a service. Authenticate with an API key created in the Wapiworld dashboard: send the base64-encoded key secret with HTTP Basic auth. Each key is scoped to a single project and carries per-resource scopes like `instances:read` or `instances:write`.'
servers:
- url: https://api.wapiworld.com
tags:
- name: Instances
paths:
  /api/instances:
    get:
      tags:
      - Instances
      summary: List WhatsApp instances
      description: Lists the WhatsApp instances of your organization. An API key is scoped to a single project and only sees that project's instances. Requires the `instances:read` scope.
      security:
      - apiKey: []
      - accessToken: []
      parameters:
      - in: query
        name: projectId
        schema:
          type: string
      - in: query
        name: fields
        description: Comma-separated projection of fields to return
        schema:
          type: string
      - in: query
        name: limit
        description: Optional page size, capped at 500
        schema:
          type: integer
          minimum: 1
          maximum: 500
      - in: query
        name: skip
        description: Optional zero-based page offset
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Array of instances
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Instance'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the `instances:read` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API key rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiInstances
    post:
      tags:
      - Instances
      summary: Create a WhatsApp instance
      description: Creates a new WhatsApp instance in your project. A caller-supplied `_id`, whether in the body or `instanceId` query, requires a stable Idempotency-Key; retrying the same create (including the same write-only webhook signing secret) returns the same resource, while reusing either identity for a different intent returns 409. The first accepted command pins its runtime backend, so an exact retry resumes the same command even if a deployment gate changed meanwhile. Keyed creates reserve the resource in stopped state and must be started with the reconnect action after the caller durably stores the returned id. Unkeyed legacy creates retain their historical auto-start behavior. Requires the `instances:write` scope and emits `instance.created`.
      security:
      - apiKey: []
      - accessToken: []
      parameters:
      - in: header
        name: Idempotency-Key
        required: false
        description: 'Stable 16-128 character key. Required when the request body supplies `_id` or the query supplies `instanceId`; recommended for every automated create.

          '
        schema:
          type: string
          minLength: 16
          maxLength: 128
      - in: header
        name: Wapiworld-Required-Create-Backend-Protocol
        required: false
        description: Fail before reservation unless the selected create backend exactly matches this protocol
        schema:
          type: string
          enum:
          - durable-generation-v1
          - legacy-direct-v1
      - in: query
        name: instanceId
        required: false
        description: Optional caller-supplied 24-character lowercase hex resource id
        schema:
          type: string
          pattern: ^[a-f0-9]{24}$
      responses:
        '200':
          description: The created or exactly replayed instance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the `instances:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The identity/key conflicts, a legacy effect lease is retryably busy, or runtime capacity is full
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API key rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The explicitly required create backend is not currently selected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiInstances
  /api/instances/{instanceId}:
    get:
      tags:
      - Instances
      summary: Get a WhatsApp instance
      description: Returns a single instance by id. Requires the `instances:read` scope. Answers 404 when the instance belongs to another organization or project.
      security:
      - apiKey: []
      - accessToken: []
      parameters:
      - in: path
        name: instanceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The instance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the `instances:read` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API key rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getApiInstancesInstanceId
    put:
      tags:
      - Instances
      summary: Update a WhatsApp instance
      description: Updates an existing instance. A body containing `webhookSigningSecret` is always an atomic durable configuration command and requires a stable Idempotency-Key. Its exact public patch and write-only secret may be replayed until the returned configurationOperation reaches `completed`; changing that intent for the same key returns 409. Requires the `instances:write` scope. May emit `instance.connected` / `instance.disconnected` on a status transition.
      security:
      - apiKey: []
      - accessToken: []
      parameters:
      - in: path
        name: instanceId
        required: true
        schema:
          type: string
      - in: header
        name: Idempotency-Key
        required: false
        description: Required for a body containing webhookSigningSecret; stable 16-128 character operation key
        schema:
          type: string
          minLength: 16
          maxLength: 128
      responses:
        '200':
          description: The updated instance and completed configuration operation, or an ordinary synchronous update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '202':
          description: The atomic configuration command is accepted and awaiting exact runtime acknowledgement
        '403':
          description: API key is missing the `instances:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The idempotency key conflicts or the operation was superseded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API key rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: putApiInstancesInstanceId
    delete:
      tags:
      - Instances
      summary: Delete a WhatsApp instance
      description: Durably requests logout, provider-state purge, and deletion. Repeat the same DELETE to poll the intrinsic `delete:{instanceId}` operation; 202 is pending and 200 includes the immutable completion event. Requires the `instances:write` scope and emits `instance.deleted` exactly once. Answers 404 for an instance in another organization or project.
      security:
      - apiKey: []
      - accessToken: []
      parameters:
      - in: path
        name: instanceId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deletion completed; response includes the stable operation and event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '202':
          description: Deletion was durably accepted and is still pending
        '403':
          description: API key is missing the `instances:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: A transitional create external effect is still in flight; retry without changing intent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API key rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: deleteApiInstancesInstanceId
  /api/instances/{instanceId}/action/send-message-idempotent:
    post:
      tags:
      - Instances
      summary: Send a WhatsApp message with a durable idempotency key
      description: Requires one stable Idempotency-Key and the `instances:write` scope. Reuse the key only for the exact same instance, normalized chat, and content. An exact retry reuses one deterministic WhatsApp message id; changed intent returns 409. The unversioned `send-message` action is legacy and rejects every Idempotency-Key.
      security:
      - apiKey: []
      - accessToken: []
      parameters:
      - in: path
        name: instanceId
        required: true
        schema:
          type: string
      - in: header
        name: Idempotency-Key
        required: true
        description: Required exactly once; retries of one command must reuse the exact value
        schema:
          type: string
          minLength: 16
          maxLength: 128
      responses:
        '200':
          description: The action result from the instance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdempotentSendResult'
        '400':
          description: The Idempotency-Key is present but invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the `instances:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The key conflicts or the WhatsApp account is not currently connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: WhatsApp could not address the recipient; no provider message was attempted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API key rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The keyed-send protocol, recipient lookup, or durable outcome is unavailable; retry the exact command and key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '504':
          description: The send timed out with an ambiguous outcome; retry the exact command and key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiInstancesInstanceIdActionSendMessageIdempotent
  /api/instances/{instanceId}/action/{action}:
    post:
      tags:
      - Instances
      summary: Perform a legacy or non-send action on a WhatsApp instance
      description: Drives actions such as `logout`, `reconnect`, and the legacy unkeyed `send-message`. Every Idempotency-Key is rejected on this route. Use the exact `send-message-idempotent` path for durable keyed sends.
      security:
      - apiKey: []
      - accessToken: []
      parameters:
      - in: path
        name: instanceId
        required: true
        schema:
          type: string
      - in: path
        name: action
        required: true
        schema:
          type: string
          example: send-message
      responses:
        '200':
          description: The action result from the instance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceActionResult'
        '202':
          description: A reconnect was durably accepted for background reconciliation
        '400':
          description: Invalid pairing phone number or an Idempotency-Key on a legacy or non-send action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: API key is missing the `instances:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Reconnect capacity is unavailable, the account is not connected, or the pairing session is unavailable or already paired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: A legacy send could not address the recipient, or WhatsApp rejected phone pairing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: API key or WhatsApp phone-pairing rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: The instance action could not be completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: A retryable recipient lookup is unavailable before a legacy provider message attempt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApiInstancesInstanceIdActionAction
components:
  schemas:
    IdempotentSendResult:
      type: object
      required:
      - key
      - messageTimestamp
      properties:
        key:
          type: object
          required:
          - id
          - remoteJid
          - fromMe
          properties:
            id:
              type: string
            remoteJid:
              type: string
            fromMe:
              type: boolean
          additionalProperties: false
        messageTimestamp:
          type: integer
          format: int64
      additionalProperties: false
    InstanceActionResult:
      description: Action-specific JSON returned by the connected instance, or null when the action has no response body.
      oneOf:
      - type: object
        additionalProperties: true
      - type: array
        items: {}
      - type: string
      - type: boolean
      - type: number
    Instance:
      type: object
      required:
      - _id
      - projectId
      properties:
        _id:
          type: string
        projectId:
          type: string
        name:
          type: string
        status:
          type: string
          description: Current connection status reported by the instance.
        creationTime:
          type: string
          format: date-time
        lastEditTime:
          type: string
          format: date-time
      additionalProperties: true
    Error:
      type: object
      required:
      - message
      - status
      properties:
        details:
          type: object
          additionalProperties: true
          description: Optional structured values needed to render the error.
        message:
          type: string
        method:
          type: string
        name:
          type: string
        status:
          type: integer
        url:
          type: string
          format: uri
  securitySchemes:
    apiKey:
      type: http
      scheme: basic
      description: 'HTTP Basic auth carrying only the API key secret: `Authorization: Basic base64(<key secret>)`.'
    accessToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Operator session token issued by the Wapiworld dashboard: `Authorization: Token <access token>`.'