Quantos números de WhatsApp o seu agente de IA precisa?

Na whasp, a quantidade de números de WhatsApp de que o seu agente de IA precisa é a maior de três divisões, cada uma arredondada para cima: usuários ativos divididos por 80, cadastros no seu dia mais movimentado divididos por 32 e mensagens enviadas no seu dia mais movimentado divididas por 1.200. Esses valores são 80% dos limites por número. Some um ou dois números de reserva para banimentos.

Quais são os limites de um número?

Um número da whasp é uma conta pessoal real de WhatsApp em um celular na nuvem e um IP próprios, então os limites valem por número. A referência da API os lista:

Um número é sinalizado como at_risk quando qualquer limite passa de 80%, então os tetos de planejamento são 80 usuários, 32 chats novos e 1.200 envios. Mais dois fatos moldam um plano. As mensagens de um número saem uma de cada vez, com cerca de um segundo de intervalo, então uma fila de 120 respostas leva cerca de dois minutos para esvaziar. E a conta aceita 100 requisições de API a cada 10 segundos, ou seja, 10 por segundo, o mesmo ritmo de 10 números enviando a toda velocidade. Acima disso, faça fila do seu lado.

Conte os usuários ativos como a whasp conta: pessoas que escreveram nos últimos 30 dias corridos, não o total de cadastros. Quem fica quieto sai da contagem depois de 30 dias. GET /v1/numbers/{number}/chats lista quem escreveu e quando, então você consegue medir.

Como calcular quantos números você precisa?

O cálculo usa três dados dos seus próprios números: usuários ativos (U), usuários novos no seu dia mais movimentado (S) e mensagens que você envia no seu dia mais movimentado (M). Cada limite dá uma contagem, e vale a maior:

• por usuários: U / (100 x 0,8) = U / 80
• por cadastros: S / (40 x 0,8) = S / 32
• por envios: M / (1.500 x 0,8) = M / 1.200

Depois some uma reserva de 10%, de pelo menos um número. Quando um número vira critical (banido, deslogado, celular offline por mais de 10 minutos ou envios falhando), o /numbers/pick para de oferecê-lo e a parte dele nos novos cadastros cai nos outros. O substituto chega sem custo, mas vazio, e a sua própria lógica move os usuários. A reserva é onde eles cabem enquanto isso acontece. Cada número custa $49 a cada 30 dias.

// Limites por número da referência da API da whasp, e a carga para a qual planejamos.
const LIMITS = { users: 100, signups: 40, sends: 1500 };
const PLAN = 0.8; // acima de 80% de um limite o número é sinalizado como at_risk

export function numbersNeeded(users: number, busiestDaySignups: number, busiestDaySends: number) {
  const byUsers = Math.ceil(users / (LIMITS.users * PLAN));
  const bySignups = Math.ceil(busiestDaySignups / (LIMITS.signups * PLAN));
  const bySends = Math.ceil(busiestDaySends / (LIMITS.sends * PLAN));
  const base = Math.max(byUsers, bySignups, bySends);
  const spare = Math.max(1, Math.ceil(base * 0.1)); // folga para um número que vire critical
  return { byUsers, bySignups, bySends, base, spare, total: base + spare, monthlyUsd: (base + spare) * 49 };
}

Como ficam três planos de tamanho real?

Os três planos abaixo usam suposições de exemplo, não medições. Troque-as por números dos seus próprios logs.

Um tutor de idiomas com 3.000 usuários ativos

Suponha que 25% dos usuários ativos escrevem em um dia qualquer, que o agente envia 12 mensagens a cada um, que o dia mais movimentado é o dobro da média e que um lançamento traz 400 usuários novos em um dia.

• Envios: 3.000 x 0,25 x 12 = 9.000 em um dia médio, 18.000 no mais movimentado.
• Por usuários: 3.000 / 80 = 37,5, então 38. Por cadastros: 400 / 32 = 12,5, então 13. Por envios: 18.000 / 1.200 = 15.
• A maior é 38. Reserva: 10% de 38 = 3,8, então 4. Total de 42 números, 42 x $49 = $2.058 por mês, ou $0,69 por usuário ativo.

Aqui quem decide são os usuários.

Um companheiro que fala muito, com 1.200 usuários ativos

Suponha que 50% escrevem em um dia qualquer, que o agente envia 40 mensagens a cada um, que o dia mais movimentado é 1,5 vez a média e que 100 usuários novos chegam nele.

• Envios: 1.200 x 0,5 x 40 = 24.000 em um dia médio, 36.000 no mais movimentado.
• Por usuários: 1.200 / 80 = 15. Por cadastros: 100 / 32 = 3,1, então 4. Por envios: 36.000 / 1.200 = 30.
• A maior é 30. Reserva 3. Total de 33 números, 33 x $49 = $1.617, ou $1,35 por usuário ativo.

Aqui quem decide são as mensagens. Com 80 usuários por número, 1.200 envios por dia dão 15 mensagens por usuário ativo por dia. Este companheiro envia 30 por usuário ativo no dia mais movimentado, então precisa do dobro dos números que a sua quantidade de usuários sugere.

Um lançamento com 1.000 cadastros em um dia

Suponha 1.000 usuários no total e 6.000 mensagens enviadas nesse dia.

• Por usuários: 1.000 / 80 = 12,5, então 13. Por cadastros: 1.000 / 32 = 31,25, então 32. Por envios: 6.000 / 1.200 = 5.
• A maior é 32. Reserva 4. Total de 36 números, $1.764 por mês.

Agora espalhe os mesmos 1.000 cadastros por cinco dias, 200 por dia, com 1.200 envios no dia mais movimentado:

• Por usuários: 13. Por cadastros: 200 / 32 = 6,25, então 7. Por envios: 1.200 / 1.200 = 1.
• A maior é 13. Reserva 2. Total de 15 números, $735 por mês.

Uma lista de espera ou códigos de convite economizariam 21 números e $1.029 por mês. Neste exemplo, o limite que pesa são os chats novos por dia, não os usuários.

Como rotear os usuários novos e mantê-los em um número?

GET /v1/numbers/pick devolve o número saudável e online com mais folga para um usuário novo, e um link wa.me que abre o chat. Passe text e o link abre com essa mensagem pré-preenchida. Coloque nela o id do seu usuário, para o agente saber quem está escrevendo (mais sobre links de onboarding).

const API = "https://api.whasp.ai/v1";
const headers = { Authorization: `Bearer ${process.env.WHASP_API_KEY}` };

/** O link para mostrar a um usuário novo, ou null quando todos os números estão cheios. */
export async function signupLink(userId: string): Promise<string | null> {
  const params = new URLSearchParams({ text: `Oi, meu código é ${userId}` });
  const res = await fetch(`${API}/numbers/pick?${params}`, { headers });
  if (res.status === 409) return null; // no_capacity: segure o cadastro e adicione um número
  if (!res.ok) throw new Error(`pick falhou com ${res.status}`);
  const { wa_link } = (await res.json()) as { number: string; wa_link: string };
  return wa_link;
}

Um chat fica no número dele. Quando você envia sem from, a whasp usa o número para o qual a pessoa escreveu por último, que é o que você quer. Um from diferente devolve 409 chat_not_open, a menos que essa pessoa também tenha escrito para esse número.

Quando signupLink devolve null, mostre uma tela de espera e adicione números. Adicione antes de precisar: POST /v1/numbers pode responder 503 no_capacity quando nenhum está pronto (nada é cobrado), e um número montado do zero leva cerca de 30 minutos.

Como acompanhar a folga e adicionar números?

Consulte GET /v1/numbers a cada poucos minutos. Cada número informa seus stats e seus limits, então você consegue somar a folga restante até 80% nos números saudáveis e alertar sobre qualquer número que não esteja healthy. O webhook number.status_changed avisa no instante em que health ou online mudam (tratamento de webhooks).

type Num = {
  number: string;
  status: "provisioning" | "active" | "retired";
  health: "healthy" | "at_risk" | "critical";
  stats: { active_chats_30d: number; new_chats_24h: number; outbound_24h: number };
  limits: { active_chats_30d: number; new_chats_24h: number; outbound_24h: number };
};

/** Folga livre nos números saudáveis, contada até 80% de cada limite. */
export async function headroom() {
  const res = await fetch(`${API}/numbers`, { headers });
  const { data } = (await res.json()) as { data: Num[] };
  const live = data.filter((n) => n.status === "active");
  const sick = live.filter((n) => n.health !== "healthy").map((n) => n.number);
  const room = { users: 0, signups: 0, sends: 0 };
  for (const n of live.filter((n) => n.health === "healthy")) {
    room.users += Math.max(0, Math.floor(n.limits.active_chats_30d * PLAN) - n.stats.active_chats_30d);
    room.signups += Math.max(0, Math.floor(n.limits.new_chats_24h * PLAN) - n.stats.new_chats_24h);
    room.sends += Math.max(0, Math.floor(n.limits.outbound_24h * PLAN) - n.stats.outbound_24h);
  }
  return { numbers: live.length, sick, room };
}

/** Adiciona um número. Isso cobra $49 na hora, então chame com um teto. */
export async function addNumber(label: string): Promise<Num> {
  const res = await fetch(`${API}/numbers`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ label, profile: { name: "Ava", about: "Sua amiga de IA" } }),
  });
  if (res.status === 402) throw new Error("saldo baixo demais: recarregue primeiro");
  if (res.status === 503) throw new Error("no_capacity: nada foi cobrado, tente de novo mais tarde");
  if (!res.ok) throw new Error(`add falhou com ${res.status}`);
  return (await res.json()) as Num;
}

Chame addNumber quando room.users ficar abaixo dos cadastros que você espera nas próximas duas semanas, ou room.signups abaixo do seu dia mais movimentado, e limite o total para que um bug não gaste o seu saldo. Mantenha o saldo acima de números x $49: um número renova sozinho enquanto o saldo cobre, e quando o saldo acaba ele tem 3 dias de tolerância e depois é aposentado.

Vários produtos ou clientes

Uma conta tem uma única URL de webhook, então mantenha um pool por produto, persona ou cliente e diferencie-os do seu lado. Dê a cada número um label como tutor-fr-1, defina o perfil dele (nome, recado e foto) de acordo com a persona e roteie cada evento pelo campo number. Rode numbersNeeded por pool. A cobrança é um único saldo, então cobre de cada cliente, do seu lado, a quantidade de números dele x $49.

Como se comparam os limites da API do WhatsApp Business?

A Meta limita as pessoas únicas que uma empresa pode contatar fora da janela de atendimento ao cliente de 24 horas, a cada 24 horas móveis e por portfólio empresarial, compartilhado por todos os números dele. Portfólios novos começam em 250. A verificação, ou o envio de 2.000 mensagens entregues com alta qualidade, sobe o limite para 2.000. Depois disso ele sobe automaticamente para 10.000, 100.000 e ilimitado quando as suas mensagens têm alta qualidade e você usou pelo menos metade do limite nos últimos 7 dias.

A plataforma oficial escala por cota, a whasp por celulares. As respostas dentro da janela não fazem parte do nível da Meta e não encontramos teto de usuários ativos por número oficial, então, para um agente que a Meta admite, um número oficial pode atender um público muito grande. Se a sua IA é permitida ali é a primeira pergunta, e a comparação de preços mostra quanto custa a rota oficial.

O que fazer agora

Tire três números dos seus próprios logs: usuários ativos em 30 dias corridos, cadastros no seu dia mais movimentado e mensagens enviadas no seu dia mais movimentado. Rode numbersNeeded e adicione os números um lançamento antes. Monte a checagem de folga e leia por que o WhatsApp bane números para dimensionar a sua reserva.