Instagram(Edição)

Instagram

1. INFORMAÇÕES GERAIS

1.1 Plataforma

• Nome: Instagram Direct Messages

• API Base: Facebook Graph API v18.0 (mesma do Facebook)

• Endpoint: 

  https://graph.facebook.com/v18.0/

• Descrição: Integração com contas Instagram Business para mensagens diretas. Permite comunicação entre empresas e usuários através de contas comerciais do Instagram conectadas a páginas do Facebook.

1.2 Configuração

class MessengerConfigParams {
  @IsString()
  @IsNotEmpty()
  token: string                    // Page Access Token

  @IsString()
  @IsNotEmpty()
  pageId: string                   // Facebook Page ID conectada

  @IsString()
  @IsOptional()
  instagramId?: string             // Instagram Business Account ID

  @IsString()
  @IsOptional()
  tokenExpirationDate?: Date
}

Descrição: Configuração para Instagram Direct que reutiliza a infraestrutura do Facebook. O "instagramId" identifica a conta comercial do Instagram conectada à página do Facebook.

---

2. MÉTODOS DE ENVIO

2.1 sendMessage()

sendMessage(message: SendMessagePayload, pageId: string, token: string): Promise<AxiosResponse>

Descrição: Envia mensagens através da mesma Graph API do Facebook, mas para usuários do Instagram. O comportamento é idêntico ao Facebook, mudando apenas os identificadores.

2.1.1 Estrutura de Entrada

{
  to: string,                   // Instagram User ID (IGSID)
  body?: string,                // Texto da mensagem
  mediaUri?: string,            // URL da mídia
  userName?: string             // Nome do agente
}

Descrição: O "to" é o Instagram-Scoped ID (IGSID) único do usuário para aquela conta comercial específica. Diferente do PSID do Facebook.

2.1.2 Implementação Específica Instagram

const textWithUserName =
      session.type === MessageServiceEnum.facebook
        ? Utils.addUserNameToMessage(userName, body)
        : `${userName}: \n\n${body}`// implementação instagram

    const text = mediaUri ? null : userName ? textWithUserName : body

Descrição: Formatação específica do Instagram que adiciona o nome do agente seguido de quebras de linha, diferente do padrão do Facebook.

2.1.3 Payload da Graph API

{
  message: {
    text?: string,
    attachment?: {
      type: 'image' | 'video' | 'audio' | 'file',
      payload: {
        url: string,
        is_reusable: true
      }
    }
  },
  recipient: { id: string },    // IGSID do destinatário
  messaging_type: 'RESPONSE'
}

Descrição: Estrutura idêntica ao Facebook, mas o "recipient.id" contém o IGSID em vez do PSID.

---

3. MÉTODOS DE RECEBIMENTO

3.1 getAccountInfo()

getAccountInfo(accountId: string, pageToken: string, provider: 'instagram'): Promise<MessengerAccountInfo>

Descrição: Obtém informações do perfil do usuário Instagram. Retorna dados mais limitados comparado ao Facebook, focando no username.

3.1.1 Retorno Instagram

{
  id: string,
  formated_name: string,        // username
  username?: string
}

Descrição: Retorna principalmente o username do Instagram. Não inclui primeiro/último nome como no Facebook.

3.1.2 Implementação

accountInfo.formated_name = accountInfo.username

Descrição: Usa diretamente o username como nome formatado, seguindo padrão de identificação do Instagram.

---

4. ESTRUTURA DE WEBHOOK

4.1 Webhook Entry

{
  object: 'page',               // Sempre 'page' (mesmo do Facebook)
  entry: [{
    id: string,                 // Page ID (não Instagram ID)
    time: number,
    messaging: [{
      sender: { id: string },   // IGSID do usuário Instagram
      recipient: { id: string }, // Instagram Business Account ID
      timestamp: number,
      message: {
        mid: string,            // Message ID único
        text?: string,
        attachments?: Attachment[]
      }
    }]
  }]
}

Descrição: Estrutura idêntica ao Facebook, mas 

sender.id

 contém IGSID e 

recipient.id

 contém o Instagram Business Account ID.

4.2 Verificação de Webhook

// Endpoint: GET /api/webhook/messenger/instagram
{
  'hub.mode': 'subscribe',
  'hub.verify_token': process.env.INSTAGRAM_WEBHOOK_TOKEN,
  'hub.challenge': string     // Retornado se verificação OK
}

Descrição: Processo de verificação idêntico ao Facebook, mas usa token específico do Instagram para maior segurança.

---

5. MAPEAMENTO ESPECÍFICO

5.1 Identificação de Plataforma

const platformConfig = await this.setupService.getPlatformConfigByMessenger(
  message.recipient.id, 
  MessageServiceEnum.instagram
)

Descrição: Identifica a configuração usando o Instagram Business Account ID e o enum específico do Instagram.

5.2 Diferenciação no Controller

@Post('messenger/:provider')
async messengerWebhook(
  @Body() payload: MessengerMessageDto,
  @Param('provider') provider: MessageServiceEnum.instagram | MessageServiceEnum.facebook,
  @Res() res: Response,
)

Descrição: Mesmo endpoint para ambas plataformas, diferenciadas pelo parâmetro 

provider

 na URL.

---

6. CONFIGURAÇÃO

6.1 Variáveis de Ambiente

INSTAGRAM_WEBHOOK_TOKEN=your_instagram_webhook_token
# Usa as mesmas configurações Meta do Facebook
META_URL_API=https://graph.facebook.com/v18.0/
META_API_APP_ID=your_app_id
META_APP_SECRET=your_app_secret

Descrição: Reutiliza configurações Meta do Facebook, mas usa token de webhook específico para maior isolamento de segurança.

6.2 Subscrições

subscribed_fields=message_deliveries,message_echoes,message_edits,message_reactions,message_reads,messages,messaging_referrals

Descrição: Mesmos campos de evento do Facebook, pois ambas plataformas usam a infraestrutura Meta.