Facebook

1. INFORMAÇÕES GERAIS

1.1 Plataforma

Nome: Facebook Messenger
API Base: Facebook Graph API v18.0
Endpoint:
```
https://graph.facebook.com/v18.0/
```
Descrição: Integração com páginas do Facebook para envio e recebimento de mensagens através do Messenger. Permite comunicação bidirecional entre empresas e usuários através de páginas comerciais do Facebook.

1.2 Configuração

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

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

  @IsString()
  @IsOptional()
  instagramId?: string             // Não usado para Facebook

  @IsString()
  @IsOptional()
  tokenExpirationDate?: Date       // Data de expiração do token
}

Descrição: Configuração específica para Facebook Messenger, onde o Token é o Page Access Token obtido através do Facebook App,e PageId identifica a página comercial que receberá/enviará mensagens.

2. MÉTODOS DE ENVIO

2.1 sendMessage()

sendMessage(session: Session, payload: SendMessagePayload)

Descrição: Envia mensagens através da Graph API do Facebook para usuários que interagiram com a página. Suporta texto, imagens, vídeos, áudios e documentos.

2.1.1 Estrutura de Entrada

{
  to: string,                   // PSID do usuário Facebook
  body?: string,                // Texto da mensagem
  mediaUri?: string,            // URL da mídia
  userName?: string             // Nome do agente
}

Descrição: O "to" é o Page-Scoped ID (PSID) único do usuário para aquela página específica. O "userName" é adicionado ao texto da mensagem para identificar o agente.

2.1.2 Implementação Específica Facebook

const textWithUserName = Utils.addUserNameToMessage(userName, body)
const text = mediaUri ? null : userName ? textWithUserName : body

Descrição: Utiliza a função utilitária addUserNameToMessage que formata o nome do agente de acordo com padrões específicos do Facebook Messenger.

2.1.3 Payload da Graph API

{
  message: {
    text?: string,              // Para mensagens de texto
    attachment?: {              // Para mídia
      type: 'image' | 'video' | 'audio' | 'file',
      payload: {
        url: string,
        is_reusable: true
      }
    }
  },
  recipient: { id: string },    // PSID do destinatário
  messaging_type: 'RESPONSE'    // Tipo fixo
}

Descrição: Estrutura oficial da Graph API. O "messaging_type: 'RESPONSE' " indica que é uma resposta a uma mensagem do usuário, permitindo envio sem restrições de janela de 24h.

2.2 Tratamento de Documentos

if (type === 'document') {
  payload = {
    message: {
      text: `Por favor, clique no(s) link(s) abaixo para realizar o(s) download(s) do(s) arquivo(s): ${mediaUri}`,
    },
  }
}

Descrição: Documentos são convertidos em mensagens de texto com links para download.

3. MÉTODOS DE RECEBIMENTO

3.1 getAccountInfo()

getAccountInfo( accountId: string, pageToken: string, provider: MessageServiceType(facebook),
  ): Promise<MessengerAccountInfo>

Descrição: Obtém informações do perfil do usuário Facebook através da Graph API

3.1.1 Retorno Facebook

{
  id: string,
  formated_name: string,        // "first_name last_name"
  first_name?: string,
  last_name?: string,
  profile_pic?: string,
  username?: string
}

Descrição: Retorna dados do perfil público do usuário. O "formated_name" combina primeiro e último nome para exibição.

3.1.2 Implementação

accountInfo.formated_name = `${accountInfo.first_name} ${accountInfo.last_name}`

Descrição: Concatena primeiro e último nome com espaço, seguindo padrão de nomenclatura do Facebook.

4. ESTRUTURA DE WEBHOOK

4.1 Webhook Entry

{
  object: 'page',               // Sempre 'page' para Facebook
  entry: [{
    id: string,                 // Page ID
    time: number,
    messaging: [{
      sender: { id: string },   // PSID do usuário
      recipient: { id: string }, // Page ID
      timestamp: number,
      message: {
        mid: string,            // Message ID único
        text?: string,
        attachments?: Attachment[]
      }
    }]
  }]
}

Descrição: Estrutura padrão dos webhooks do Facebook. O "object: 'page' " identifica que é um evento de página. Cada entry pode conter múltiplos eventos messaging.

4.2 Verificação de Webhook

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

Descrição: Processo de verificação obrigatório do Facebook. O "hub.challenge" 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.facebook
)

Descrição: Identifica a configuração da plataforma usando o ID do destinatário (Page ID) e o enum específico do Facebook.

5.2 Processamento de Anexos

if (message.message.attachments) {
  for (const attachment of attachments) {
    // Processa cada anexo separadamente
    const payloadWithOneAttachment = { ...payload }
    payloadWithOneAttachment.entry[0].messaging[0].message.attachments = [attachment]
    await this.ingestMessage(payloadWithOneAttachment, this.messengerService, session)
  }
}

Descrição: Múltiplos anexos em uma mensagem são processados individualmente, criando eventos separados para cada mídia. Isso facilita o processamento e rastreamento individual.

6. CONFIGURAÇÃO

6.1 Variáveis de Ambiente

FACEBOOK_WEBHOOK_TOKEN=your_facebook_webhook_token
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_APP_ID=your_app_id

Descrição: Tokens necessários para autenticação e verificação de webhooks. O

WEBHOOK_TOKEN

é definido pelo desenvolvedor, enquanto

APP_SECRET

APP_ID

são fornecidos pelo Facebook.

6.2 Subscrições

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

Descrição: Campos de evento subscritos automaticamente. Inclui mensagens, confirmações de entrega, leitura, edições e reações.