Quick Start

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.

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.

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
Nos exemplos, troque sk_live_xxxxx pela sua chave

Começando agora? Use sk_test_... e confira o resultado na Caixa sandbox.

Conexão oficial
Conexão não oficial

1. Conectar a conta

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

1A, Pelo painel

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

1B, Pela API com link para o cliente

POST /v1/instagram/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Atendimento IG",
  "mode": "OFFICIAL",
  "generateShareableLink": true
}

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

{
  "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.

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.

1C, Pela API com credenciais Meta

Embedded (após Facebook Login no navegador):

{
  "name": "Atendimento IG",
  "mode": "OFFICIAL",
  "metaEmbeddedCode": "CODE_DO_EMBEDDED_SIGNUP"
}

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

{
  "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

POST /v1/instagram/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

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

Resposta esperada: 202 com a mensagem na fila:

{
  "success": true,
  "data": {
    "messageIds": ["msg_abc..."],
    "status": "QUEUED",
    "count": 1
  }
}

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

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.

1. Conectar a conta

1A, Pelo painel

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

1B, Pela API com credenciais

POST /v1/instagram/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "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

{
  "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.

Conta nova: leia a política anti-suspensão (warm-up, cooldown).

2. Enviar o primeiro DM

{
  "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 do workspace. No não oficial você pode editar e unsend DMs enviados.

Todos os tipos de envio

Na referência da API, 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.

API Instagram

Em poucas palavras

Antes de começar

1. Conectar a conta

1A, Pelo painel

1B, Pela API com link para o cliente

1C, Pela API com credenciais Meta

2. Como obter o IGSID do destinatário

3. Enviar o primeiro DM

4. Depois do primeiro envio

1. Conectar a conta

1A, Pelo painel

1B, Pela API com credenciais

1C, Pela API com link compartilhável

2. Enviar o primeiro DM

3. Depois do primeiro envio

Todos os tipos de envio

Próximos passos

​Em poucas palavras

​Antes de começar

​1. Conectar a conta

​1A, Pelo painel

​1B, Pela API com link para o cliente

​1C, Pela API com credenciais Meta

​2. Como obter o IGSID do destinatário

​3. Enviar o primeiro DM

​4. Depois do primeiro envio

​1. Conectar a conta

​1A, Pelo painel

​1B, Pela API com credenciais

​1C, Pela API com link compartilhável

​2. Enviar o primeiro DM

​3. Depois do primeiro envio

​Todos os tipos de envio

​Próximos passos

Em poucas palavras

Antes de começar

1. Conectar a conta

1A, Pelo painel

1B, Pela API com link para o cliente

1C, Pela API com credenciais Meta

2. Como obter o IGSID do destinatário

3. Enviar o primeiro DM

4. Depois do primeiro envio

1. Conectar a conta

1A, Pelo painel

1B, Pela API com credenciais

1C, Pela API com link compartilhável

2. Enviar o primeiro DM

3. Depois do primeiro envio

Todos os tipos de envio

Próximos passos