Inteligência de números de telefone. Tipo de linha, operadora, portabilidade, sinais de fraude.
Consulta de operadora com suporte a MNP nos mesmos canais que transportam o tráfego de SMS e Voice do Bird. Um endpoint, mesma autenticação, mesmo formato de erro de qualquer outro canal Bird — porque a mesma equipa de engenharia construiu todos eles.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();
if (error) throw error;
console.log(data);
// → {
// phone: "+14155550172",
// line_type: "mobile",
// carrier: "T-Mobile USA",
// country: "US",
// ported_from: "AT&T Mobility",
// fraud_score: 0.07,
// valid: true,
// }5 minutos do npm install à primeira consulta
Consulte um número na linguagem que já utiliza.
SDKs em todos os principais runtimes. Respostas do Lookup em menos de 300ms na mediana — rápido o suficiente para condicionar o envio de um SMS.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();Dez campos que teria de reunir de três fornecedores diferentes.
Dados concretos, identificados e auditáveis. Cada um vem de uma fonte real, não de um modelo a adivinhar.
- 01
Deteção de tipo de linha
Móvel, fixo, VoIP, gratuito, premium, pager. Decida se o SMS é sequer possível antes de enviar.
- 02
Identificação da operadora
Nome da operadora atual e código do país por entrada E.164. Atualizado continuamente contra registos MNP.
- 03
Histórico de portabilidade
A operadora anterior de onde o número foi portado. Útil para previsão de custos de encaminhamento e heurísticas de fraude.
- 04
Formato de país e região
Retorna formatação E.164, nacional e internacional; os códigos de país e região que um router necessita.
- 05
Sinais de fraude
Um fraud_score de 0 a 1 por número, combinando velocidade, heurísticas de tipo de linha, flags de portabilidade recente e listas de números conhecidos como maliciosos.
- 06
Validade e acessibilidade
Um booleano valid e uma janela reachable — alguns números são válidos no formato, mas a operadora já não os atribui.
- 07
Consulta em lote
Envie via POST uma lista de até 1.000 números numa única chamada. O mesmo preço por número aplica-se; poupa os round trips.
- 08
Preços com cache inteligente
Um cache de 24h para entradas idênticas é gratuito. Só paga quando a resposta seria efetivamente diferente.
- 09
Webhooks para trabalhos em lote
Para lotes grandes, subscreva lookup.completed e leia o ficheiro de resultado em vez de manter uma ligação HTTP aberta.
- 10
Mesma autenticação, mesmo formato de erro
Uma chave API para Lookup, SMS, Email, WhatsApp, Voice. Um único registo de tipos de erro para todos.
Porque criámos o Lookup
Porque não deveria descobrir que um número é fixo ao ver o SMS falhar.
Já estávamos a executar consultas MNP dentro do encaminhamento de SMS do Bird — tínhamos de o fazer para escolher a rota de operadora mais barata em tempo real. O Lookup é essa mesma consulta, disponibilizada como um endpoint de primeira classe, para que possa filtrar registos, avaliar riscos e prever custos de encaminhamento sem enviar um único SMS. Mesma autenticação, mesmo formato de erro, mesmos webhooks que o resto da plataforma.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.lookup.get({
phone: "+14155550172",
}).safe();
if (error) throw error;
console.log(data);
// → {
// phone: "+14155550172",
// line_type: "mobile",
// carrier: "T-Mobile USA",
// country: "US",
// ported_from: "AT&T Mobility",
// fraud_score: 0.07,
// valid: true,
// }Cada mudança de estado é um webhook.
Payloads assinados com HMAC, protegidos contra repetição, idempotentes. Consultas de número único são síncronas; consultas em lote distribuem-se como webhooks.
{
"type": "lookup.completed",
"id": "evt_2qB72y...",
"created_at": "2026-05-19T15:42:01.221Z",
"data": {
"lookup_id": "lkp_4hQ8m2nT",
"phone": "+14155550172",
"line_type": "mobile",
"carrier": "T-Mobile USA",
"country": "US",
"ported_from": "AT&T Mobility",
"fraud_score": 0.07,
"valid": true
}
}Agenda de tentativas: 5s, 30s, 5m, 30m, 2h, 6h, 12h. Dead-letter após a última tentativa; cada evento em dead-letter pode ser reenviado a partir do dashboard ou da API.
lookup.completedUma consulta (única ou em lote) foi concluída. O payload inclui a resposta completa.lookup.failedNão foi possível realizar a consulta; o payload inclui o envelope de erro.
Consulte o número e depois envie para ele.
Mesma autenticação, mesmo contrato de idempotência, mesmo formato de erro. O Lookup tem a mesma estrutura de qualquer outro endpoint — a diferença é que retorna dados em vez de despachar uma mensagem.
Lookup.
await bird.lookup.get({
phone: "+14155550172",
});Operadora, tipo de linha, portabilidade, sinais de fraude — retornados de forma síncrona em menos de 300ms.
SMS.
await bird.sms.send({
from: "Bird",
to: "+14155550172",
text: `Your code is ${code}.`,
});Mesma autenticação, mesmo formato de erro. Condicione o envio ao resultado da consulta — elimine os fixos antes que lhe custem dinheiro.