FAQ da API de SMS

Instale o SDK e envie para o destinatário de teste autorizado +15005550006 em cerca de cinco minutos. Pode configurar uma verificação de CI antes de provisionar um número.

Um endpoint de envio, receção bidirecional, provisionamento de números (long codes, short codes, toll-free e sender IDs alfanuméricos), conformidade A2P 10DLC e opt-out, encaminhamento direto para operadora e análise de entregas — tudo numa única API.

A Bird alcança mais de 150 países através de mais de 240 ligações diretas a operadoras, com reseleção de rotas de nível operador quando um caminho de operadora se degrada.

Para enviar tráfego application-to-person para números dos EUA, sim. O registo de marca e campanha é feito no dashboard, e o estado pode ser consultado através da API.

Por mensagem, a uma tarifa que depende do país de destino e do tipo de remetente utilizado, pelo que um código longo dos EUA e um sender alfanumérico do Reino Unido são cobrados separadamente. As tarifas são publicadas por país na página de preços de SMS.

Sim, a faturação é por segmento e não por mensagem. Um segmento contém 160 caracteres GSM-7, ou 70 quando um único emoji ou carácter não latino força toda a mensagem para Unicode. Texto mais longo é dividido e cada segmento é cobrado, pelo que um carácter extra pode duplicar o custo de uma campanha grande.

Taxas das operadoras aplicam-se por mensagem e variam consoante o destino e a operadora. Nos EUA, 10DLC também inclui taxas de registo de marca e campanha. Ambas estão listadas na página de taxas de operadoras de SMS.

O registo de SMS mostra a contagem de segmentos e o custo de cada mensagem individual assim que é tarifada; as métricas de SMS agregam volume aceite, segmentos e gastos ao longo do tempo.

Uma mensagem GSM-7 comporta 160 caracteres por segmento; mudar para Unicode (UCS-2) para emoji ou scripts não latinos reduz para 70. Mensagens mais longas são concatenadas em vários segmentos, e o SDK indica a contagem antes do envio.

Doze segmentos, o que corresponde a aproximadamente 1.836 caracteres GSM-7 ou 804 Unicode. A Bird nunca trunca: um corpo acima do limite retorna um erro 422. O limite conta segmentos em vez de caracteres precisamente porque as duas codificações comportam quantidades diferentes.

Até 100 numa chamada batch, cada uma com o seu próprio destinatário e texto. Uma mensagem individual vai para exatamente um destinatário, por isso um batch é como se faz a distribuição.

Uma chave de plano gratuito permite 10 envios individuais e 5 chamadas batch por minuto, e os planos pagos aumentam ambos. Cada resposta inclui um cabeçalho IETF RateLimit que indica o que resta e quando a janela reinicia — ajuste o ritmo com base nisso em vez de um número fixo no código.

Isso é definido pelas operadoras, não pela Bird. Um long code 10DLC registado obtém throughput com base na pontuação de confiança da marca e no tipo de campanha: mais do que um número não registado, menos do que um short code. Short codes obtêm a taxa mais alta e previsível.

Para tráfego de aplicação nos EUA, um código longo 10DLC cobre a maioria dos casos de uso bidirecional e OTP. Programas de alto volume de um-para-muitos passam para um código curto; toll-free é uma opção para EUA/Canadá sem 10DLC.

Um código longo ou número toll-free está disponível imediatamente e começa a enviar assim que o seu registo ou verificação for aprovado. Códigos curtos são avaliados pelas operadoras e normalmente demoram semanas.

Sim. Códigos longos, códigos curtos e números toll-free são bidirecionais: aponte o tráfego de entrada de um número para um webhook e as respostas chegam como eventos assinados. Sender IDs alfanuméricos são apenas unidirecionais.

Depende do tipo de remetente e do país. O tráfego de aplicação nos EUA precisa de A2P 10DLC, toll-free precisa de verificação, e muitos países exigem pré-registo do sender ID — tudo gerido a partir do painel.

É uma string de texto curta, geralmente o nome da sua marca, que aparece no campo "de" do destinatário em vez de um número de telefone. É um rótulo na mensagem, não um número que lhe pertence.

Mantenha-a curta: normalmente até 11 caracteres em redes GSM. A restrição exata depende do país de destino e da operadora, e do que cada um aceita.

Um número toll-free é um número 8xx (800, 888, 877 e os restantes prefixos toll-free) que envia e recebe SMS nos EUA e no Canadá. Transporta tráfego de aplicações sem A2P 10DLC, após ter passado a verificação toll-free.

Não. Os números toll-free estão fora do sistema A2P 10DLC. Em vez disso, passam pela verificação toll-free, onde as operadoras analisam o caso de uso e o conteúdo das mensagens antes de o número poder enviar a volume total.

Um long code de 10 dígitos (10DLC) é um número de telefone local padrão autorizado para SMS application-to-person nos EUA, uma vez que a sua marca e campanha estejam registadas junto das operadoras.

Long codes 10DLC registados obtêm throughput verificado que depende da pontuação de confiança da marca e do tipo de campanha: mais do que um número não registado, menos do que um short code.

Um short code é um número de 5–6 dígitos aprovado pelas operadoras para SMS de alto volume de um-para-muitos: campanhas de marketing, alertas e OTP de alta taxa. É o tipo de remetente com maior throughput e passa por verificação da operadora antes de poder enviar.

Planeie em semanas, não em minutos. As operadoras analisam cada programa de short code antes de o ativar, pelo que um short code tem um tempo de espera real — ao contrário de um long code, que pode comprar e começar a enviar assim que o registo for aprovado.

Um short code dedicado é exclusivamente seu, pelo que a sua reputação de envio é inteiramente sua. Um short code partilhado divide um número entre remetentes através de palavras-chave: mais barato, mais rápido para começar, mas herda a reputação de todos os outros que o utilizam.

É você, num envio de texto livre: passe um número que o seu workspace possua, um short code ou um sender ID alfanumérico onde o país de destino o permita. Se o omitir, o envio é rejeitado em vez de ser adivinhado. Um envio por template é a exceção, porque seleciona o seu próprio remetente.

Indica à Bird e às operadoras o motivo do envio, e regras de conformidade por país — como política de opt-out e horários silenciosos — dependem dela. É obrigatória num envio de texto livre; um envio por template herda a classificação do próprio template.

Passe uma chave de idempotência e um pedido retentado devolve o resultado original em vez de enviar duas vezes. Sem ela, a retentativa é tratada como uma nova mensagem.

Cada mudança de estado dispara um webhook assinado com HMAC (queued, sent, delivered ou failed), incluindo o recibo de entrega da operadora e a contagem de segmentos.

Cada mensagem enviada para o seu número provisionado chega como um webhook sms.received assinado com HMAC. Verifica uma assinatura, lê o from, to e text, e encaminha para a sua própria lógica — o mesmo envelope que já processa para recibos de entrega.

Sim. Responda enviando a partir do mesmo número em que a mensagem foi recebida. Defina from para o seu número e to para o remetente original, e a conversa mantém-se num único número de ponta a ponta.

Bird adds the sender to your suppression list and fires sms_suppression.created, and blocks later sends from that sender to that number automatically. HELP returns a help reply and START opts them back in, all handled before they reach your code, so you stay compliant without writing the keyword logic yourself.

Precisa de um número compatível com comunicação bidirecional. Códigos longos, códigos curtos e números gratuitos suportam mensagens de entrada; IDs de remetente alfanuméricos são apenas de envio e não podem receber respostas.

A sua mensagem é entregue diretamente à operadora móvel através de uma das nossas 240 ligações diretas, sem passar por uma cadeia de revendedores. Menos saltos significa menos pontos onde uma mensagem pode ficar parada ou um recibo de entrega se perder.

Bird reseleciona a rota em tempo real. Se um caminho começa a perder recibos ou a abrandar, a próxima mensagem segue por uma ligação mais saudável para a mesma operadora, e o envio que programou nunca muda.

Cada mensagem devolve um recibo de entrega da operadora como webhook sms.delivered ou sms.failed, contendo mcc_mnc, country e latency_ms. É a confirmação da própria operadora, não uma inferência da nossa parte.

Sim. Fazemos uma consulta MNP em cada envio para identificar a operadora atual do destinatário, de modo que um número portado é encaminhado para a operadora que efetivamente o detém. Para inteligência de números de forma independente, consulte o Lookup.

O encaminhamento equilibra custo e qualidade de entrega por destino. Tráfego transacional como códigos de uso único favorece o caminho de maior qualidade; tráfego em massa pode pender para o menor custo. A seleção acontece por mensagem, por trás da mesma chamada de API.

Do recibo de entrega da operadora (DLR) para cada envio. A Bird regista o recibo associado à mensagem e depois agrega esses recibos em métricas de entrega, falha e latência. Uma contagem de entregues é a operadora a confirmar a receção, não uma estimativa da Bird.

Yes, from its own endpoint. The stats API has one breakdown per dimension (carrier, country, originator, category, status, error code, tag) plus daily and hourly series, and each row carries the one dimension you asked for. Crossing two of them, such as a carrier inside a country, means two calls and joining the rows yourself. A failure rate that looks fine nationally often turns out to be one carrier rejecting one sender ID.

Ambos. Cada estado de entrega já chega como webhook, por isso pode construir o seu próprio armazenamento a partir do fluxo de eventos. A API de estatísticas existe para quando quiser que a Bird faça a agregação em vez de manter um contador por conta própria.

Passe o ID da mensagem ao endpoint de eventos e obtém a cronologia completa: em fila, enviada, entregue ou falhada, cada uma com timestamp e, em caso de falha, o código de motivo da operadora. Este é o relatório de que realmente precisa quando um cliente diz que um SMS nunca chegou.

Sim. O opt-out é reversível. Um destinatário que envie START é removido da lista de supressão e pode voltar a receber mensagens. A escolha é sempre do destinatário.

A lista de supressão é um recurso da API consultável. Verifique um número antes de construir uma audiência para que um destinatário que fez opt-out nunca volte a entrar num envio.

Depende de para onde envia e do que envia. Tráfego de aplicação nos EUA requer registo de marca e campanha A2P 10DLC. Muitos países exigem pré-registo de sender ID para remetentes alfanuméricos. A gestão de opt-out aplica-se em todo o lado e não requer configuração.

A Bird submete cada registo às operadoras ou registos e reporta o seu estado através da API. O seu código pode consultar o estado do registo por polling e aguardar a aprovação em vez de enviar para uma campanha que ainda não está ativa.

Não. Usa o mesmo cliente e chaves que o envio, números e comunicação bidirecional. O estado do registo e a lista de supressão são recursos da API ao lado da chamada de envio, por isso uma única integração cobre tanto o envio como as regras associadas.

Para combater a falsificação de identidade, muitos países só entregam sender IDs alfanuméricos que tenham sido pré-registados junto das operadoras locais ou do regulador. Onde essa regra se aplica, um remetente de marca não registado é rejeitado ou reescrito.

A Bird. Submete o sender ID e o destino a partir do painel, a Bird encaminha-o para o registo local e a API reporta o estado para que saiba quando o remetente está ativo.

A aprovação passa por operadoras e registos externos e varia por país — normalmente dias a semanas. Consulte o estado do registo através da API e aguarde antes de enviar a partir desse sender ID.

A2P 10DLC é o framework das operadoras dos EUA para SMS application-to-person enviados através de long codes padrão de 10 dígitos. Uma empresa regista a marca por trás do seu tráfego e uma campanha que descreve as mensagens, e as operadoras verificam ambos antes de conceder throughput.

A marca é a entidade legal que envia o tráfego. Uma campanha descreve um caso de uso de mensagens específico sob essa marca. Uma marca pode ter várias campanhas, e os números são associados a uma campanha e não à marca.

A verificação da marca e da campanha passa pelas operadoras e pelo registo e normalmente demora dias a semanas. Consulte o estado da campanha através da API para que o seu código aguarde pela aprovação antes de enviar.

Não. O 10DLC é um framework dos EUA. Outros países têm as suas próprias regras, muitos exigindo pré-registo de sender ID, e o tratamento de palavras-chave de opt-out aplica-se onde quer que envie.

A sua chamada para Bird é, via HTTPS, e o webhook de entrada que lhe enviamos também. O último salto não nos compete encriptar: SMS é um protocolo de operadora sem encriptação ponta-a-ponta, e a mensagem é legível no aparelho e pela operadora. É por isso que deve manter informações sensíveis fora do corpo da mensagem e preferir WhatsApp ou email para conteúdo confidencial.

Cada evento é assinado com HMAC. Verifique a assinatura com o segredo do seu endpoint antes de processar o payload, e faça a rotação desse segredo a partir do painel sempre que necessário.

Na região onde a sua organização está alojada, us1 ou eu1. A sua chave de API contém essa informação no prefixo (bk_us1_…, bk_eu1_…), que é como os SDKs e o CLI selecionam o endpoint correto sem necessidade de configuração.

Apenas o que definir no seu âmbito. Uma chave contém uma lista de scopes, cada um com permissão de leitura ou escrita, pelo que uma chave que envia SMS não pode gerir os seus números nem ler outro canal. Ações de gestão como gerir membros e emitir chaves são exclusivas do painel e nenhuma chave lhes tem acesso.

Ambos. Uma chave aceita uma lista de intervalos CIDR e rejeita pedidos de qualquer outra origem, e a rotação mantém a chave antiga a funcionar durante um período de tolerância (24 horas por defeito, ou zero para a cortar imediatamente) para que a transição não necessite de downtime.

Sim. O registo de auditoria é um registo apenas de leitura, a nível de toda a organização, de cada ação de gestão, com o autor, o workspace, a hora e o resultado, e é exportável em OCSF para o seu próprio SIEM.

Certificações e documentação de segurança estão disponíveis no Trust Center em trust.bird.com. O acordo de processamento de dados, a declaração de privacidade e a política de utilização aceitável estão publicados em bird.com/legal. Para um questionário de fornecedor, a equipa de conta Bird trata disso.