API de Mensagens do Instagram: Guia Completo para Desenvolvedores

The API de Mensagens do Instagram permite que as empresas enviem e recebam mensagens diretas de forma programática através da Graph API oficial do Instagram. Se você está criando automação de suporte ao cliente, sistemas de notificações ou fluxos de comércio conversacional, este guia abrange tudo o que você precisa para integrar o API de DM do Instagram na sua aplicação.

As capacidades de mensagens do Instagram fazem parte do ecossistema mais amplo da Meta Graph API. Ao contrário dos métodos não oficiais que podem resultar na suspensão da conta, a solução oficial API de Mensagens Diretas do Instagram oferece mensagens confiáveis e escaláveis para contas empresariais com autenticação adequada e limitação de taxa.

Pré-requisitos e Requisitos

Antes de poder enviar DMs do Instagram de forma programática, é necessário configurar vários componentes. A API de Mensagens do Instagram possui requisitos específicos que diferem de outras plataformas sociais.

Requisitos para Conta Empresarial

A API de Mensagens do Instagram funciona apenas com contas de Negócios ou Criadores do Instagram conectadas a uma Página do Facebook. Contas pessoais não conseguem acessar os endpoints de mensagens.

Criando um App para Desenvolvedores da Meta

1. Navegar para developers.facebook.com e crie um novo aplicativo
2. Selecione "Negócio" como o tipo de aplicativo.
3. Adicione o produto "Instagram Graph API" ao seu aplicativo.
4. Configure os seus URIs de redirecionamento OAuth
5. Anote o seu ID do aplicativo e o segredo do aplicativo.

```
// Variáveis de ambiente necessárias para a integração da API do Instagram
interface InstagramConfig {
  clientId: string;      // ID do App Meta
  clientSecret: string;  // Segredo do App Meta
  redirectUri: string;   // Sua URL de callback OAuth
  webhookVerifyToken: string; // Para verificação do webhook
}

const config: InstagramConfig = {
  clientId: process.env.INSTAGRAM_CLIENT_ID || '',
  clientSecret: process.env.INSTAGRAM_CLIENT_SECRET || '',
  redirectUri: process.env.INSTAGRAM_REDIRECT_URI || '',
  webhookVerifyToken: process.env.INSTAGRAM_WEBHOOK_VERIFY_TOKEN || '',
};
```

Nota: Armazene todas as credenciais em variáveis de ambiente. Nunca armazene segredos de API no controle de versão.

Fluxo de Autenticação OAuth 2.0

A API de Mensagens do Instagram utiliza OAuth 2.0 para autenticação. Você precisará implementar um processo de troca de token em duas etapas para obter tokens de acesso de longa duração.

Passo 1: Gere a URL de Autorização

Direcione os usuários para a página de autorização do Instagram com os escopos necessários:

function getInstagramAuthUrl(state: string): string {
  const scopes = [
    'instagram_business_basic',
    'instagram_business_content_publish',
    'instagram_business_manage_messages', // Necessário para DMs
  ];

  const params = new URLSearchParams({
    client_id: config.clientId,
    redirect_uri: config.redirectUri,
    scope: scopes.join(','),
    response_type: 'code',
    auth_type: 'rerequest', // Forçar o prompt de re-permissão
    state: state, // Proteção CSRF
  });

  return `https://www.instagram.com/oauth/authorize?${params.toString()}`;
}

Passo 2: Trocar Código por Tokens

Após o usuário autorizar seu aplicativo, o Instagram redireciona para sua URL de callback com um código de autorização. Troque isso por tokens de acesso:

interface TokenResponse {
  accessToken: string;
  refreshToken: string;
  userId: string;
  expiresIn: number;
}

async function exchangeCodeForToken(
  code: string
): Promise {
  // Passo 1: Trocar o código por um token de curta duração
  const tokenResponse = await fetch(
    'https://api.instagram.com/oauth/access_token',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        client_id: config.clientId,
        client_secret: config.clientSecret,
        grant_type: 'authorization_code',
        redirect_uri: config.redirectUri,
        code: code,
      }),
    }
  );

  if (!tokenResponse.ok) {
    const error = await tokenResponse.text();
    throw new Error(`Falha na troca do token: ${error}`);
  }

  const shortLivedData = await tokenResponse.json();
  const shortLivedToken = shortLivedData.access_token;
  const userId = shortLivedData.user_id;

  // Passo 2: Trocar por um token de longa duração (60 dias)
  const longLivedResponse = await fetch(
    `https://graph.instagram.com/access_token?` +
    `grant_type=ig_exchange_token&` +
    `client_secret=${config.clientSecret}&` +
    `access_token=${shortLivedToken}`,
    { method: 'GET' }
  );

  if (!longLivedResponse.ok) {
    const error = await longLivedResponse.text();
    throw new Error(`Falha na troca do token de longa duração: ${error}`);
  }

  const longLivedData = await longLivedResponse.json();

  return {
    accessToken: longLivedData.access_token,
    refreshToken: longLivedData.access_token,
    userId: userId,
    expiresIn: longLivedData.expires_in,
  };
}

Atualizando Tokens de Acesso

Tokens de longa duração expiram após 60 dias. Implemente a atualização de tokens para manter o acesso:

async function refreshAccessToken(
  currentToken: string
): Promise<{ accessToken: string; expiresIn: number }> {
  const response = await fetch(
    `https://graph.instagram.com/refresh_access_token?` +
    `grant_type=ig_refresh_token&` +
    `access_token=${currentToken}`,
    { method: 'GET' }
  );

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Falha ao atualizar o token: ${response.status} ${errorText}`);
  }

  const data = await response.json();

  if (data.error) {
    throw new Error(`Erro ao atualizar o token: ${data.error.message}`);
  }

  if (!data.access_token) {
    throw new Error('A atualização do token não retornou um access_token');
  }

  return {
    accessToken: data.access_token,
    expiresIn: data.expires_in,
  };
}

Nota: Programe tarefas de atualização de tokens para serem executadas antes da expiração. Uma boa prática é atualizar os tokens quando restarem menos de 7 dias.

Configuração de Webhooks para Mensagens em Tempo Real

Para receber mensagens recebidas em tempo real, é necessário configurar webhooks. O Instagram envia requisições POST para o seu endpoint sempre que um usuário envia uma mensagem para a sua conta comercial.

Endpoint de Verificação de Webhook

O Instagram verifica a sua URL de webhook com uma solicitação GET antes de ativá-la:

import { Request, Response } from 'express';

function handleWebhookVerification(
  req: Request,
  res: Response
): void {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === config.webhookVerifyToken) {
    console.log('Webhook verificado com sucesso');
    res.status(200).send(challenge);
    return;
  }

  console.error('Falha na verificação do webhook');
  res.status(403).send('Verificação falhou');
}

Envio de Mensagens através da API de DM do Instagram

A funcionalidade principal do API de Mensagens Diretas do Instagram é enviar mensagens para usuários que iniciaram conversas com o seu negócio.

Envio de Mensagens de Texto

To envie DMs do Instagram de forma programática, utilize o endpoint de mensagens:

interface SendMessageOptions {
  accessToken: string;
  igUserId: string;      // Seu ID da Conta Comercial do Instagram
  recipientId: string;   // O ID do usuário no Instagram
  text: string;
}

interface SendMessageResponse {
  messageId: string;
}

async function sendTextMessage(
  options: SendMessageOptions
): Promise<SendMessageResponse> {
  const { accessToken, igUserId, recipientId, text } = options;

  const response = await fetch(
    `https://graph.instagram.com/${igUserId}/messages`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${accessToken}`,
      },
      body: JSON.stringify({
        recipient: {
          id: recipientId,
        },
        message: {
          text: text,
        },
      }),
    }
  );

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Falha ao enviar a mensagem: ${error}`);
  }

  const data = await response.json();
  return { messageId: data.message_id };
}

Limites de Taxa e Melhores Práticas

Compreender os limites de taxa é fundamental para criar integrações de mensagens confiáveis no Instagram.

Visão Geral do Limite de Taxa

Melhores Práticas

1. Implemente um retrocesso exponencial para erros de limite de taxa
2. Armazene os tokens de usuário para evitar chamadas de autenticação repetidas
3. Utilize o reconhecimento de webhook imediatamente, processe de forma assíncrona
4. Monitore a expiração do token e atualize proativamente
5. Registre todas as interações da API para depuração

Usando o Late para Integração de Mensagens no Instagram

Construir e manter integrações com a API de Mensagens do Instagram exige um esforço de desenvolvimento considerável. É necessário gerenciar fluxos de OAuth, atualização de tokens, gerenciamento de webhooks, limitação de taxa e tratamento de erros em potencialmente várias plataformas sociais.

Late oferece uma API unificada que simplifica a integração de mensagens do Instagram junto com outras plataformas sociais. Em vez de criar integrações separadas para cada plataforma, a Late oferece:

• Autenticação UnificadaFluxo único de OAuth para Instagram, Facebook, Twitter, LinkedIn e muito mais
• Gestão Automática de TokensA Late gerencia automaticamente a atualização e a expiração de tokens.
• Abstração de WebhookReceba eventos de webhook normalizados em todas as plataformas.
• Limitação de Taxa Integrada: Filas de requisições inteligentes e lógica de reenvio
• SDK Tipo SeguroSuporte completo a TypeScript com tipos abrangentes

Com o Late, a implementação de mensagens do Instagram torna-se simples:

import { Late } from '@getlate/sdk';

const late = new Late({ apiKey: process.env.LATE_API_KEY });

// Enviar uma mensagem através da API unificada do Late
await late.messages.send({
  accountId: 'instagram-account-id',
  recipientId: 'user-id',
  content: {
    text: 'Olá do Late!',
  },
});

// Lidar com mensagens recebidas com eventos normalizados
late.webhooks.on('message.received', (event) => {
  console.log('Plataforma:', event.platform); // 'instagram'
  console.log('Mensagem:', event.content.text);
});

Late cuida da complexidade da API de Mensagens do Instagram para que você possa se concentrar em desenvolver a funcionalidade principal do seu aplicativo. Confira o Documentação do Late para começar com a integração de mensagens do Instagram e outras plataformas sociais.