> ## 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.

# Migrando o Tipo de Conexão

> Migra a instância entre a conexão não oficial (QR Code) e a API oficial (WABA), preservando o ID, os webhooks e as configurações.


Use este endpoint para trocar o tipo de conexão de uma instância existente sem perder nada da sua integração: o ID da instância, os webhooks cadastrados e as configurações permanecem exatamente como estavam. A migração funciona nos dois sentidos.

### Não oficial para API oficial (WABA)

Envie `connection_type: "waba"` junto com o objeto `waba`, contendo `access_token`, `phone_number_id` e `waba_id`.

<Note>
  O Embedded Signup (login com o Facebook) só está disponível pelo painel da Zapster: ele depende de uma página hospedada por nós e não pode ser reproduzido por chamada de API. Para migrar por aqui, gere um System User Token no Meta Business Manager e informe-o no objeto `waba`.
</Note>

O ambiente de execução da conexão não oficial é desativado e o número passa a operar pela Cloud API da Meta. Ao final, a instância fica `connected`.

### API oficial (WABA) para não oficial

Envie `connection_type: "unofficial"`, sem credenciais. A configuração WABA é removida com segurança na Meta e um novo ambiente de conexão é preparado. A instância fica `disconnected`, aguardando a leitura do QR Code (ou código de pareamento) para conectar o número.

### Webhooks são revalidados

Os tipos de conexão suportam conjuntos diferentes de eventos de webhook, e a API oficial suporta um conjunto menor. Antes de migrar, os webhooks já cadastrados na instância são validados contra o tipo de destino: se algum estiver inscrito em um evento que o destino não emite, a migração é rejeitada com `400` (`unsupported_webhook_event`), listando todos os eventos incompatíveis e os eventos válidos. Ajuste as inscrições e repita a chamada.

### Confirmação para instâncias em uso

Migrar uma instância que não está `disconnected` interrompe o serviço dela durante a troca, mesmo quando ela está apenas `offline`: só a instância já `disconnected` dispensa a confirmação. Nesse caso, a chamada exige o header `X-Confirmation-Token`, com um valor que identifique a confirmação (evite reenviar sempre o mesmo texto fixo). Sem ele, a API responde `409` (`confirmation_required`) e nada é alterado; o corpo da resposta traz em `details` o contexto da ação (`action`, `resource`, `from`, `to` e `status`).

Essa confirmação não é uma camada de segurança. Ela existe para evitar que uma migração disruptiva aconteça por engano, não para impedir chamadas mal-intencionadas.


## OpenAPI

````yaml POST /wa/instances/{instance_id}/migrate
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/{instance_id}/migrate:
    post:
      tags: []
      summary: Migração do Tipo de Conexão
      description: >
        Migra a instância entre a conexão não oficial (QR Code) e a API oficial
        (WABA), preservando o ID, os webhooks e as configurações.
      parameters:
        - name: instance_id
          in: path
          description: ID da instância.
          required: true
          example: ozj35qv418rpmlrb
          schema:
            type: string
        - name: X-Confirmation-Token
          in: header
          description: >
            Token de confirmação, obrigatório quando a instância NÃO está

            desconectada, inclusive quando está `offline`: a migração interrompe

            o serviço dela durante a troca. Qualquer valor não vazio confirma a

            chamada hoje; envie um valor que identifique a confirmação, sem
            fixar

            sempre o mesmo texto. Sem o header nessa situação, a API responde

            `409` (`confirmation_required`).
          required: false
          example: x7k2m9qp
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - connection_type
              properties:
                connection_type:
                  type: string
                  enum:
                    - unofficial
                    - waba
                  description: >
                    Tipo de conexão de destino:

                    - `unofficial`: o metadata WABA é limpo e um pod é
                    provisionado para a conexão por QR Code

                    - `waba`: o pod é derrubado e o número é conectado pela
                    Cloud API da Meta (exige credenciais)
                  example: waba
                waba:
                  type: object
                  description: |
                    Credenciais manuais da Cloud API da Meta, aceitas apenas
                    quando `connection_type` é `waba`.
                  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.
                      example: '1234567890123456'
                    app_secret:
                      type: string
                      description: >
                        Opcional, recomendado para BYO-app. App Secret do app
                        Meta

                        do cliente, usado para validar a assinatura HMAC

                        (`X-Hub-Signature-256`) dos webhooks de entrada.
                        Armazenado

                        criptografado em repouso (AES-256).
                      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
              example:
                connection_type: waba
                waba:
                  access_token: EAAxxxxxxx...
                  phone_number_id: '1016102021584086'
                  waba_id: '419378847918255'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '400':
          description: |
            Erro de validação no corpo da requisição, instância já no tipo de
            destino, ou webhook com evento não suportado no tipo de destino
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Código do erro
                          example: unsupported_webhook_event
                        message:
                          type: string
                          description: Mensagem de erro
                          example: >-
                            The events "group.created" are not supported by
                            "waba" instances.
        '401':
          description: Token de acesso da Meta inválido ou expirado
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: waba_invalid_token
                        message:
                          type: string
                          example: >-
                            The provided WABA access token is invalid or has
                            expired. Please verify your credentials.
        '404':
          description: Instância não encontrada ou não pertence ao usuário
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: instance_not_found
                        message:
                          type: string
                          example: Instance not found.
        '409':
          description: |
            Confirmação necessária para migrar uma instância que não está
            desconectada (inclui `offline`)
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: confirmation_required
                        message:
                          type: string
                          example: >-
                            This action interrupts the service of an instance
                            that is currently "connected". Resend the request
                            with the confirmation token to proceed.
                        details:
                          type: object
                          description: Contexto da ação que exige confirmação.
                          properties:
                            action:
                              type: string
                              example: instance.migrate_connection
                            resource:
                              type: string
                              description: ID da instância
                              example: ozj35qv418rpmlrb
                            from:
                              type: string
                              description: Tipo de conexão atual
                              example: unofficial
                            to:
                              type: string
                              description: Tipo de conexão de destino
                              example: waba
                            status:
                              type: string
                              description: Status atual da instância
                              example: connected
      deprecated: false
      security:
        - bearer: []
components:
  schemas:
    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
    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.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````