Conectar canais
Conectar o Instagram
Como ligar uma conta profissional do Instagram para Direct, comentários e menções.
Requisitos
Seção intitulada “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. - 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).
Permissões
Seção intitulada “Permissões”O Messajo pede só as permissões da API do Instagram com Login do Facebook para Empresas:
| 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 fotos, vídeos, carrosséis, Reels e Stories | não |
instagram_manage_insights |
Ler os insights da conta e de cada post | não |
Sem uma das duas obrigatórias a conexão não é criada (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, com a permissão em details[0].message, até você reconectar.
Passo a passo
Seção intitulada “Passo a passo”- 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.
- Entre, escolha a(s) conta(s) do Instagram que o Messajo pode acessar e confirme.
- 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.
- 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.

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 com o canal Instagram: a pessoa autoriza pela página pública do convite, sem conta no Messajo.
Acesso sem validade
Seção intitulada “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ção intitulada “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
Seção intitulada “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
Seção intitulada “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 |
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. 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
Seção intitulada “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.
Fora da janela, o Messajo recusa antes de chamar a Meta: 422 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. Reação, curtida e share não abrem nem estendem a janela.
Comentários, resposta privada e menções
Seção intitulada “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).
| 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); até 7 dias depois do comentário, e em comentário de live só durante a live (422 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). A resposta que você mandou volta pela Meta como webhook, mas não gera evento de novo.
Perfil de mensagens
Seção intitulada “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
payloadque chega no webhook quando a pessoa toca. - Menu fixo: até 20 itens (
postbackou 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).

O PUT é parcial: campo ausente não muda, null apaga. Depois de gravar, o Messajo relê o perfil na Meta.
Camada espelho
Seção intitulada “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 …/messagesgrava a mensagem nos logs, gasta as fichas de envio e devolveX-Messajo-Message-Id.subscribed_apps,access_tokeneoauth/*são bloqueados (403mirror_path_blocked).media_publishpelo espelho não passa pelo agendamento do Messajo: para agendar, use/v1/publications.
O que a Meta não permite
Seção intitulada “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.