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.

Anexos recebidos

No código atualmente auditado, o webhook reconhece que a DM contém anexo, mas não repassa esse anexo para a conversa. Uma foto, um áudio ou outro arquivo pode chegar sem conteúdo utilizável; uma mensagem composta somente pelo anexo pode falhar no processamento. Peça ao cliente para enviar a informação em texto e registre o caso com o suporte.

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.
• Imagem, áudio ou arquivo não chega ao agente: peça o conteúdo em texto; anexos recebidos ainda não atravessam o pipeline deste canal.