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

# Criando Instância

Ao criar uma instância, você escolhe o tipo de conexão:

* **Não oficial** (`connection_type: "unofficial"`): o padrão. Depois de criar, você conecta via QR code ou código de pareamento.
* **Oficial WABA** (`connection_type: "waba"`): usa a API oficial da Meta. Você precisa fornecer as credenciais no objeto `waba`.

Para instâncias WABA, existem duas formas de obter as credenciais:

1. **Embedded Signup** (recomendado): fluxo OAuth pelo dashboard, sem precisar mexer no Meta Business Manager. Veja o [guia passo a passo](/pt-BR/v1/guides/connect-waba-instance).
2. **Token manual**: você gera um System User Token no Meta Business Manager e passa direto na API. Veja o [método avançado](/pt-BR/v1/guides/connect-waba-instance#método-2-token-manual-avançado).

<Note>
  Quando `connection_type` é `waba`, o objeto `waba` com `access_token`, `phone_number_id` e `waba_id` é obrigatório. Para instâncias não oficiais, esse campo é ignorado.
</Note>

Para entender as diferenças entre os dois tipos, veja o [comparativo WABA vs não oficial](/pt-BR/v1/guides/waba-vs-unofficial).


## OpenAPI

````yaml POST /wa/instances
openapi: 3.1.0
info:
  title: Zapster API
  description: ''
  version: 1.0.0
servers:
  - url: https://api.zapsterapi.com/v1
    description: Produção
security: []
tags: []
paths:
  /wa/instances:
    post:
      tags: []
      summary: Criação de Instâncias
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                connection_type:
                  type: string
                  enum:
                    - unofficial
                    - waba
                  default: unofficial
                  description: >
                    Tipo de conexão da instância:

                    - `unofficial` (padrão): conexão via QR code ou código de
                    pareamento

                    - `waba`: conexão via API oficial do WhatsApp (Cloud API da
                    Meta)


                    Quando `waba` é selecionado, o objeto `waba` com as
                    credenciais é obrigatório.
                  example: unofficial
                waba:
                  type: object
                  description: >
                    Credenciais para conexão com a API oficial do WhatsApp
                    (Cloud API da Meta).

                    Obrigatório quando `connection_type` é `waba`. Ignorado para
                    instâncias não oficiais.
                  properties:
                    access_token:
                      type: string
                      description: >
                        Token de acesso da Meta Cloud API. Pode ser um System
                        User Token

                        (gerado no Meta Business Manager) ou obtido via Embedded
                        Signup (OAuth).
                      example: EAAxxxxxxx...
                    phone_number_id:
                      type: string
                      description: >-
                        ID do número de telefone cadastrado na Meta Business
                        Platform
                      example: '1016102021584086'
                    waba_id:
                      type: string
                      description: ID da conta WhatsApp Business (WABA) na Meta
                      example: '419378847918255'
                    auth_method:
                      type: string
                      enum:
                        - system_user_token
                      default: system_user_token
                      description: >
                        Opcional. Como o `access_token` foi obtido. Aqui o único

                        valor aceito é `system_user_token` (token gerado no Meta

                        Business Manager), que também é o padrão quando omitido.


                        Este campo define qual segredo a Zapster usa para
                        validar

                        a assinatura dos webhooks que a Meta envia. Informe

                        `app_secret` junto se o token pertence ao seu próprio
                        app

                        Meta, para que a validação seja feita contra ele.
                      example: system_user_token
                    app_id:
                      type: string
                      description: >
                        Opcional. ID do app Meta do cliente (BYO-app), quando o

                        `access_token` é um System User Token gerado no app Meta
                        do

                        próprio cliente. Usado apenas para
                        identificação/auditoria —

                        não é segredo e não participa da validação de
                        assinatura.
                      example: '1234567890123456'
                    app_secret:
                      type: string
                      description: >
                        Opcional, recomendado para BYO-app. App Secret do app
                        Meta

                        do cliente. Quando informado, a assinatura HMAC

                        (`X-Hub-Signature-256`) dos webhooks de entrada é
                        validada

                        contra este segredo (em vez do app secret global da

                        Zapster), garantindo a verificação completa de
                        autenticidade

                        dos eventos recebidos.


                        É armazenado criptografado em repouso (AES-256), com o
                        mesmo

                        rigor do `access_token`. Informe-o sempre que o

                        `access_token` for um System User Token do seu próprio
                        app

                        Meta.
                      example: a1b2c3d4e5f6...
                    webhook_verify_token:
                      type: string
                      description: |
                        Opcional. Token de verificação de webhook fornecido pelo
                        cliente. Se omitido, a Zapster gera um token aleatório.
                        Armazenado criptografado em repouso (AES-256).
                      example: meu-verify-token
                  required:
                    - access_token
                    - phone_number_id
                    - waba_id
                name:
                  type: string
                  description: >-
                    Um apelido opcional para sua instância, usado apenas para
                    sua organização.
                  maxLength: 64
                  example: Bot SDR
                lookup_key:
                  type: string
                  maxLength: 36
                  example: ins_8j7wlxmpjlixx9mux5
                  description: >
                    Um identificador único opcional de pesquisa que permite
                    associar sua instância a uma estrutura de dados específica.
                    A Zapster API não utiliza esse dado internamente; ele serve
                    exclusivamente para facilitar consultas na API, permitindo
                    localizar registros mais rapidamente por meio deste
                    parâmetro de pesquisa.
                metadata:
                  type: object
                  description: >
                    Um conjunto de informações adicionais armazenadas como chave
                    e valor. Cada chave é um texto e o valor pode ser um número
                    ou um texto. Esse campo é opcional e pode ser usado para
                    guardar detalhes personalizados.


                    Para números de telefone, use o formato E.164 (ex:
                    `+5587989075555`). O sistema validará e formatará
                    automaticamente o número, removendo espaços e hífens.
                  additionalProperties:
                    oneOf:
                      - type: string
                      - type: number
                  example:
                    customer_id: '123456'
                    customer_name: Joãozinho
                    phone_number: '+5587989075555'
                settings:
                  $ref: '#/components/schemas/InstanceSettings'
                webhooks:
                  $ref: '#/components/schemas/InstanceWebhookCreate'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
      deprecated: false
      security:
        - bearer: []
components:
  schemas:
    InstanceSettings:
      type: object
      description: |
        Objeto **opcional** de configurações da sua instância.
      properties:
        call_rejection:
          type: string
          description: |
            Define o comportarmento de rejeição de ligações.

            - `all` - Irá rejeitar todas ligações
            - `none` - Não irá rejeitar ligações.
            - `video_only` - Irá rejeitar apenas ligações de **vídeo**.
            - `audio_only` - Irá rejeitar apenas ligações de **audio**.
          enum:
            - all
            - none
            - video_only
            - audio_only
        delay_per_word:
          type: boolean
          description: >
            Define se o delay antes de enviar a mensagem deve ser baseado na
            quantidade de palavras.


            ℹ️ Limitado a no máximo **10 segundos** de espera.
        delete_chat_after_sent:
          type: boolean
          description: >
            ⚠️ *Esta função não está funcionando adequadamente, estamos
            trabalhando para regulariza-la.*


            Define se o chat/conversa deve ser limpo depois do envio da
            mensagem. Isso garante que o dispositivo fique acumulando mensagens
            a ponto de muitas vezes travar o dispositivo que foi conectado.
        message_delay:
          type: object
          description: >
            Define a configuração de delay antes do envio da mensagem, se
            configurado `delay_per_word` é ignorado. O tempo é gerado
            randomicamente entre os limites configurado (`min` e `max`).
          properties:
            enabled:
              type: boolean
              default: true
            max:
              type: integer
              description: >-
                Máximo de tempo em segundos que deve ser esperado antes do envio
                da mensagem.
              default: 10
            min:
              type: integer
              description: >-
                Mínimo de tempo em segundos que deve ser esperado antes do envio
                da mensagem.
              default: 1
        presence_behavior:
          type: string
          description: >
            Define o comportamento da presença (Online, Digitando...,
            Gravando...) da sua instância.


            - `only_composing` - Aparecerá "Online" apenas durante o envio da
            mensagem. (**recomendado**)

            - `always_online` - Aparecerá sempre online

            - `always_offline` - Nunca aparecerá "Online" exceto quando
            necessário durante os envios (por boas práticas)
          enum:
            - only_composing
            - always_online
            - always_offline
        read_confirmation:
          description: >
            Define o comportamento de "confirmação de leitura", ou seja, a
            leitura automática das mensagens recebidas.


            Aceita os valores clássicos em texto ou um objeto segmentado por
            tipo de conversa:


            - `never` - Nunca confirma a leitura (equivale a todos os segmentos
            desligados)

            - `always` - Sempre confirma a leitura (equivale a todos os
            segmentos ligados)

            - Objeto com os campos `chats`, `groups` e `status` - Controla cada
            segmento de forma independente


            No formato de objeto, cada campo é booleano e o padrão é `false`:


            - `chats` - Conversas individuais

            - `groups` - Grupos

            - `status` - Status publicados pelos seus contatos (com este
            segmento ligado, os status recebidos são marcados como vistos)


            Mensagens enviadas pela própria instância, listas de transmissão e
            publicações de canais nunca recebem confirmação de leitura
            automática.
          oneOf:
            - type: string
              enum:
                - never
                - always
            - type: object
              properties:
                chats:
                  type: boolean
                  default: false
                  description: >-
                    Confirma a leitura de mensagens recebidas em conversas
                    individuais.
                groups:
                  type: boolean
                  default: false
                  description: Confirma a leitura de mensagens recebidas em grupos.
                status:
                  type: boolean
                  default: false
                  description: Marca como vistos os status publicados pelos seus contatos.
    InstanceWebhookCreate:
      type: object
      description: >
        Lista de webhooks serão criados assim que a instância finalizar sua
        criação. Atente-se para a quantidade de webhooks nesta lista, a mesma é
        baseada no seu plano contratado.
      properties:
        events:
          type: array
          description: >
            Lista de eventos será enviados para o webhook.


            Alguns eventos dependem do tipo de conexão da instância. O
            `message.failed` e o `message.flow_reply` existem apenas em
            instâncias com API oficial (WABA); assinar `message.failed` em uma
            instância não oficial é recusado com `unsupported_webhook_event`.
            Consulte a página de eventos disponíveis para o detalhamento por
            evento.
          items:
            type: string
            example:
              - message.received
            enum:
              - group.created
              - group.participants_added
              - group.participants_demoted
              - group.participants_promoted
              - group.participants_removed
              - group.updated
              - instance.connected
              - instance.disconnected
              - instance.forbidden
              - instance.mentioned
              - instance.qrcode
              - message.deleted
              - message.delivered
              - message.failed
              - message.flow_reply
              - message.pinned
              - message.reaction
              - message.read
              - message.received
              - message.sent
              - message.unpinned
              - poll.created
              - poll.deleted
              - poll.updated
              - status.reply
        url:
          type: string
          description: URL para onde deverá ser enviada as notificações de webhook.
          format: uri
      required:
        - events
        - url
    Instance:
      type: object
      description: Estrutura de uma instância registrada na API.
      properties:
        created_at:
          type: string
          format: date-time
          description: Data e hora de criação da instância no formato ISO 8601.
          example: '2024-10-03T21:56:22.620Z'
        id:
          type: string
          description: Identificador único da instância.
          example: xy9rexnkwobmgg3tehgvs
        metadata:
          type: object
          description: Metadados adicionais armazenados como chave e valor.
          additionalProperties:
            oneOf:
              - type: string
              - type: number
          example:
            customer_id: '123456'
            customer_name: Joãozinho
            phone_number: '+5587989075555'
        connection_type:
          type: string
          enum:
            - unofficial
            - waba
          description: |
            Tipo de conexão da instância:
            - `unofficial`: conexão via QR code (padrão)
            - `waba`: conexão via API oficial do WhatsApp (Cloud API da Meta)
          example: unofficial
        name:
          type: string
          description: Nome da instância.
          example: MyNewInstance2
        owner:
          type: object
          description: Informações sobre o proprietário da instância.
          properties:
            display_name:
              type: string
              nullable: true
              description: Nome de exibição do proprietário. Pode ser nulo.
              example: null
            id:
              type: string
              format: uuid
              description: Identificador único do proprietário.
          required:
            - id
        qrcode:
          type: string
          nullable: true
          description: QR Code da instância, caso disponível.
          example: null
        settings:
          $ref: '#/components/schemas/InstanceSettings'
        status:
          type: string
          enum:
            - connected
            - disconnected
            - offline
          description: Status atual da instância
          example: disconnected
        webhooks:
          type: array
          description: Lista de webhooks configurados para esta instância.
          items:
            type: object
            description: Configuração de um webhook associado à instância.
            properties:
              enabled:
                type: boolean
                description: Indica se o webhook está ativado.
                example: true
              events:
                type: array
                description: Lista de eventos que acionam este webhook.
                items:
                  type: string
                  enum:
                    - group.created
                    - group.participants_added
                    - group.participants_demoted
                    - group.participants_promoted
                    - group.participants_removed
                    - group.updated
                    - instance.connected
                    - instance.disconnected
                    - instance.forbidden
                    - instance.mentioned
                    - instance.qrcode
                    - message.deleted
                    - message.delivered
                    - message.failed
                    - message.flow_reply
                    - message.pinned
                    - message.reaction
                    - message.read
                    - message.received
                    - message.sent
                    - message.unpinned
                    - poll.created
                    - poll.deleted
                    - poll.updated
                    - status.reply
                example:
                  - message.received
              id:
                type: string
                description: Identificador único do webhook.
                example: 2nenz69l0xbf0m3uu9tfo
              name:
                type: string
                description: Nome do webhook configurado.
                example: Webhook Name
              test_mode:
                type: boolean
                description: Indica se o webhook está em modo de teste.
                example: false
              test_url:
                type: string
                nullable: true
                description: URL de teste do webhook, se disponível.
                example: null
              url:
                type: string
                format: uri
                description: URL do webhook para onde os eventos serão enviados.
                example: https://webhook.mydomain.com
            required:
              - enabled
              - events
              - id
              - name
              - test_mode
              - url
        lookup_key:
          type: string
          description: Identificador de pesquisa criado anteriormente.
          example: ins_8j7wlxmpjlixx9mux5
      required:
        - created_at
        - id
        - metadata
        - name
        - owner
        - settings
        - status
        - webhooks
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````