Sender IDs de SMS

Um sender é o from que o destinatário vê na sua SMS. Seu espaço de trabalho tem um sender por identidade a partir da qual ele pode enviar, e cada país de destino decide quais tipos de sender aceita e o que exige de registro prévio. Ter um sender não é o mesmo que ter permissão para enviar a partir dele: são etapas separadas, e este guia cobre ambas.

Os senders ficam na página Senders, uma linha por sender, com seu status e quantos destinos estão ativos, pendentes ou precisam da sua atenção. A chamada de envio em si, incluindo como um valor from é validado, está em Enviando SMS.

Tipos de sender

O sender_type de um sender é o tipo de identidade que ele representa, e determina o que cada país exige dele:

Sender ID alfanumérico: uma string curta de marca como BIRD, de 3 a 11 letras ASCII, dígitos, espaços, hifens, underscores ou pontos, com pelo menos uma letra. Espaços, hifens, underscores e pontos não podem ser o primeiro nem o último caractere. Os destinatários veem seu nome em vez de um número e não podem responder. Muitos países exigem registro antes de permitir tráfego, e alguns, incluindo os Estados Unidos, não aceitam esse tipo. Você mesmo reivindica esse tipo.
Long code: um número comum que você possui, que pode enviar e receber. Um long code dos EUA precisa de uma marca e campanha registradas antes de transportar tráfego application-to-person; veja Registro 10DLC.
Número toll-free: um número cujo custo é pago pelo destinatário da chamada, que na América do Norte também pode transportar mensagens. Enviar a partir de um deles exige completar a verificação toll-free primeiro.
Short code: um número nacional curto para um programa de mensagens aprovado, com comprimento e throughput determinados pelo mercado e pelo programa da operadora. Bird aloca short codes em vez de vendê-los, então esse tipo não é autoatendimento.

Um sender também informa source_kind, que diz o que o sustenta: alpha para uma string de sender que você reivindicou, number para um número dedicado que você possui e shared_number para um número gerenciado por Bird a partir do qual seu espaço de trabalho envia. O dashboard rotula esses como Alphanumeric, Dedicated number e Shared number. Tipos de número explica como o tipo de um número é escolhido, e Comprar e liberar um número explica como alocar um.

Quais tipos um país aceita, e se ele os analisa, muda conforme operadoras e reguladores revisam suas regras. Destinos de SMS publica a posição atual por país; consulte lá em vez de presumir que um país se comporta como seus vizinhos.

Reivindicar um sender ID alfanumérico

Reivindicar uma string de sender não tem custo e entra em vigor imediatamente. Na página Senders, abra Add sender e escolha Add sender ID, depois insira a string. Pela API:

Exemplo de código

bird sms senders create --type alpha --sender BIRD

A resposta traz o id do novo sender, prefixado com snd_, e todas as outras operações neste guia usam esse id. Um claim bem-sucedido pode enviar onde o registro é ausente ou opcional assim que esses destinos estiverem habilitados. Registro obrigatório precisa ser aprovado primeiro.

Duas recusas aparecem aqui. Um 412 significa que sua organização não concluiu a verificação de identidade que esta operação exige: conclua-a em Identity Center e tente novamente. Um 409 significa que a string de sender já foi reivindicada.

alpha é o único tipo que esta chamada cria. Um número dedicado se torna um sender quando você o aloca do inventário, então comprar o número já traz o sender junto. Short codes e números compartilhados chegam a um espaço de trabalho por alocação de Bird, não por compra.

Verificar o que um país exige

Uma única leitura responde o que cada país exige de um sender. Ela retorna uma linha por país que o sender pode alcançar, e cada linha é completa por si só:

Exemplo de código

bird sms senders requirements snd_01krdgeqcxet5s7t44vh8rt9mg
bird sms senders requirements snd_01krdgeqcxet5s7t44vh8rt9mg --country-code NL

Omita --country-code para todos os países relevantes para o sender. Um resultado filtrado vazio significa que o sender não tem rota para aquele país.

Leia seis campos em uma linha antes de enviar:

registration_mode é none, optional ou required. none não exige registro de país. Quando combinado com um sender ID overwritten, o registro fica indisponível. Registros explícitos mais antigos ainda podem ser gravados para políticas none com comportamento unknown ou preserved, mas nunca bloqueiam o envio. optional permite que o sender continue enviando enquanto você o registra. required bloqueia o envio até a aprovação.
program identifica o fluxo de registro quando o país nomeia um, como alpha ou numeric. Pode ser null quando nenhum programa nomeado se aplica.
sender_id_behavior é unknown, preserved ou overwritten. É independente de registration_mode: um registro obrigatório ainda pode deixar o sender ID sobrescrito após a aprovação. Registro opcional informa overwritten antes da aprovação e preserved após a aprovação para as categorias de mensagem aprovadas.
status indica a posição do sender no programa de registro do país. No modo required, o envio aguarda approved. No modo optional, o status acompanha o trabalho de registro, mas não bloqueia o envio. Status de registro lista cada valor.
destination_enabled indica se o seu espaço de trabalho tem esse país ativado. Essa é uma configuração do espaço de trabalho, não do sender, e é verificada primeiro, então um registro totalmente aprovado ainda recusa mensagens enquanto o destino estiver desativado. Ative países em Destinations; Enviando SMS cobre a lista de permissões.
next lista o que faz o país avançar, em ordem. Uma lista vazia significa que nada está pendente. Cada entrada nomeia uma ação e diz por que vale a pena realizá-la; assim, um país em análise pela operadora nomeia o recurso a ser lido em vez de repetir um veredito que pertence a esse recurso.

As linhas também trazem timeline_min_days e timeline_max_days, o menor e o maior prazo que a aprovação de um país costuma levar em dias úteis, e null quando o país não publica uma estimativa. Quando um registro foi recusado, rejection_reason diz o motivo.

A mesma informação aparece na página de detalhes de cada sender no dashboard, como uma tabela Destinations com colunas Status, Country e Category. Um país que você não ativou e para o qual não se registrou fica fora dessa tabela, porque nada está pendente ali.

Registrar um sender para um país

O registro é por país, e a chamada recebe o sender e o país juntos:

Exemplo de código

bird sms senders registrations create snd_01krdgeqcxet5s7t44vh8rt9mg --country-code NL
bird sms senders registrations create snd_01krdgeqcxet5s7t44vh8rt9mg --country-code NL --category marketing

--category restringe o registro a uma entre transactional, marketing, authentication ou service. Omita-o para registrar em todas as categorias. O dashboard executa a mesma chamada a partir do botão Register na linha do país do sender.

O que acontece em seguida depende do país. Quando o país analisa registros, o registro volta como pending e nada é cobrado ainda. Quando o país não analisa nada, ele é aprovado nessa mesma chamada. Registrar um número é gratuito; um sender alfanumérico com custo traz uma taxa de configuração e uma cobrança mensal recorrente, faturadas no momento em que o registro é aprovado, então um registro sob análise é criado sem cobrança. Nem esta chamada nem a leitura de requisitos exibem um preço, então pergunte a quem é responsável pela conta quanto custa um registro antes de criá-lo.

Quando um programa coleta suas respostas em um formulário, o registro fica em pending até que você o preencha. A linha do país do sender então oferece Complete, que abre as perguntas que o programa faz sobre seu negócio e suas mensagens.

Quatro recusas a tratar:

Resposta	O que significa
402	A carteira não cobriu o valor devido quando a cobrança foi executada. Adicione saldo e tente novamente.
409	Já existe um registro para este país em algum estado diferente de rejeitado ou suspenso, incluindo um ainda em pending revisão. O status por si só não decide se o remetente pode enviar: verifique registration_mode, destination_enabled e se o registro cobre a categoria da mensagem.
412	Sua organização tem um requisito de verificação de identidade não atendido. Conclua-o no Identity Center e tente novamente.
422	O remetente é coberto por um programa com caminho próprio, como 10DLC dos EUA, verificação toll-free ou um short code. Consulte Programas com caminho próprio.

Um registro recusado é reenviado, e um suspenso é reativado, chamando essa mesma operação novamente em vez de usar uma operação separada.

Status de registro

Um registro de país passa pelos estados abaixo. O dashboard exibe cada um como um rótulo com inicial maiúscula na linha do sender:

Status	O que significa e o que fazer
registration_required	O registration_mode do país é required e nenhum registro foi iniciado. Registre o sender para o país.
pending	O trabalho de registro foi iniciado. Onde o programa pede um formulário, conclua-o a partir de Complete na linha do país.
under_review	As informações enviadas estão em análise ou precisam de alterações. O program_ref da linha aponta para o recurso do próprio programa, o único lugar onde uma análise em andamento se distingue de uma que aguarda você.
bird_approved	A análise de Bird foi aprovada e a aprovação da operadora está pendente. Nada é solicitado a você.
carrier_pending	Enviado à operadora ou registro aprovador. Nada é solicitado a você.
approved	Registro aprovado.
rejected	O registro foi recusado. Leia rejection_reason, corrija e registre novamente a partir de Resubmit.
suspended	Um registro anteriormente ativo está suspenso. Registre novamente a partir de Register again para reativá-lo.
not_required	Nenhum registro ativo bloqueia o envio. Verifique registration_mode e sender_id_behavior: none não exige registro de país e o torna indisponível quando o sender ID é sobrescrito; optional oferece registro sem bloquear o tráfego.

Novos status são adicionados conforme os programas de registro mudam, então trate um valor desconhecido como algo que seu código ainda não trata em vez de tratá-lo como erro, e leia o next da linha para saber o que fazer com o país.

Alguns programas abrem vários países com um único registro, então uma única verificação toll-free ou registro de campanha pode ser o que libera vários destinos.

Status do sender e próximas ações

O status do próprio sender reflete o que o sender possui, que é uma questão diferente de saber se um determinado país aceitará uma mensagem:

active: nada que este sender possui está pendente. Um sender que não se registrou em lugar nenhum mostra active, mesmo quando todos os países que ele pode alcançar exigem registro.
pending_number_ownership: a documentação que comprova que você possui o número deste sender não está em ordem, seja porque não foi fornecida ou porque o país que emitiu o número ainda não a aceitou. Todo envio a partir deste sender é recusado até que isso seja resolvido. Visão geral de números explica esse ciclo de vida.
pending_registrations: o sender possui registros de país e nenhum foi aprovado ainda. Isso abrange tanto um registro em análise quanto um que foi recusado, então leia next para saber qual é o caso.

Junto a ele, destinations agrupa os países para os quais o sender está configurado por quem deve agir em seguida, e a lista Senders mostra os três grupos como colunas:

"Active": países para os quais você pode enviar, ativados nas suas configurações de destino e que não exigem registro obrigatório ou possuem um registro aprovado. Um registro opcional ainda pode estar pendente enquanto o envio permanece disponível com o sender ID sobrescrito.
"Pending": países cujo registro está em andamento e aguardando Bird ou uma operadora. Nada é exigido de você; esses passam para "Active" após a aprovação.
"Needs attention": países para os quais você se registrou que não estão funcionando e aguardam uma ação sua, porque o registro foi recusado ou retirado, ou porque está aprovado enquanto o destino está desligado.

Esses três grupos cobrem apenas países para os quais você tem um registro, então um país para o qual você poderia se registrar e não se registrou não aparece em nenhum deles. Para tudo que o sender pode alcançar e o que cada país exigiria, leia o que um país exige.

Uma leitura de sender que calcula as próximas ações as retorna em next, o mesmo campo de roteamento que as linhas de requisitos trazem. Um sender só conhece a si mesmo, então quando o trabalho é por país, ele nomeia a leitura de requisitos em vez de adivinhar qual país você quis dizer.

Programas com caminho próprio

O program de um país nomeia o esquema de registro que ele aplica a um tipo de sender. Dois deles são atendidos pela chamada de registro neste guia, e três têm caminho próprio:

Programa	A que se aplica	Onde acontece
alpha	um sender ID alfanumérico	Registrar um remetente para um país, mais o formulário que o país solicita
numeric	um long code	Registrar um remetente para um país, mais o formulário que o país solicita
10dlc	um long code dos EUA	Registre uma marca e uma campanha, depois vincule o número: Registro 10DLC
tfn	um número toll-free dos EUA	Verificação toll-free, na página Toll-free verifications
short_code	um short code	Bird gerencia a solicitação; nada é pedido a você, a menos que ela seja rejeitada, quando o next da linha direciona você ao suporte

Chamar a operação de registro para um remetente coberto por 10dlc, tfn ou short_code retorna 422. Use o programa correspondente.

A verificação toll-free começa como um rascunho que você preenche em uma ou mais atualizações e depois envia para a operadora analisar. Ela passa por draft, submitted, under_review, info_requested, approved e rejected. Uma verificação em info_requested pode ser editada e reenviada; uma recusada pode ser reenviada enquanto a janela de reenvio estiver aberta. O envio entrega o dossiê à operadora para análise, então uma pessoa autoriza essa etapa: o CLI e o servidor MCP de Bird podem rascunhar e corrigir uma verificação, e o envio em si acontece no dashboard.

Parar de enviar a partir de um sender

Três formas de encerramento diferem no que preservam, e todas as três são ações no dashboard na página de detalhes do sender. Taxas de configuração já cobradas não são reembolsadas por nenhuma delas:

Ação	O que faz
Deregister de um país	Cancela a cobrança recorrente e mantém o registro. Registrar aquele país novamente retoma o mesmo registro sem pagar a taxa de configuração duas vezes. Quando o país exige registro, os envios para lá param; quando o registro é opcional, os envios continuam, porque o registro nunca os bloqueou.
Remove de um registro	Remove o registro do país inteiramente, cancela a cobrança recorrente e para de listar o destino para o sender. Registrar o país novamente é um novo registro e paga a taxa de configuração outra vez.
Excluir o sender	Libera um sender alfanumérico. Todo registro de país nele é removido, a cobrança recorrente é cancelada e ele deixa de ser utilizável. Reivindicar a mesma string depois cria um novo sender com novos registros e paga as taxas de configuração uma segunda vez.

Um sender respaldado por um número não é excluído aqui: libere o número dedicado, o que encerra o sender junto. Um sender em um número compartilhado gerenciado por Bird não pode ser removido.

Uma linha 10DLC ou toll-free é desfeita pelo seu próprio programa, desvinculando a campanha ou cancelando a verificação, em vez de cancelar o registro.

Próximos passos

Compare números e sender IDs de SMS, ou revise registro de sender para seu rollout.

Página	O que aborda
Enviando SMS	A chamada de envio, os formatos de from que ela aceita e a allowlist de destinos
Registro 10DLC	O modelo de marca, campanha e número por trás do envio A2P nos EUA
Tipos de número	Escolha entre números móveis, locais, nacionais, toll-free e short code
Destinos de SMS	Quais tipos de sender cada país aceita e quais deles precisam de registro
Opt-outs e palavras-chave	As respostas de palavra-chave que um sender deve honrar e as supressões que elas criam

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaRegistering your SMS sender ID Entenda o conceitoWhat is sender ID registration, and why do some countries require it?Explore a funcionalidadeSMS sender IDs Siga o percurso de aprendizagemBuild your first integration

Obtenha um resumo de implementação