# Conectar o Instagram

> Como ligar uma conta profissional do Instagram para Direct, comentários e menções.

## Requisitos

- Uma conta **profissional** do Instagram (comercial ou de criador). Se nenhuma conta for liberada no login, a conexão é recusada com [`instagram_account_not_professional`](/errors#instagram_account_not_professional).
- Não é preciso ter uma Página do Facebook.
- Quem faz o login precisa administrar a conta no Instagram.
- Na conta, ative **Configurações → Mensagens e respostas a stories → Controles de mensagens → Ferramentas conectadas → Permitir acesso às mensagens**. Sem isso o Direct não funciona (veja [Acesso ao Direct desativado](#acesso-ao-direct-desativado)).

## Permissões

O Messajo pede só as permissões da [API do Instagram com Login do Facebook para Empresas](https://developers.facebook.com/documentation/instagram-platform/overview):

| Permissão | Para quê | Obrigatória |
|---|---|---|
| `instagram_basic` | Ler o perfil e a mídia da conta | sim |
| `instagram_manage_messages` | Receber e enviar mensagens no Direct | sim |
| `instagram_manage_comments` | Listar, responder, ocultar e apagar comentários; resposta privada; menções | não |
| `instagram_content_publish` | [Publicar](/connect/instagram-content/#publicar) fotos, vídeos, carrosséis, Reels e Stories | não |
| `instagram_manage_insights` | Ler os [insights](/connect/instagram-content/#insights) da conta e de cada post | não |

Sem uma das duas obrigatórias a conexão não é criada ([`signup_scope_mismatch`](/errors#signup_scope_mismatch)). As outras podem ser desmarcadas na tela do Instagram: a conta conecta, a página da conexão mostra **Permissões que faltam** e o recurso responde `403` [`instagram_scope_missing`](/errors#instagram_scope_missing), com a permissão em `details[0].message`, até você reconectar.

## Passo a passo

1. Abra **Conexões → Conectar Instagram**. O painel navega para a página da Meta (Login do Facebook para Empresas), sem popup e funcionando no celular.
2. Entre, escolha a(s) conta(s) do Instagram que o Messajo pode acessar e confirme.
3. A Meta volta para o Messajo, que troca o código por um token de acesso, lê a conta, inscreve o app nos webhooks e lê o perfil de mensagens.
4. Pronto: a conta aparece como **Ativa**, com os campos de webhook inscritos.

- Uma conta liberada: conecta direto.
- Mais de uma: o Messajo mostra um seletor e conecta **uma por login**. Repita o login para conectar as outras.
- Nenhuma: erro [`instagram_account_not_professional`](/errors#instagram_account_not_professional).

![Página de uma conexão do Instagram no painel: conta ativa, permissões que faltam e campos do webhook](../../../assets/screenshots/instagram-connection-pt-BR.png)

Se você cancelar na tela da Meta, a tentativa fica no **Histórico** da conexão com o evento `CANCEL`. Se um passo falhar depois de a conexão ser criada, ela fica **Pendente** com o passo que faltou, e **Concluir conexão** refaz só o que falta.

Uma organização pode conectar várias contas. Para conectar a conta de um cliente, mande um [convite por link](/connect/whatsapp/#convidar-o-cliente-por-link) com o canal Instagram: a pessoa autoriza pela página pública do convite, sem conta no Messajo.

## Acesso sem validade

O acesso não expira, então não há renovação. Se a Meta revogar o acesso (senha trocada, app removido da conta, erro `190`), a conexão vai para `needs_reconnect` com `token_invalid` e o dono recebe o aviso com o link de reconexão. Reconectar mantém a mesma conexão.

### Acesso ao Direct desativado

Se a configuração **Permitir acesso às mensagens** estiver desligada na conta, a verificação de saúde da conexão registra `reason: "dm_access_disabled"`: sai um evento `connection.updated` e o painel mostra um aviso. A conexão continua ativa e comentários, publicação e insights seguem funcionando; só o Direct não. Para resolver, no Instagram abra **Configurações → Mensagens e respostas a stories → Controles de mensagens → Ferramentas conectadas** e ative **Permitir acesso às mensagens**. O aviso some na próxima verificação.

### Contas conectadas antes desta versão

Contas conectadas com o Login do Instagram precisam ser reconectadas uma vez. Os ids de mensagem da Meta são diferentes entre os dois logins.

## Tipos de mensagem

Instagram e Messenger usam o mesmo motor e o mesmo `POST /v1/messages`. O `to` é o IGSID do contato (ou o `ctc_…` do Messajo).

| `type` | WhatsApp | Instagram | Messenger |
|---|---|---|---|
| `text` (com `quick_replies` no IG/Messenger) | sim | sim | sim |
| `image` · `video` · `audio` · `document` | sim | sim | sim |
| `images` (2 a 10 imagens numa mensagem) | não | sim | não |
| `reaction` | sim | sim | sim |
| `like` (curtida) | não | sim | não |
| `share` (compartilhar um post da conta) | não | sim | não |
| `buttons` · `cards` | não | sim | sim |
| `template` · `interactive` · `location` · `contacts` · `sticker` | sim | não | não |

Tipo fora da matriz volta `422` [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel). No Instagram o texto tem até 1.000 bytes; imagem até 8 MB (JPEG, PNG ou GIF); áudio, vídeo e PDF até 25 MB. `typing: true` mostra "digitando" antes do envio e `POST /v1/messages/{id}/read` marca a conversa como vista. O contato chega com nome, nome de usuário e foto (lidos na primeira mensagem e a cada 7 dias).

## Janelas e HUMAN_AGENT

A Meta só deixa responder dentro de uma janela aberta pela última mensagem do contato:

| Janela | Quando vale |
|---|---|
| 24 horas | Qualquer resposta, contada da última mensagem do contato |
| 7 dias | Depois de o contato responder a um anúncio de Direct (o Messajo reconhece o `referral` do anúncio) |
| 7 dias | Com `tag: "human_agent"` |

`tag: "human_agent"` serve **só para resposta escrita por uma pessoa** (política da Meta): nunca use em automação ou bot. O painel não oferece a tag em automações. Ela exige o recurso **Human Agent** aprovado no App Review; sem ele a Meta recusa e o Messajo devolve `403` [`human_agent_not_approved`](/errors#human_agent_not_approved).

Fora da janela, o Messajo recusa antes de chamar a Meta: `422` [`outside_service_window`](/errors#outside_service_window), com o fim da janela em `details[0].message`. Com a tag e mais de 7 dias: `422` [`human_agent_window_closed`](/errors#human_agent_window_closed). Reação, curtida e `share` não abrem nem estendem a janela.

## Comentários, resposta privada e menções

Com `instagram_manage_comments`, o Messajo inscreve os campos `comments`, `live_comments` e `mentions` e entrega os eventos `comment.*` e `mention.received` ([catálogo](/webhooks/events/#catálogo)).

| O quê | Rota `/v1` | Evento |
|---|---|---|
| Comentários de um post (ao vivo na Meta, com o estado do Messajo) | `GET /connections/{id}/posts/{post_id}/comments` | — |
| Responder em público | `POST /connections/{id}/comments/{comment_id}/replies` com `{ message }` (até 2.200 caracteres) | `comment.replied` |
| Ocultar ou mostrar | `POST /connections/{id}/comments/{comment_id}/hide` com `{ hidden }` | `comment.hidden` · `comment.unhidden` |
| Apagar | `DELETE /connections/{id}/comments/{comment_id}` | `comment.deleted` |
| Resposta privada | `POST /connections/{id}/comments/{comment_id}/private-reply` | `comment.private_replied` + `message.sent` |
| Menções | `GET /connections/{id}/mentions` | `mention.received` |

A **resposta privada** manda uma mensagem no Direct para quem comentou, mesmo sem janela de 24 h aberta. Regras da Meta: só `text`, `buttons` ou `cards`; uma por comentário (`409` [`private_reply_already_sent`](/errors#private_reply_already_sent)); até 7 dias depois do comentário, e em comentário de live só durante a live (`422` [`private_reply_window_closed`](/errors#private_reply_window_closed)). A resposta abre a conversa com o contato e as próximas mensagens seguem as janelas normais.

Só dá para apagar comentário em mídia da própria conta ([`comment_not_owned`](/errors#comment_not_owned)). A resposta que você mandou volta pela Meta como webhook, mas não gera evento de novo.

## Perfil de mensagens

Em **Conexões → (conta) → Perfil de mensagens**, ou por `GET`/`PUT /v1/connections/{id}/messaging-profile`:

- **Perguntas frequentes** (ice breakers): até 4 por idioma, até 80 caracteres cada, com o `payload` que chega no webhook quando a pessoa toca.
- **Menu fixo**: até 20 itens (`postback` ou link).
- **Boas-vindas dos anúncios**: no Instagram, as boas-vindas são os fluxos dos anúncios de Direct (`/v1/connections/{id}/welcome-flows`). Fluxo usado num anúncio não muda nem apaga ([`welcome_flow_in_use`](/errors#welcome_flow_in_use)).

![Tela do perfil de mensagens de uma conta do Instagram, com uma pergunta frequente e um fluxo de boas-vindas](../../../assets/screenshots/instagram-profile-pt-BR.png)

O `PUT` é parcial: campo ausente não muda, `null` apaga. Depois de gravar, o Messajo relê o perfil na Meta.

## Camada espelho

Quem já fala a Graph do Instagram pode usar `/v1/instagram/{ig_user_id}/...` com o corpo e a resposta da Meta intactos: o Messajo põe o token da conta e confere a permissão da chave. Nós avulsos (mídia, comentário, contêiner, mensagem) ficam em `/v1/instagram/{ig_user_id}/nodes/{node_id}`.

- `POST …/messages` grava a mensagem nos logs, gasta as fichas de envio e devolve `X-Messajo-Message-Id`.
- `subscribed_apps`, `access_token` e `oauth/*` são bloqueados (`403` [`mirror_path_blocked`](/errors#mirror_path_blocked)).
- `media_publish` pelo espelho **não** passa pelo agendamento do Messajo: para agendar, use [`/v1/publications`](/connect/instagram-content/#publicar).

## O que a Meta não permite

- envio em massa (não há campanhas no Instagram);
- mensagem fora da janela;
- grupos;
- contas pessoais: só funciona com conta profissional.
