Erros de Autenticação WhatsApp API: Token Expirado e Permissões

Erros Comuns de Autenticação

Os erros de autenticação são os primeiros obstáculos que você encontra ao integrar com a WhatsApp Business API. Aqui estão os principais e como resolvê-los.

Erro 190: Token Expirado

{
  "error": {
    "message": "Error validating access token: Session has expired",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": 463,
    "fbtrace_id": "..."
  }
}

Causa

O access token temporário expirou. Tokens de teste do Meta for Developers duram apenas 24 horas.

Solução 1: Gerar Token Permanente

1. Vá para Meta Business Suite
2. Configurações > Usuários > Tokens de acesso do sistema
3. Gere um token com permissões necessárias

// Exemplo de uso com token permanente
const PERMANENT_TOKEN = process.env.WHATSAPP_TOKEN

async function sendMessage(to, message) {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/${phoneNumberId}/messages`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${PERMANENT_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        messaging_product: 'whatsapp',
        to,
        type: 'text',
        text: { body: message }
      })
    }
  )

  return response.json()
}

Solução 2: Implementar Refresh Automático

Para aplicações que usam OAuth:

class WhatsAppClient {
  constructor() {
    this.accessToken = process.env.WHATSAPP_TOKEN
    this.refreshToken = process.env.REFRESH_TOKEN
    this.appId = process.env.APP_ID
    this.appSecret = process.env.APP_SECRET
  }

  async refreshAccessToken() {
    const response = await fetch(
      `https://graph.facebook.com/v18.0/oauth/access_token?` +
        `grant_type=fb_exchange_token&` +
        `client_id=${this.appId}&` +
        `client_secret=${this.appSecret}&` +
        `fb_exchange_token=${this.accessToken}`
    )

    const data = await response.json()

    if (data.access_token) {
      this.accessToken = data.access_token
      // Salve o novo token
      await this.saveToken(data.access_token)
    }

    return data
  }

  async request(url, options = {}) {
    try {
      const response = await fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          Authorization: `Bearer ${this.accessToken}`
        }
      })

      const data = await response.json()

      // Se token expirou, tenta refresh
      if (data.error?.code === 190) {
        await this.refreshAccessToken()
        // Tenta novamente
        return this.request(url, options)
      }

      return data
    } catch (error) {
      throw error
    }
  }
}

Erro 0: AuthException

{
  "error": {
    "message": "Invalid OAuth access token",
    "type": "OAuthException",
    "code": 0,
    "fbtrace_id": "..."
  }
}

Causa

O token é inválido - pode ter sido revogado, mal formatado ou nunca existiu.

Solução

1. Verifique se o token está correto (sem espaços extras)
2. Use o Access Token Debugger
3. Gere um novo token se necessário

// Validar token antes de usar
async function validateToken(token) {
  const response = await fetch(
    `https://graph.facebook.com/debug_token?input_token=${token}&access_token=${token}`
  )

  const data = await response.json()

  if (data.data?.is_valid) {
    console.log('Token válido até:', new Date(data.data.expires_at * 1000))
    return true
  }

  console.log('Token inválido:', data.data?.error?.message)
  return false
}

Erro 3: Permissões Insuficientes

{
  "error": {
    "message": "(#3) Application does not have permission for this action",
    "type": "OAuthException",
    "code": 3,
    "fbtrace_id": "..."
  }
}

Causa

O token não tem as permissões necessárias para a ação.

Permissões Necessárias

Para WhatsApp Business API, você precisa de:

• whatsapp_business_management - Gerenciar conta e configurações
• whatsapp_business_messaging - Enviar e receber mensagens
• business_management - Gerenciar Business Manager

Solução

1. Vá para Meta for Developers > seu App > App Review
2. Solicite as permissões necessárias
3. Gere um novo token com as permissões aprovadas

// Verificar permissões do token
async function checkPermissions(token) {
  const response = await fetch(
    `https://graph.facebook.com/me/permissions?access_token=${token}`
  )

  const data = await response.json()

  const permissions = data.data.filter((p) => p.status === 'granted')
  console.log(
    'Permissões concedidas:',
    permissions.map((p) => p.permission)
  )

  const required = [
    'whatsapp_business_management',
    'whatsapp_business_messaging'
  ]

  const missing = required.filter(
    (r) => !permissions.find((p) => p.permission === r)
  )

  if (missing.length > 0) {
    console.log('Permissões faltando:', missing)
    return false
  }

  return true
}

Erro 100: Parâmetro Inválido

{
  "error": {
    "message": "(#100) Invalid parameter",
    "type": "OAuthException",
    "code": 100,
    "error_subcode": 33,
    "fbtrace_id": "..."
  }
}

Causa

Algum parâmetro da requisição está incorreto.

Solução

Verifique:

• Phone Number ID está correto
• Número de destino está no formato internacional
• Template existe e está aprovado
• Todos os parâmetros obrigatórios estão presentes

// Validação antes de enviar
function validateMessageRequest(to, template) {
  const errors = []

  // Validar número
  if (!/^\d{10,15}$/.test(to.replace(/\D/g, ''))) {
    errors.push('Número de telefone inválido')
  }

  // Validar template
  if (!template?.name) {
    errors.push('Nome do template é obrigatório')
  }

  if (!template?.language?.code) {
    errors.push('Código de idioma é obrigatório')
  }

  return errors
}

Configuração Segura de Tokens

Variáveis de Ambiente

# .env
WHATSAPP_TOKEN=seu_token_aqui
WHATSAPP_PHONE_NUMBER_ID=123456789
WHATSAPP_BUSINESS_ACCOUNT_ID=987654321
META_APP_SECRET=app_secret_aqui

Nunca faça isso:

// ❌ ERRADO - Token exposto no código
const token = 'EAABsbCS1iHgBAKm...'

// ❌ ERRADO - Token em log
console.log('Token:', process.env.WHATSAPP_TOKEN)

Faça assim:

// ✅ CORRETO - Token em variável de ambiente
const token = process.env.WHATSAPP_TOKEN

// ✅ CORRETO - Log mascarado
console.log('Token:', token ? '***configurado***' : 'NÃO CONFIGURADO')

Middleware de Autenticação

class WhatsAppAuthMiddleware {
  constructor(config) {
    this.token = config.token
    this.phoneNumberId = config.phoneNumberId
    this.lastValidation = null
    this.validationInterval = 60 * 60 * 1000 // 1 hora
  }

  async validateIfNeeded() {
    const now = Date.now()

    if (
      !this.lastValidation ||
      now - this.lastValidation > this.validationInterval
    ) {
      const isValid = await this.validateToken()

      if (!isValid) {
        throw new Error('Token WhatsApp inválido ou expirado')
      }

      this.lastValidation = now
    }
  }

  async validateToken() {
    try {
      const response = await fetch(
        `https://graph.facebook.com/v18.0/${this.phoneNumberId}`,
        {
          headers: {
            Authorization: `Bearer ${this.token}`
          }
        }
      )

      const data = await response.json()
      return !data.error
    } catch {
      return false
    }
  }
}

Conclusão

Erros de autenticação geralmente são:

1. Token expirado: Use tokens permanentes ou implemente refresh
2. Token inválido: Verifique no Debug Token
3. Permissões faltando: Solicite via App Review

Mantenha seus tokens seguros e implemente validação periódica para evitar falhas em produção.

Precisa de ajuda com autenticação da API? Fale comigo para consultoria.