Instagram Direct Message (DM)

O canal Instagram Direct Message (DM) conecta uma conta Instagram Business ou Creator a uma caixa de entrada. Cada mensagem recebida entra em uma conversa do SquadOS e segue para o destino escolhido: um agente ou o atendimento humano.

Antes de conectar

Você precisa de:

• uma conta Instagram Business ou Creator; contas pessoais não são aceitas;
• acesso para entrar nessa conta e autorizar o aplicativo;
• permissão para criar ou alterar caixas de entrada no SquadOS.

A autorização usa o login do próprio Instagram. Não é necessário vincular uma Página do Facebook. O SquadOS solicita acesso ao perfil profissional, às mensagens e aos comentários porque a mesma conexão da Meta atende Instagram Direct e Instagram Comentários.

Conectar a conta

1. No painel administrativo, abra Caixas de entrada.
2. Clique em Conectar caixa de entrada.
3. No grupo Instagram, escolha Instagram Direct.
4. Clique em Conectar com Instagram. Uma janela separada abre o login do Instagram.
5. Entre na conta profissional e autorize as permissões solicitadas.
6. Depois que a janela fechar, confira Conectado: @usuário. Quando a Meta não devolve o nome, o card identifica a conta como Instagram Business · ID ….
7. Clique em Continuar, escolha um agente ativo ou Atendimento humano, defina o Nome da caixa e clique em Concluir.

Se o navegador não abrir a janela de autorização, permita pop-ups para o domínio do painel e tente novamente. Fechar a janela antes do fim cancela a conexão e não deve deixar uma nova caixa na lista.

Uma conta só pode ficar ativa em uma caixa do mesmo canal. Conectar a mesma conta em outra caixa desativa a conexão anterior por exclusividade; confirme o destino antes de concluir a troca.

O que acontece com cada mensagem

O webhook da Meta identifica a conta destinatária e procura uma caixa Instagram Direct ativa com essa identidade. O SquadOS então:

1. ignora cópias de mensagens enviadas pela própria conta;
2. identifica o contato pelo ID do Instagram e cria ou reutiliza a conversa;
3. registra contexto quando a mensagem é resposta ou menção de story;
4. entrega a mensagem ao agente configurado ou à fila humana;
5. envia a resposta de volta pelo Instagram.

Quando há agente, ele usa o prompt, as bases de conhecimento vinculadas e as ferramentas habilitadas. Quando o destino é Atendimento humano, a mensagem é armazenada sem chamar modelo nem consumir créditos de IA. Respostas longas do agente ou do operador são divididas automaticamente em blocos de até 1.000 caracteres para o Instagram.

O canal é reativo: o SquadOS responde a uma pessoa que iniciou o contato, mas esta caixa não oferece uma ação para começar uma nova DM.

Imagens, Reels, posts e Stories recebidos

Disponibilidade em Dev

O fluxo de mídias compartilhadas foi publicado em Dev em 13/10/2026. A análise de vídeo e a recuperação pelo histórico foram validadas pela API publicada. O compartilhamento pelo aplicativo Instagram até a resposta do agente ainda precisa de validação real; esta entrega não foi publicada em produção.

Quando o Instagram fornece uma URL acessível, o canal identifica a mídia de posts, Reels e Stories compartilhados e preserva a legenda ou o título disponível. Imagens seguem o processamento visual configurado no agente. Áudios seguem o fluxo de transcrição. O agente recebe também o contexto de compartilhamento, resposta ou menção de Story.

Para vídeos, o comportamento depende do modelo e da configuração de Multimodal:

• se o modelo do atendimento aceita vídeo e não há um modelo de pré-processamento configurado, ele recebe o vídeo diretamente;
• caso contrário, um modelo auxiliar ativo e compatível analisa o vídeo e entrega uma descrição ao agente, mantendo o modelo do atendimento;
• Não aceitar arquivos também bloqueia vídeos e usa a mensagem de rejeição configurada.

A análise auxiliar fica salva junto da mensagem. Na conversa, você pode reproduzir o vídeo e abrir Descrição de … quando a análise estiver disponível. Perguntas posteriores podem usar essa descrição pelo histórico, sem nova análise do mesmo anexo. O custo da análise integra a cobrança da resposta; uma descrição salva e reaproveitada não gera uma nova chamada de análise.

Vídeos recebidos têm limite de 25 MB. Uma URL ausente, expirada ou inacessível não permite recuperar o conteúdo apenas pelo tipo da mensagem. Nesses casos, o canal registra a indisponibilidade no contexto; peça à pessoa que envie a imagem ou o vídeo diretamente. A disponibilidade de falas e sons na descrição depende do modelo auxiliar.

Atendimento humano e janela da Meta

Em Conversas, use Assumir para ficar responsável pelo atendimento e pausar a resposta automática. As mensagens digitadas pelo operador são enviadas ao Direct pelo mesmo canal.

O envio atual usa a mensagem padrão da Meta, inclusive para o operador. Portanto, trate 24 horas desde a última mensagem do contato como o limite operacional tanto para a IA quanto para o atendimento humano. O runtime possui suporte técnico à tag HUMAN_AGENT, mas o caminho de atendimento do produto não a aplica; não prometa a janela estendida de sete dias. Fora da janela, peça ao contato que escreva novamente no Instagram.

Conferir e renovar a conexão

Em Caixas de entrada, abra o menu ⋮ da linha e escolha Configurações. No bloco Conexão, uma conta conectada pode mostrar:

• Usuário do Instagram ou o ID usado como identidade;
• Conectado em;
• Token expira.

O token é salvo com uma expiração de até 60 dias. Uma rotina diária tenta renovar conexões próximas do vencimento. Falhas transitórias ficam registradas para nova tentativa; uma falha considerada permanente desativa a caixa com o motivo de token expirado.

Quando a lista mostrar Desconectada e a ação Reconectar, reautorize a conta por essa ação. Não dependa do aviso interno de token expirado: no código auditado, o estado calculado impede que esse aviso específico seja exibido.

Desconectar ou remover

Dentro de Configurações → Conexão, Desconectar tenta cancelar a assinatura na Meta e remove a caixa da lista:

• sem conversas, a caixa é apagada;
• com conversas, a caixa é removida logicamente e o histórico preserva a origem das conversas;
• a credencial deixa de ficar disponível para novos envios.

Isso não é uma pausa reversível. Para voltar a usar a conta depois de uma desconexão voluntária, conecte uma nova caixa. Uma caixa desativada automaticamente por perda de sessão, token ou exclusividade segue outro fluxo e pode oferecer Reconectar enquanto permanece na lista.

Diagnóstico rápido

• O pop-up não abre: permita pop-ups para o domínio do painel.
• A janela foi fechada: clique novamente em Conectar com Instagram e conclua a autorização.
• A caixa aparece conectada, mas nenhuma DM entra: envie uma DM de outra conta, confirme a identidade mostrada em Configurações e procure o suporte. O fluxo atual pode concluir o OAuth mesmo quando a Meta não devolve o ID roteável ou quando a assinatura do webhook falha.
• A caixa aparece desconectada: use Reconectar e autorize novamente. Se a linha já não existe, crie uma nova caixa.
• A resposta falha depois de horas sem contato: a janela padrão de 24 horas terminou; peça ao cliente para enviar uma nova mensagem.
• Post, Reel ou Story aparece indisponível: peça à pessoa que envie a imagem ou o vídeo diretamente; a Meta pode não fornecer uma URL acessível, ou o conteúdo pode ter expirado ou sido removido.
• O vídeo não é analisado: confira se Arquivos está habilitado em Multimodal. Quando o modelo do atendimento não aceita vídeo, a análise depende de um modelo auxiliar compatível permitido pela organização. Para tamanho acima de 25 MB ou demora no processamento, envie um vídeo menor; para falha de acesso, envie a mídia novamente.
• O vídeo não reproduz no navegador: confira sua conexão e tente novamente. Se o formato não for reproduzível, baixe o arquivo para abri-lo em outro aplicativo.