You are viewing the Portuguese (Brazil) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Classifique esta página:

TwiML™ para Programmable Voice

O que é TwiML?

O TwiML (o Twilio Markup Language) é um conjunto de instruções que você pode usar para dizer à Twilio o que fazer ao receber uma chamada, SMS ou fax.

Como o TwiML funciona

Quando alguém faz uma chamada para um dos seus números de telefone da Twilio, a Twilio procura o URL associado a esse número de telefone e envia uma solicitação. A Twilio lê as instruções do TwiML hospedadas por esse URL para determinar o que fazer, seja gravando a chamada, reproduzindo uma mensagem para o autor da chamada ou solicitando que o autor da chamada pressione dígitos no teclado.

Em sua essência, TwiML é um documento XML com tags especiais definidas pela Twilio para ajudar você a criar seu aplicativo Programmable Voice.

Não está fazendo chamadas telefônicas? O TwiML alimenta mais do que apenas o Twilio Programmable Voice. Consulte a documentação sobre como usar o TwiML com Programmable SMS e Programmable Fax.

O seguinte dirá "Hello, world!" quando alguém discar um número da Twilio configurado com este TwiML:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hello, world!</Say>
</Response>

Você sempre pode retornar o TwiML bruto do idioma de sua escolha ou aproveitar as bibliotecas auxiliares da Twilio para criar automaticamente um TwiML válido para você. No exemplo de código abaixo, alterne para sua linguagem de programação da Web preferida para conferir como fica o TwiML acima usando a biblioteca auxiliar.

        
        
        

        Confira nosso breve tutorial sobre como responder a chamadas telefônicas, disponível em nossos seis idiomas compatíveis com a biblioteca auxiliar. Você também pode aproveitar os repositórios do TwiML da Twilio, nossa solução sem servidor que permite escrever TwiML que a Twilio hospedará para que você possa criar um protótipo rapidamente uma solução sem ativar um servidor Web.

        As chamadas outbound (chamadas de um número da Twilio para um número externo) são controladas usando TwiML da mesma maneira. Quando você inicia uma chamada outbound com a API da Twilio, a Twilio solicita que seu TwiML aprenda a gerenciar a chamada.

        A Twilio executa apenas um documento TwiML para o autor da chamada por vez, mas muitos documentos TwiML podem ser vinculados para criar aplicativos de voz interativos complexos.

        Elementos TwiML

        Na linguagem TwiML, os elementos XML são divididos em três grupos: o elemento raiz <Response> , verbos e substantivos.

        Os elementos TwiML (verbos e substantivos) têm nomes que diferenciam maiúsculas de minúsculas. Por exemplo, usar <say> em vez de <Say> resultará em um erro. Os nomes de atributos também diferenciam maiúsculas de minúsculas e camelCased.

        Você pode usar comentários XML livremente no TwiML; o interpretador os ignora.

        O elemento <Response>

        Em qualquer resposta do TwiML a uma solicitação da Twilio, você deve aninhar todos os elementos verbais dentro de <Response>, o elemento raiz da marcação XML da Twilio:

        <?xml version="1.0" encoding="UTF-8"?>
        <Response>
            <Say>
              Essa mensagem deve ser aninhada em um elemento Response
              para que a Twilio a diga ao autor da chamada.
            </Say>
        </Response>

        Qualquer outra estrutura é considerada inválida.

        Verbos TwiML para Programmable Voice

        Os verbos TwiML dizem à Twilio quais ações tomar em uma determinada chamada. Por isso, a maioria dos elementos em um documento do TwiML são verbos do TwiML. Os nomes dos verbos diferenciam maiúsculas de minúsculas, assim como os nomes dos atributos.

        Você pode usar diferentes combinações de verbos TwiML para criar todos os tipos de aplicativos de voz interativos. Os principais verbos TwiML para Programmable Voice são:

        • <Say> - ler o texto para o autor da chamada
        • <Play> - reproduzir um arquivo de áudio para o autor da chamada
        • <Dial> - adicionar outra parte à chamada
        • <Record> - gravar a voz do autor da chamada
        • <Gather> - coletar os dígitos que o autor da chamada digita em seu teclado

        Os seguintes verbos podem ser usados ​​para controlar o fluxo da chamada:

        • <Hangup> - desligar a chamada
        • <Enqueue> - adicionar o chamador a uma fila de autores da chamada
        • <Leave> - remover um autor da chamada de uma fila de autores
        • <Pause> - esperar antes de executar mais instruções
        • <Redirect> - redirecionar o fluxo de chamadas para um documento TwiML diferente
        • <Refer> - Twilio inicia SIP REFER para infraestrutura de comunicação IP
        • <Reject> - recusar uma chamada recebida sem ser cobrada

        Os seguintes substantivos fornecem recursos avançados:

        • <Autopilot> - criar uma URA conversacional com inteligência artificial

        Há certas situações em que o interpretador do TwiML pode não alcançar verbos em um documento do TwiML porque o fluxo de controle passou para um documento diferente. Isso geralmente acontece quando o atributo de ação de um verbo é definido.

        Por exemplo, se um verbo <Say> for seguido por um <Redirect> e depois outro <Say>, o segundo <Say> ficará inacessível porque <Redirect> transferirá o controle total de uma chamada para o TwiML em um URL diferente.

        Substantivos em TwiML

        Um substantivo em TwiML descreve os números de telefone e os recursos da API sobre os quais você quer agir. Efetivamente, um substantivo TwiML é qualquer coisa aninhada dentro de um verbo que não seja um verbo: é o elemento no qual o verbo age.

        Os substantivos em TwiML geralmente são apenas texto. No entanto, como no caso de <Dial> com seus <Number> e substantivos <Conference>, às vezes há elementos XML aninhados que são substantivos.

        Solicitação da Twilio para seu aplicativo

        Quando alguém faz uma chamada inbound para um dos seus números de telefone da Twilio, a Twilio precisa solicitar o TwiML do seu aplicativo para receber instruções sobre como lidar com a chamada.

        Você pode configurar seu número de telefone da Twilio para apontar para o URL do seu aplicativo visitando a seção de números de telefone do console. Selecione seu número de telefone e, em seguida, role até a seção "Voice & Fax" (Voz e fax) para definir um webhook, repositório do TwiML ou Twilio Function para enviar essa solicitação HTTP quando uma chamada for recebida:

        Configure webhook on phone number for voice

        A Twilio faz sua solicitação por HTTP, seja como um GET ou POST, assim como solicitar uma página da Web em seu navegador ou enviar um formulário.

        A Twilio não pode armazenar POSTs em cache. Se você quiser que a Twilio armazene em cache páginas TwiML estáticas, configure‐as para fazer solicitações ao seu aplicativo usando GET.

        Ao incluir parâmetros e valores em sua solicitação, a Twilio envia dados para seu aplicativo para que você possa tomar uma ação com eles antes de responder.

        Parâmetros da solicitação

        A Twilio sempre envia os seguintes parâmetros quando envia uma solicitação ao seu aplicativo para recuperar instruções sobre como lidar com uma chamada.

        Eles serão enviados como parâmetros POST ou parâmetros de consulta de URL, dependendo de qual método HTTP você configurou.

        Parâmetro Descrição
        CallSid Um identificador exclusivo para esta chamada, gerado pela Twilio.
        AccountSid Seu ID da conta da Twilio. Ele tem 34 caracteres e sempre começa com as letras AC.
        From (De)

        O número de telefone ou identificador de cliente da parte que iniciou a chamada.

        Os números de telefone são formatados com um '+' e o código do país, por exemplo, +16175551212 (formato E.164). Os identificadores de cliente começam com o esquema de URI client:; por exemplo, em uma chamada de um cliente chamado 'charlie' o parâmetro From será client:charlie.

        To (Para)

        O número de telefone ou identificador de cliente da parte chamada.

        Os números de telefone são formatados com um '+' e o código do país, por exemplo, +16175551212 (formato E.164). Os identificadores de cliente começam com o esquema de URI client:; por exemplo, em uma chamada para um cliente chamado 'joey' o parâmetro To será client:joey.

        CallStatus (Status da chamada)

        Um status descritivo para a chamada.

        O valor é um dos seguintes: queued, ringing, in-progress, completed, busy, failed ou no-answer. Consulte a seção CallStatus (Status da chamada) abaixo para obter mais detalhes.

        ApiVersion (Versão da API)

        A versão da API da Twilio usada para lidar com essa chamada.

        Para chamadas recebidas, isso é determinado pela versão da API definida no número chamado. Para chamadas realizadas, esta é a versão usada pela solicitação da API REST da chamada realizadas.

        Direction (Direção)

        Uma string descrevendo a direção da chamada:

        inbound para chamadas inbound

        outbound-api para chamadas iniciadas por meio da API REST

        outbound-dial para chamadas iniciadas por um verbo <Dial>.

        ForwardedFrom (Encaminhada de)

        Este parâmetro é definido apenas quando a Twilio recebe uma chamada encaminhada, mas seu valor depende da operadora do chamador incluindo informações no encaminhamento.

        Nem todas as operadoras oferecem suporte para passar essas informações.

        CallerName (Nome do autor da chamada) Esse parâmetro é definido quando IncomingPhoneNumber que recebeu a chamada tem o valor VoiceCallerIdLookup definido como true (US$ 0,01 por pesquisa).
        ParentCallSid (SID da chamada principal)

        Um identificador exclusivo para a chamada que criou esse trecho.

        Este parâmetro não é passado se esta for a primeira etapa de uma chamada.

        CallToken (Token de chamada)

        Uma string de token necessária para invocar uma chamada encaminhada.

        X-Home-Region (X‐Início‐região)

        Uma string descrevendo a região inicial da Twilio em que o webhook foi processado.

        A Twilio também tenta pesquisar dados geográficos com base nos números de telefone To (Para) e From (De). Se disponível, a Twilio enviará os seguintes parâmetros com a solicitação:

        Parâmetro Descrição
        FromCity A cidade do autor da chamada
        FromState O estado ou província do autor da chamada
        FromZip O código postal do autor da chamada
        FromCountry O país do autor da chamada
        ToCity A cidade da parte chamada
        ToState O estado ou província da parte chamada
        ToZip O código postal da parte chamada
        ToCountry O país da parte chamada

        A Twilio fornecerá os parâmetros listados acima quando fizer uma solicitação ao seu aplicativo para recuperar instruções sobre como lidar com uma chamada. Isso pode ocorrer quando uma chamada inbound chega ao seu número da Twilio, ou depois que um verbo TwiML é concluído e você fornece um URL action onde a Twilio pode recuperar o próximo conjunto de instruções. Dependendo do que está acontecendo em uma chamada, outras variáveis ​​também podem ser enviadas.

        Por exemplo, quando a Twilio receber um SIP, enviará parâmetros adicionais para o aplicativo da Web: você encontrará a lista de parâmetros enviados com SIP em "SIP and TwiML interaction" (interação SIP e TwiML).

        Há alguns casos em que a Twilio enviará uma solicitação que não contém todos os parâmetros acima. Por exemplo, se você forneceu um URL statusCallback em um substantivo TwiML como <VirtualAgent> ou <Pay>, a solicitação da Twilio ao seu aplicativo não conterá todos os parâmetros listados acima, pois nem todos eles são relevantes para o retorno de chamada de status específico. Nesses casos, você pode encontrar os parâmetros esperados na documentação do verbo TwiML específico.

        Valores de CallStatus

        A seguir estão os valores possíveis para o parâmetro CallStatus. Esses valores também se aplicam ao parâmetro DialCallStatus, que é enviado com solicitações HTTP para uma URL de ação <Dial>.

        Status Descrição
        queued (na fila) A chamada está pronta e aguardando na fila antes de sair.
        ringing (tocando) A chamada está tocando no momento.
        in-progress (em andamento) A chamada foi atendida e está em andamento.
        completed (concluída) A chamada foi atendida e terminou normalmente.
        busy (ocupado) O autor da chamada recebeu um sinal de ocupado.
        falha A chamada não pôde ser concluída como discada, provavelmente porque o número de telefone não existia.
        no-answer (sem resposta) A chamada foi encerrada sem ser atendida.
        canceled (cancelada) A chamada foi cancelada por meio da API REST enquanto estava na fila ou tocando.

        Encerramento a chamada: solicitações de retorno de chamada

        Após receber uma chamada, solicitar TwiML de seu aplicativo, processá‐lo e, finalmente, encerrar a chamada, a Twilio fará uma solicitação HTTP assíncrona para o URL StatusCallback configurada para o número da Twilio que foi chamado.

        Você precisa fornecer explicitamente esse URL ao seu aplicativo no parâmetro StatusCallback de cada mensagem para a qual deseja os retornos de chamada de status. O TwiML bruto para essa ação é semelhante a:

        <?xml version="1.0" encoding="UTF-8"?>
        <Response>
            <Dial>
                <Number
                 statusCallbackEvent="initiated ringing answered completed"
                 statusCallback="https://myapp.com/calls/events"
                 statusCallbackMethod="POST">
                    +12316851234
                </Number>
            </Dial>
        </Response>
        

        O exemplo de código abaixo mostra como definir seu URL StatusCallback com um TwiML simples ou usando a biblioteca auxiliar de sua escolha:

              
              
              

              Ao fornecer um URL StatusCallback para seu número da Twilio e capturar essa solicitação, você pode determinar quando uma chamada termina e receber informações sobre a chamada. Observe que URLs não relacionados devem conter um nome de host válido e sublinhados não são permitidos.

              Parâmetros de solicitação StatusCallback

              Quando a Twilio envia parâmetros para seu aplicativo em uma solicitação assíncrona ao URL StatusCallback, eles incluem os mesmos parâmetros passados ​​em uma solicitação TwiML síncrona.

              A solicitação de retorno de chamada de status também passa por esses parâmetros adicionais:

              Parâmetro Descrição
              CallDuration (Duração da chamada) A duração em segundos da chamada recém‐concluída.
              RecordingUrl (URL de gravação) A URL do áudio gravado da chamada telefônica. Este parâmetro é incluído apenas se Record=true estiver definido na solicitação da API REST e não inclui gravações de <Dial> ou <Record>.
              RecordingSid (Sid de gravação) O ID exclusivo da Gravação desta chamada.
              RecordingDuration (Duração da gravação) A duração do áudio gravado (em segundos).

              Formatos de dados

              Números de telefone

              Todos os números de telefone em solicitações da Twilio estão no formato E.164, se possível. Por exemplo, (231) 685-1234 seria exibido como "+12316851234". No entanto, ocasionalmente, há casos em que a Twilio não pode normalizar uma ID de chamada recebida para E.164. Nessas situações, a Twilio reportará a string bruta do ID do autor da chamada.

              Datas e horas

              Todas as datas e horas em solicitações da Twilio são GMT no formato RFC 2822. Por exemplo, 18h13 (UTC‐7) em 19 de agosto de 2010 seria "Sex, 20 ago 2010 01:13:42 +0000"

              A Twilio é um cliente HTTP com bom comportamento

              A Twilio se comporta como um navegador da Web ao fazer solicitações HTTP para URLs:

              • Cookies: a Twilio aceita cookies HTTP e os incluirá em cada solicitação, como um navegador da Web normal.
              • Redirecionamentos: a Twilio segue redirecionamentos HTTP (códigos de status HTTP 301, 307 etc.), assim como um navegador da Web normal. A Twilio suporta no máximo 10 redirecionamentos antes de falhar na solicitação com o código de erro 11215.
              • Armazenamento em cache: a Twilio armazenará em cache os arquivos quando os cabeçalhos HTTP permitirem (via cabeçalhos ETag e Last‐Modified) e quando o método HTTP for GET (OBTER), assim como um navegador da Web normal.

              A Twilio entende tipos MIME

              A Twilio faz a coisa certa quando seu aplicativo responde com diferentes tipos MIME:

              Tipo MIME Comportamento
              text/xml, application/xml, text/html A Twilio interpreta o documento retornado como um conjunto de instruções XML (que gostamos de chamar de TwiML). Esta é a resposta mais comumente usada.
              vários tipos de áudio A Twilio reproduz o arquivo de áudio para o autor da chamada e desliga. Consulte a documentação <Play> dos tipos MIME compatíveis.
              text/plain A Twilio lê o conteúdo do texto em voz alta para o autor da chamada e desliga.

              Responder à Twilio

              Em sua resposta à solicitação da Twilio para o URL configurado, você pode dizer à Twilio o que fazer em uma chamada.

              Como funciona o interpretador do TwiML

              Quando seu aplicativo responde a uma solicitação da Twilio com XML, a Twilio executa seu documento através do interpretador do TwiML. Para simplificar as coisas, o interpretador do TwiML entende apenas os poucos elementos XML especialmente nomeados que compõem o TwiML: <Response>, verbos e substantivos.

              O interpretador começa na parte superior do seu documento TwiML e executa instruções (verbos) de cima para baixo.

              O trecho de código a seguir lê "Hello World" (Olá, mundo) para o autor da chamada antes de tocar Cowbell.mp3 para o autor e depois desligar.

              <?xml version="1.0" encoding="UTF-8"?>
              <Response> 
                  <Say>Hello, World!</Say>
                  <Play>https://api.twilio.com/Cowbell.mp3</Play>
              </Response>
              

              Assim como em todos os TwiML, você pode usar as bibliotecas auxiliares para ajudá‐lo a tocar música para um autor da chamada. Inclua o atributo loop para dizer à Twilio para repetir esta gravação 10 vezes (ou até que o autor da chamada desligue):

                    
                    
                    

                    Retornos de chamada de status na resposta

                    Os retornos de chamada de status não controlam o fluxo de chamadas, portanto, o TwiML não precisa ser retornado. Se você responder, use o código de status 204 No Content (204 Sem conteúdo) ou 200 OK com Content-Type: text/xml e um <Response/> vazio no corpo. Não responder corretamente resultará em avisos no Debugger.

                    O que vem a seguir?

                    Aprofunde‐se para saber mais sobre os vários verbos TwiML que você usará com o Programmable Voice da Twilio, como <Dial> para conectar uma chamada ou <Gather> para reconhecimento de fala e coleta de teclas pressionadas pelo usuário. Você encontrará links para todos os documentos de referência detalhados acima.

                    Você também pode explorar como gerar TwiML com as bibliotecas auxiliares da Twilio, fornecidas para permitir que você gere TwiML em seu idioma favorito.

                    Para um passo a passo guiado, confira nossos inícios rápidos que mostrarão como fazer e receber chamadas telefônicas com Twilio em C#/.NET, Java, Node.js, PHP, Python ou Ruby.

                    Classifique esta página:

                    Precisa de ajuda?

                    Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

                          
                          
                          

                          Obrigado pelo seu feedback!

                          Selecione o(s) motivo(s) para seu feedback. As informações adicionais que você fornece nos ajudam a melhorar nossa documentação:

                          Enviando seu feedback...
                          🎉 Obrigado pelo seu feedback!
                          Algo deu errado. Tente novamente.

                          Obrigado pelo seu feedback!

                          Indique‑nos e obtenha USD10 em 3 etapas simples!

                          Etapa 1

                          Obtenha o link

                          Obtenha um link de indicação pessoal gratuito aqui

                          Etapa 2

                          Dê USD10

                          Seu usuário se inscreve e faz a atualização usando o link

                          Etapa 3

                          Obtenha USD10

                          1.250 mensagens SMS grátis
                          OU 1.000 min de voz grátis
                          OU 12.000 chats
                          OU mais