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

# Quick Start

> Primeiros passos no Instagram: conectar conta (oficial ou não oficial) e enviar o primeiro DM.

<Tip>
  Do **zero ao primeiro DM na fila** em poucos passos. Escolha **oficial (Meta)** ou **não oficial**. As mesmas rotas de envio servem os dois.
</Tip>

## Em poucas palavras

* **Oficial:** login Meta no painel ou link compartilhável; destinatário = **IGSID**; janela de **24h**
* **Não oficial:** usuário e senha (ou link); `acceptInstagramTerms: true`; warm-up em conta nova
* Nos dois casos você usa a **mesma API**; só muda como conecta a conta

Dúvida sobre qual escolher? Veja [Modos de conexão](/instagram-api/como-funciona/modos-de-conexao).

## Antes de começar

* Uma **chave de API** (`sk_live_...` ou `sk_test_...` para sandbox)
* Permissões de instância e envio na chave. Veja [Escopos](/instagram-api/como-funciona/escopos-api-key)
* Nos exemplos, troque `sk_live_xxxxx` pela sua chave

<Note>
  Começando agora? Use `sk_test_...` e confira o resultado na [Caixa sandbox](/guides/sandbox/index).
</Note>

***

<Tabs>
  <Tab title="Conexão oficial">
    ### 1. Conectar a conta

    Três caminhos, escolha o que combina com sua integração:

    #### 1A, Pelo painel

    1. Instagram → Nova conexão → **Oficial**
    2. Faça login com a Meta (ou cole credenciais manuais no draft)
    3. Quando o status ficar **ativo**, anote o **id da instância**

    #### 1B, Pela API com link para o cliente

    ```http theme={null}
    POST /v1/instagram/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Atendimento IG",
      "mode": "OFFICIAL",
      "generateShareableLink": true
    }
    ```

    Resposta esperada: **200** com instância **PENDING** e o link:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "instance": {
          "id": "clxx123...",
          "name": "Atendimento IG",
          "status": "PENDING",
          "mode": "OFFICIAL"
        },
        "shareableLink": {
          "hostedUrl": "https://api.notifique.dev/w/instance-connect/...?token=...",
          "embedUrl": "https://api.notifique.dev/w/embed/instance-connect/...?token=..."
        }
      }
    }
    ```

    Envie `shareableLink.hostedUrl` para o cliente. Na página ele vê **Continuar com a Meta**. Quando terminar, a instância fica **ACTIVE**.

    <Warning>
      Quem tiver o link pode conectar ou desconectar a instância. Depois do uso, rotacione o secret se disponível na API de connect-page.
    </Warning>

    #### 1C, Pela API com credenciais Meta

    **Embedded** (após Facebook Login no navegador):

    ```json theme={null}
    {
      "name": "Atendimento IG",
      "mode": "OFFICIAL",
      "metaEmbeddedCode": "CODE_DO_EMBEDDED_SIGNUP"
    }
    ```

    **BYOK** (token e IDs que você já possui):

    ```json theme={null}
    {
      "name": "Atendimento IG",
      "mode": "OFFICIAL_BYOK",
      "metaAccessToken": "EAAxx...",
      "facebookPageId": "123456789012345",
      "igBusinessAccountId": "17841400000000000",
      "metaAppSecret": "abc123..."
    }
    ```

    ### 2. Como obter o IGSID do destinatário

    No modo **oficial**, o campo `to` usa o **IGSID** (ID scoped da Page), não `@username`.

    * **Webhook** `instagram.received`: campo `from` na mensagem inbound
    * **API** `GET /v1/instagram/messages/inbound/{id}` após o cliente enviar DM
    * **Painel:** detalhe da mensagem recebida

    ### 3. Enviar o primeiro DM

    ```http theme={null}
    POST /v1/instagram/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "clxx123...",
      "to": ["17841400000000000"],
      "type": "text",
      "payload": { "message": "Olá! Como posso ajudar?" }
    }
    ```

    Resposta esperada: **202** com a mensagem na fila:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "messageIds": ["msg_abc..."],
        "status": "QUEUED",
        "count": 1
      }
    }
    ```

    <Warning>
      No oficial, a conversa precisa estar na **janela de 24h** após a última mensagem do cliente.
    </Warning>

    ### 4. Depois do primeiro envio

    Configure o webhook Meta em `{sua_base}/webhooks/meta/instagram`, escute `instagram.received` e status de envio. Para hide de comentários, use as rotas de comments na [referência da API](/instagram-api/api-reference/api-reference).
  </Tab>

  <Tab title="Conexão não oficial">
    ### 1. Conectar a conta

    #### 1A, Pelo painel

    1. Instagram → Nova conexão → **Não oficial**
    2. Informe usuário e senha (e 2FA se pedido)
    3. Aceite os termos; aguarde status **ativo**

    #### 1B, Pela API com credenciais

    ```http theme={null}
    POST /v1/instagram/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Atendimento IG",
      "mode": "UNOFFICIAL",
      "acceptInstagramTerms": true,
      "auth": {
        "mode": "password",
        "username": "sua_conta",
        "password": "sua_senha"
      }
    }
    ```

    Se a Meta pedir verificação, envie `verificationCode` no create ou use `POST /v1/instagram/instances/{id}/challenge/resolve`.

    #### 1C, Pela API com link compartilhável

    ```json theme={null}
    {
      "name": "Atendimento IG",
      "mode": "UNOFFICIAL",
      "acceptInstagramTerms": true,
      "generateShareableLink": true
    }
    ```

    Resposta: `connection.status` = `pending_login` + `shareableLink`. O cliente abre o link e digita usuário/senha.

    <Warning>
      Conta nova: leia a [política anti-suspensão](/instagram-api/como-funciona/politica-anti-banimento) (warm-up, cooldown).
    </Warning>

    ### 2. Enviar o primeiro DM

    ```json theme={null}
    {
      "instanceId": "clxx123...",
      "to": ["nome_do_usuario"],
      "type": "text",
      "payload": { "message": "Olá!" }
    }
    ```

    Resposta esperada: **202** (mesmo formato da aba oficial).

    ### 3. Depois do primeiro envio

    Configure [webhooks](/instagram-api/como-funciona/eventos-do-webhooks) do workspace. No não oficial você pode **editar** e **unsend** DMs enviados.
  </Tab>
</Tabs>

***

## Todos os tipos de envio

Na [referência da API](/instagram-api/api-reference/api-reference), abra **Enviar mensagem no Instagram** (`POST /v1/instagram/messages`) e escolha o exemplo no playground: Texto, Imagem, Vídeo, Áudio, Documento, Agendada, IGSID oficial ou username não oficial.

## Próximos passos

* [Modos de conexão](/instagram-api/como-funciona/modos-de-conexao)
* [Eventos de webhook](/instagram-api/como-funciona/eventos-do-webhooks)
* [Política anti-suspensão](/instagram-api/como-funciona/politica-anti-banimento)