Receber webhooks do WhatsApp numa Edge Function do Supabase

O que tem a Edge Function de fazer?

Duas coisas, em dois métodos.

Em GET, responde à verificação da Meta. Leia hub.mode, hub.verify_token e hub.challenge da query string, compare o token com o que indicou como verify token do destino e devolva o challenge como corpo em texto simples, com estado 200. Devolva 403 quando o token não coincide.

Em POST, recebe eventos. Faça o parse do corpo, extraia as mensagens de entry, changes e value, insira-as numa tabela e devolva 200. Mantenha a resposta rápida: a Meta trata uma resposta lenta ou falhada como uma entrega falhada e volta a tentar, o que significa a mesma mensagem duas vezes.

Defina o URL da função como destino do webhook do número no EasyCoexistence, com o mesmo verify token, e a Meta começa a entregar.

import { createClient } from "npm:@supabase/supabase-js@2";

const db = createClient(Deno.env.get("SUPABASE_URL")!, Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!);

Deno.serve(async (req) => {
  const url = new URL(req.url);
  if (req.method === "GET") {
    const ok = url.searchParams.get("hub.verify_token") === Deno.env.get("VERIFY_TOKEN");
    return new Response(ok ? url.searchParams.get("hub.challenge") : "forbidden", { status: ok ? 200 : 403 });
  }
  if (url.searchParams.get("key") !== Deno.env.get("URL_SECRET")) return new Response("no", { status: 401 });
  const body = await req.json();
  const rows = (body.entry ?? []).flatMap((e: any) => e.changes ?? [])
    .flatMap((c: any) => (c.value?.messages ?? []).map((m: any) => ({
      wamid: m.id, sender: m.from, kind: m.type, text: m.text?.body ?? null,
      phone_number_id: c.value.metadata?.phone_number_id, raw: m,
    })));
  if (rows.length) await db.from("whatsapp_messages").upsert(rows, { onConflict: "wamid" });
  return new Response("ok");
});

Porque devolve a função 401 à Meta?

Porque a verificação de JWT está ativa. O Supabase valida um JWT no cabeçalho Authorization antes de o código da Edge Function correr, e essa é a predefinição de todas as funções. A Meta não envia esse cabeçalho, pelo que a plataforma rejeita tanto o GET de verificação como todas as entregas, e o seu código nunca as vê.

Desative-a apenas nesta função. Faça o deploy com supabase functions deploy whatsapp --no-verify-jwt, ou defina verify_jwt = false na secção da função em supabase/config.toml. A documentação do Supabase descreve exatamente este caso: um endpoint público chamado por um fornecedor externo de webhooks.

Com a verificação da plataforma desativada, a função precisa da sua própria. O cabeçalho de assinatura não está disponível, uma vez que a Meta assina com o segredo da app que detém a subscrição. Coloque um segredo longo e aleatório no URL de destino, como parâmetro de query, e rejeite os pedidos que não o tragam, como faz o exemplo em POST.

Como deve a função guardar e responder?

Guardar primeiro, responder depois. Faça upsert pelo id da mensagem do WhatsApp com uma restrição de unicidade, para que as novas tentativas da Meta caiam na mesma linha em vez de criarem um duplicado. Guarde o phone_number_id de receção em cada linha se mais de um número apontar para a função.

Para tudo o que for lento, como chamar um modelo ou outra API antes de responder, entregue o trabalho a EdgeRuntime.waitUntil e devolva a resposta de imediato. A função continua a correr até essa promise terminar, enquanto a Meta já tem o seu 200. O Supabase deixa de esperar aos 150 segundos de inatividade e devolve 504, pelo que um código que faz todo o trabalho antes de responder é o que mais provavelmente causa novas tentativas.

As respostas seguem para o endpoint de mensagens da Cloud API com o phone number id e o token do número, guardados como segredos da função. Nas 24 horas seguintes à última mensagem do cliente, o texto livre é entregue; fora desse prazo, só um template aprovado.

As mensagens enviadas a partir do telemóvel chegam à função?

Sim. Num número Coexistence, a app WhatsApp Business continua a funcionar e, quando alguém responde a partir dela, a Meta entrega um eco dessa mensagem enviada ao mesmo destino, no campo smb_message_echoes e num array message_echoes, e não em messages.

Amplie o parser para ler ambos e guarde uma coluna direction. A tabela passa a conter a conversa completa, as mensagens do cliente e as respostas da empresa, que é o que a maioria das pessoas quer consultar depois: tempos de resposta, conversas sem resposta, a hora da última mensagem recebida por contacto.

Esse último valor é também o dado de que todos os caminhos de envio precisam, porque decide se a resposta pode ser texto livre ou tem de ser um template. Uma view sobre a tabela pode expô-lo por contacto ao resto da sua aplicação.

Erros comuns

• Fazer o deploy com a verificação de JWT ativa. O Supabase rejeita os pedidos da Meta com 401 antes de o código correr, e nenhuma mensagem chega.
• Devolver o challenge embrulhado em JSON. A Meta precisa do valor em bruto como corpo, ou a verificação falha em silêncio.
• Fazer trabalho lento antes de responder. A Meta repete o que vê como falhas, e a mesma mensagem é processada duas vezes.
• Desativar a verificação de JWT sem qualquer controlo próprio. Quem descobrir o URL pode enviar mensagens falsas para a tabela.

Perguntas frequentes

Continue a ler