Pular para o conteúdo

Conectar canais

Conectar o Instagram

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

  • 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).

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.

  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.

Página de uma conexão do Instagram no painel: conta ativa, permissões que faltam e campos do webhook

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.

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.

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 com o Login do Instagram precisam ser reconectadas uma vez. Os ids de mensagem da Meta são diferentes entre os dois logins.

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

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.

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.

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

Tela do perfil de mensagens de uma conta do Instagram, com uma pergunta frequente e um fluxo de boas-vindas

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

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).
  • media_publish pelo espelho não passa pelo agendamento do Messajo: para agendar, use /v1/publications.
  • envio em massa (não há campanhas no Instagram);
  • mensagem fora da janela;
  • grupos;
  • contas pessoais: só funciona com conta profissional.