contrate online meu vono
Vono
Suporte e tutoriais

Central de Ajuda

Encontre manuais, guias e perguntas frequentes sobre os produtos Vono. Tudo o que você precisa para usar nossas soluções, em um só lugar.

Tutorial Manuais

Máscaras do Asterisk no Dialplan: Guia Completo e Fácil

Entendendo as máscaras do Asterisk no dialplan

As máscaras do Asterisk permitem criar regras de discagem que funcionam para vários números ao mesmo tempo.

Em vez de cadastrar uma regra para cada telefone, ramal ou destino, você cria um padrão capaz de reconhecer diversos números.

Por exemplo, imagine que sua empresa tenha os seguintes ramais:

  • 2000
  • 2001
  • 2002
  • 2150
  • 2999

Como todos possuem quatro dígitos e começam com o número 2, podemos criar uma única regra para todos eles:

exten => _2XXX,1,Dial(PJSIP/${EXTEN},30)
same => n,Hangup()

Nesse exemplo, a máscara _2XXX representa qualquer número com quatro dígitos que comece com 2.

O que é o dialplan do Asterisk?

O dialplan é o conjunto de regras que determina o que o Asterisk deve fazer quando alguém disca um número.

Ele pode ser usado para:

  • encaminhar chamadas para ramais;
  • enviar chamadas por um SIP Trunk;
  • reconhecer números locais, nacionais ou internacionais;
  • criar regras para números especiais;
  • bloquear determinados tipos de chamada;
  • reproduzir mensagens;
  • direcionar chamadas para filas, URAs ou correio de voz.

Pense no dialplan como um mapa de rotas.

Quando alguém disca um número, o Asterisk procura uma regra correspondente e executa as instruções configuradas nela.

O que são máscaras no Asterisk?

Máscaras são padrões usados para reconhecer números que possuem características semelhantes.

Por exemplo:

_2XXX

Essa máscara reconhece números como:

2000
2001
2150
2999

Mas não reconhece:

1500
3000
200
20000

Isso acontece porque a máscara exige:

  • o primeiro dígito igual a 2;
  • mais três dígitos entre 0 e 9.

Por que a máscara começa com _?

Toda máscara do dialplan precisa começar com um sublinhado:

_

É esse caractere que informa ao Asterisk que aquela extensão é um padrão, e não um número exato.

Compare:

exten => 2000,1,Dial(PJSIP/2000)

A regra acima funciona somente para o ramal 2000.

Já esta regra:

exten => _2XXX,1,Dial(PJSIP/${EXTEN})

pode funcionar para qualquer ramal de quatro dígitos que comece com 2.

Sem o _, o Asterisk não interpreta o conteúdo como uma máscara.

Principais caracteres das máscaras

Caractere O que representa Exemplo
X Um dígito entre 0 e 9 _2XXX
Z Um dígito entre 1 e 9 _ZXXX
N Um dígito entre 2 e 9 _NXXX
[ ] Um único caractere entre os valores informados _[234]XXX
[2-6] Um único dígito dentro do intervalo informado _[2-6]XXX
. Um ou mais caracteres adicionais _0800.
! Zero ou mais caracteres, com correspondência imediata _123!

Vamos entender cada um deles.

Máscara com X

O caractere X representa um único dígito entre 0 e 9.

_2XXX

Essa máscara aceita:

2000
2085
2345
2999

Cada X representa exatamente uma posição.

Por isso, _2XXX reconhece números com quatro dígitos, mas não reconhece números com três ou cinco dígitos.

Outro exemplo:

_0800XXXXXXXXX

Nesse caso, o número precisa começar com 0800 e possuir mais nove dígitos.

Máscara com Z

O caractere Z representa um único dígito entre 1 e 9.

Ele não aceita o número 0.

_ZXXX

Essa máscara aceita:

1234
5678
9999

Mas não aceita:

0123

Máscara com N

O caractere N representa um único dígito entre 2 e 9.

Ele não aceita 0 nem 1.

_NXXX

Essa máscara aceita:

2000
3456
9876

Mas não aceita:

0123
1234

Máscaras com colchetes

Os colchetes permitem escolher quais caracteres podem aparecer em determinada posição.

Aceitando números específicos

_[234]XXX

Essa máscara reconhece números com quatro dígitos que começam com 2, 3 ou 4.

Exemplos aceitos:

2000
3123
4999

Exemplos não aceitos:

1000
5000

Mesmo existindo três números dentro dos colchetes, eles representam apenas uma posição.

A leitura da máscara é:

  • o primeiro dígito pode ser 2, 3 ou 4;
  • os outros três dígitos podem variar entre 0 e 9.

Aceitando um intervalo

Também é possível definir um intervalo:

_[2-6]XXX

Essa máscara aceita números que começam com:

2
3
4
5
6

Por exemplo:

2000
3456
4999
5123
6001

Ela não aceita números que começam com 1, 7, 8, 9 ou 0.

Máscara com ponto .

O ponto representa um ou mais caracteres adicionais.

_0800.

Essa máscara reconhece qualquer sequência que:

  • comece com 0800;
  • tenha pelo menos mais um caractere depois disso.

Ela pode reconhecer, por exemplo:

08001
08001234
0800123456789

O ponto é útil quando o tamanho do número pode variar.

Porém, ele deve ser usado com cuidado.

O ponto não representa somente números. Ele pode corresponder a outros caracteres aceitos pelo Asterisk. Uma regra muito ampla pode criar problemas de segurança ou permitir chamadas que não deveriam ser autorizadas.

Sempre que você souber a quantidade exata de dígitos, prefira usar X, Z, N ou intervalos.

Em vez de:

_0800.

pode ser mais seguro utilizar uma máscara com o tamanho esperado:

_0800XXXXXXXXX

A máscara correta depende do formato de numeração utilizado no seu ambiente.

Máscara com exclamação !

A exclamação representa zero ou mais caracteres adicionais.

_123!

Ela pode reconhecer:

123
1234
12345
123456789

A diferença principal é que o ! pode considerar a correspondência completa imediatamente, sem aguardar a entrada de novos dígitos quando não houver outra regra mais específica.

Por esse motivo, seu uso exige bastante cuidado.

Para a maioria das configurações comuns, máscaras com quantidade definida de dígitos são mais fáceis de controlar e manter.

Como interpretar uma máscara passo a passo

Veja a máscara:

_[2-4]NXX

Podemos dividi-la assim:

Posição Regra
Primeiro dígito Pode ser 2, 3 ou 4
Segundo dígito Pode ser qualquer número entre 2 e 9
Terceiro dígito Pode ser qualquer número entre 0 e 9
Quarto dígito Pode ser qualquer número entre 0 e 9

Essa máscara aceitaria:

2200
2399
3275
4980

Mas não aceitaria:

2100
5000
1234

O número 2100 não seria aceito porque o segundo dígito é 1, e o caractere N aceita somente números entre 2 e 9.

Entendendo uma regra completa

Veja este exemplo:

exten => _2XXX,1,Dial(PJSIP/${EXTEN},30)
same => n,Hangup()

Agora vamos separar cada parte.

exten =>

Indica a criação de uma extensão ou regra dentro do dialplan.

_2XXX

É a máscara que identifica os números aceitos.

Nesse caso, são ramais de quatro dígitos que começam com 2.

1

É a primeira prioridade da regra.

As prioridades indicam a ordem em que as instruções serão executadas.

Dial()

É a aplicação usada para iniciar uma chamada.

PJSIP/${EXTEN}

Informa que a chamada será enviada para um endpoint PJSIP correspondente ao número discado.

A variável ${EXTEN} contém o número que a pessoa digitou.

Se a pessoa discar 2040, o valor de ${EXTEN} será:

2040

30

É o tempo máximo, em segundos, que o destino tocará antes de a tentativa terminar.

same => n

Permite adicionar a próxima instrução sem repetir a máscara.

O n significa próxima prioridade.

Hangup()

Encerra a chamada ao final da execução.

É uma boa prática terminar a extensão com Hangup() para evitar que o Asterisk continue procurando outras prioridades ou regras menos específicas.

Exemplo para ramais internos

Imagine que todos os ramais internos tenham quatro dígitos e comecem com 2.

[ramais-internos]

exten => _2XXX,1,NoOp(Chamada para o ramal ${EXTEN})
same => n,Dial(PJSIP/${EXTEN},30)
same => n,Hangup()

Essa regra pode atender ramais como:

2000
2001
2150
2999

A aplicação NoOp() não altera a chamada. Ela apenas adiciona uma mensagem ao log do Asterisk, o que pode ajudar na identificação de problemas.

Exemplo para enviar chamadas por um SIP Trunk

Em uma configuração moderna com PJSIP, uma chamada externa pode seguir uma estrutura como esta:

[saidas-vono]

exten => _0X.,1,NoOp(Chamada externa para ${EXTEN})
same => n,Dial(PJSIP/${EXTEN}@tronco-vono,60)
same => n,Hangup()

Nesse exemplo:

  • a chamada precisa começar com 0;
  • o número completo está disponível em ${EXTEN};
  • tronco-vono representa o nome do endpoint ou tronco configurado no PJSIP;
  • o destino tocará por até 60 segundos.

O nome do tronco e o formato do número enviado devem ser adaptados à configuração do seu servidor e às regras da operadora.

Não copie o exemplo diretamente para um ambiente em produção sem confirmar:

  • o nome correto do endpoint;
  • o formato de numeração exigido;
  • as permissões de chamadas;
  • as regras de segurança;
  • o tratamento de chamadas locais, nacionais e internacionais.

Removendo dígitos com ${EXTEN:n}

O Asterisk permite remover caracteres do começo do número discado.

Considere:

${EXTEN:1}

O número depois dos dois-pontos informa quantos caracteres devem ser removidos do início.

Se o usuário discar:

0011312345678

o valor de:

${EXTEN:1}

será:

011312345678

Foi removido um caractere do início.

Com:

${EXTEN:2}

o resultado seria:

11312345678

Foram removidos os dois primeiros caracteres.

Exemplo usando um prefixo de saída

Imagine que os usuários precisem digitar 0 antes de fazer uma chamada externa, mas que o tronco deva receber o número sem esse primeiro 0.

exten => _0X.,1,NoOp(Número digitado: ${EXTEN})
same => n,Set(NUMERO_DESTINO=${EXTEN:1})
same => n,NoOp(Número enviado: ${NUMERO_DESTINO})
same => n,Dial(PJSIP/${NUMERO_DESTINO}@tronco-vono,60)
same => n,Hangup()

Se o usuário digitar:

011312345678

o Asterisk removerá o primeiro 0 e poderá enviar:

11312345678

O formato correto depende do padrão exigido pela operadora.

Exemplo para números que começam com 0800

Quando o tamanho exato do número é conhecido, prefira uma máscara específica.

Exemplo ilustrativo:

exten => _0800XXXXXXXXX,1,NoOp(Chamada para número 0800)
same => n,Dial(PJSIP/${EXTEN}@tronco-vono,60)
same => n,Hangup()

Caso o ambiente precise aceitar comprimentos diferentes, uma regra com ponto pode ser utilizada:

exten => _0800.,1,NoOp(Chamada para número iniciado em 0800)
same => n,Dial(PJSIP/${EXTEN}@tronco-vono,60)
same => n,Hangup()

A segunda opção é mais ampla e, portanto, exige maior atenção.

Números exatos não precisam de máscara

Quando uma regra deve funcionar para apenas um número, não é necessário usar _, X ou outros caracteres especiais.

exten => 2000,1,Dial(PJSIP/2000,30)
same => n,Hangup()

Essa regra funciona somente quando o número 2000 é discado.

Outro exemplo:

exten => 5000,1,Playback(bem-vindo)
same => n,Hangup()

Ao discar 5000, o Asterisk reproduzirá o áudio configurado.

O Asterisk escolhe a regra mais específica

Às vezes, mais de uma máscara pode corresponder ao mesmo número.

Considere:

_2XXX
_20XX
_200X

O número 2001 poderia corresponder às três máscaras.

Nesse caso, o Asterisk prioriza a regra mais específica.

A máscara _200X é mais específica que _20XX, que é mais específica que _2XXX.

Por isso, evite criar máscaras sobrepostas sem entender qual delas terá prioridade.

Para visualizar as regras de um contexto no console do Asterisk, você pode usar:

dialplan show nome-do-contexto

Para verificar quais regras correspondem a um número específico:

dialplan show 2001@nome-do-contexto

Como testar uma máscara antes de colocá-la em produção

Antes de liberar uma regra para os usuários, faça uma lista com:

  • números que devem ser aceitos;
  • números que não devem ser aceitos;
  • quantidade esperada de dígitos;
  • prefixos que serão removidos;
  • formato enviado ao SIP Trunk;
  • tipos de chamada permitidos.

Por exemplo, para a máscara _2XXX:

Número Deve corresponder? Motivo
2000 Sim Começa com 2 e possui quatro dígitos
2456 Sim Começa com 2 e possui quatro dígitos
1999 Não Não começa com 2
200 Não Possui apenas três dígitos
20000 Não Possui cinco dígitos

Esse teste simples ajuda a evitar regras excessivamente abertas.

Cuidados importantes de segurança

Uma máscara incorreta pode permitir chamadas não autorizadas ou encaminhar números para a rota errada.

Siga estas recomendações:

  1. Prefira máscaras com quantidade definida de dígitos.
  2. Evite usar apenas _X. como regra geral de saída.
  3. Utilize . e ! somente quando realmente necessário.
  4. Separe chamadas locais, nacionais, internacionais e especiais.
  5. Restrinja chamadas conforme o perfil de cada usuário ou contexto.
  6. Teste as regras antes de aplicá-las em produção.
  7. Verifique o formato exigido pela operadora.
  8. Finalize as extensões com Hangup().
  9. Não confie apenas no número digitado pelo usuário para autorizar chamadas.
  10. Mantenha o Asterisk e seus módulos atualizados.

Máscaras como esta são extremamente abrangentes:

_X.

Ela aceita praticamente qualquer sequência iniciada por um dígito.

Uma regra assim pode ser útil em um laboratório, mas normalmente precisa de validações e restrições adicionais antes de ser utilizada em produção.

Chamadas de emergência

Chamadas de emergência exigem planejamento específico.

Não existe uma única regra adequada para todas as empresas, operadoras ou localidades.

A configuração precisa considerar:

  • os números de emergência disponíveis na região;
  • o formato aceito pela operadora;
  • a localização associada ao número de origem;
  • rotas alternativas em caso de falha;
  • disponibilidade de energia e internet;
  • regras e exigências aplicáveis ao serviço contratado.

Não presuma que uma chamada de emergência funcionará apenas porque existe uma máscara no dialplan. Faça testes controlados e valide o projeto com a operadora e com o responsável técnico pelo sistema.

Também não é recomendado copiar regras antigas que forçam todas as chamadas de emergência para uma interface E1. Ambientes atuais podem utilizar diferentes tecnologias e precisam ser avaliados individualmente.

PJSIP e configurações antigas com SIP/

Em tutoriais antigos, é comum encontrar comandos como:

Dial(SIP/2000)

Esse formato está relacionado ao antigo driver chan_sip.

Nas versões modernas do Asterisk, o recomendado é utilizar o res_pjsip, com chamadas no formato:

Dial(PJSIP/2000)

Você também pode encontrar exemplos antigos usando:

Dial(DAHDI/g1/${EXTEN})

O DAHDI ainda pode existir em ambientes com placas de telefonia ou links digitais, mas não representa a configuração mais comum de um SIP Trunk atual.

Ao atualizar um dialplan antigo, não basta trocar SIP por PJSIP. Os endpoints, autenticações, registros e rotas também precisam estar configurados corretamente no pjsip.conf ou na interface de administração utilizada.

Resumo das máscaras

Máscara Significado
_2XXX Quatro dígitos começando com 2
_ZXXX Quatro dígitos, sendo o primeiro entre 1 e 9
_NXXX Quatro dígitos, sendo o primeiro entre 2 e 9
_[234]XXX Quatro dígitos começando com 2, 3 ou 4
_[2-6]XXX Quatro dígitos começando com um número entre 2 e 6
_0800. Sequência iniciada por 0800 e com pelo menos mais um caractere
_123! Sequência iniciada por 123, com zero ou mais caracteres adicionais

Conclusão

As máscaras do Asterisk facilitam a criação de planos de discagem porque permitem que uma única regra reconheça vários números.

Os principais pontos são:

  • toda máscara começa com _;
  • X aceita números entre 0 e 9;
  • Z aceita números entre 1 e 9;
  • N aceita números entre 2 e 9;
  • os colchetes definem valores ou intervalos para uma única posição;
  • o ponto aceita um ou mais caracteres adicionais;
  • a exclamação aceita zero ou mais caracteres e realiza a correspondência imediatamente;
  • ${EXTEN} contém o número discado;
  • ${EXTEN:n} remove caracteres do começo do número;
  • regras específicas são mais seguras e fáceis de controlar;
  • exemplos modernos devem priorizar o uso de PJSIP.

Antes de aplicar qualquer exemplo, adapte os nomes dos endpoints, os contextos, os formatos de número e as permissões às configurações do seu ambiente.

Referências

Não encontrou o que procurava?

Nossa equipe de atendimento está pronta para ajudar você com dúvidas sobre produtos, configurações e suporte técnico.

WhatsApp Central de Atendimento