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

Como resolver erros de autenticação da WhatsApp Business API: códigos 0, 3, 190 e problemas com access token

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:

| Permissão | Uso | |-----------|-----| | 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.

.