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:session: SendMessagePayload,Session, pageId:payload: string, token: string): Promise<AxiosResponse>
SendMessagePayload)

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

id" contém o IGSID e

"recipient.id

id" contém o Instagram ~~Business~~ Account ~~ID.~~ID destinatario .

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~~Instagram. ~~para~~O ~~maior~~"hub.challenge" ~~segurança.~~deve ser retornado exatamente como recebido se o "verify_toke" estiver correto.

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çãoProcessamento node ControllerAnexos

@Post('messenger/:provider')if async(message.message.attachments) messengerWebhook({
  @Body()for payload:(const MessengerMessageDto,attachment @Param('provider')of provider:attachments) MessageServiceEnum.instagram{
    |// MessageServiceEnum.facebook,Processa @Res()cada res:anexo Response,separadamente
    )const payloadWithOneAttachment = { ...payload }
    payloadWithOneAttachment.entry[0].messaging[0].message.attachments = [attachment]
    await this.ingestMessage(payloadWithOneAttachment, this.messengerService, session)
  }
}

Descrição: ~~Mesmo~~Múltiplos ~~endpoint~~anexos em uma mensagem são processados individualmente, criando eventos separados para ~~ambas~~cada ~~plataformas,~~mídia. ~~diferenciadas~~Isso ~~pelo~~facilita ~~parâmetro~~o processamento e rastreamento individual.

5.3. Status de Mensagens

providerexport const messengerPayloadToStatus = (payload: MessengerMessageDto, platformConfigId: string, channelId: string,)

Descrição: na ~~URL.~~Método para identificar status de mensagem

5.3.1 Implementação no Sistema

 let messageStatus: WebhookStatusMessagesEnum = WebhookStatusMessagesEnum.SENDED
  let messageId = message?.message?.mid || null

  if (message?.read?.watermark || message?.read?.mid) {
    messageStatus = WebhookStatusMessagesEnum.READED
    messageId = message?.read?.mid
  } else if (message?.delivery) {
    messageStatus = WebhookStatusMessagesEnum.DELIVERED
    messageId = message?.delivery?.mids?.[0]
  } else if (message?.message?.is_deleted) {
    messageStatus = WebhookStatusMessagesEnum.REMOVED
  } else if (message.message.is_echo) {
    messageStatus = WebhookStatusMessagesEnum.SENDED
  }

Descrição: Tipos de Status Suportados

SENDED: Mensagem enviada

DELIVERED: Mensagem entregue (delivery?.mids?)

READED: Mensagem lida (read.watermark ou read.mid)

REMOVED: Mensagem removida (is_deleted: true)

5.3.2 Estrutura payload status

MessengerMessageDto {
  object: "page"
  entry: [{
      messaging: [{
      sender: { id: "user123" },
      recipient: { id: "page456" },
      message?: {
        mid: string                 // ID da mensagem
        is_deleted?: boolean        // Flag de mensagem deletada
        is_echo?: boolean           // Flag de echo (mensagem enviada)
      }
      Ou
      delivery?: {                  // Status de entrega
        mids: string[]              // Array de IDs das mensagens entregues
        watermark: number           // Timestamp de entrega
      }
      Ou
      read?: {                      // Status de leitura
        watermark?: number          // Timestamp de leitura
        mid?: string                // ID específico da mensagem lida
      }
    }]
  }]
}

Descrição: O identificação do status diferencia pelos eventos escutados, is_deleted(mensagem removida), is_echo( mensagem enviada), delivery( mensagem entregue), read(mensagem lida)

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~~Campos de evento dosubscritos ~~Facebook,~~automaticamente. ~~pois~~Inclui ~~ambas~~mensagens, ~~plataformas~~confirmações ~~usam~~de aentrega, ~~infraestrutura~~leitura, ~~Meta.~~edições e reações