TwiML™ Voice: <Record>
O verbo <Record>
grava a voz do autor da chamada e retorna o URL de um arquivo que contém a gravação de áudio. Opcionalmente, é possível gerar transcrições de texto de chamadas gravadas definindo o atributo transcribe
do verbo <Record>
como true
.
Implicações legais da gravação de chamadas
Se você optar por gravar chamadas de voz ou vídeo, precisará estar em conformidade com determinadas leis e regulamentações, incluindo as relacionados à obtenção de consentimento para gravar (como a Lei de Invasão de Privacidade da Califórnia e leis semelhantes em outras jurisdições). Informações adicionais sobre as implicações legais da gravação de chamadas podem ser encontradas aqui.
Aviso: A Twilio recomenda que você consulte o seu conselho jurídico para se certificar do cumprimento de todas as leis aplicáveis em relação às comunicações que você registra ou armazena usando a Twilio.
Atributos do verbo
O verbo <Record>
é compatível com os seguintes atributos que modificam seu comportamento:
Nome do atributo | Valores permitidos | Valor padrão |
---|---|---|
action | URL relativo ou absoluto | URL do documento atual |
method | GET , POST |
POST |
timeout | Número inteiro positivo | 5 |
finishOnKey | Qualquer dígito, # , * |
1234567890*# |
maxLength | Número inteiro maior que 1 | 3600 (1 hora) |
playBeep | true , false |
true |
trim | trim-silence , do-not-trim |
trim-silence |
recordingStatusCallback | URL relativo ou absoluto | Nenhum |
recordingStatusCallbackMethod | GET , POST |
POST |
recordingStatusCallbackEvent | in-progress , completed , absent |
completed |
transcribe | true , false |
false |
transcribeCallback | URL relativo ou absoluto | Nenhum |
Use um ou mais desses atributos em um verbo <Record>
desta maneira:
action
O atributo action
usa um URL relativo ou absoluto como um valor. Quando a gravação é concluída, a Twilio faz uma solicitação GET ou POST para este URL, incluindo os parâmetros abaixo. Se nenhum action
for fornecido, o <Record>
solicitará o URL do documento atual.
Após fazer esta solicitação, a Twilio continuará a chamada atual usando o TwiML recebido em sua resposta. Lembre‐se de que, por padrão, a Twilio solicitará novamente o URL do documento atual. Isso pode levar a um comportamento de loop indesejado se você não tiver cuidado. Quaisquer verbos TwiML que ocorram após um <Record>
não podem ser alcançados.
Por padrão, as gravações silenciosas são salvas pela Twilio. Se você não precisar manter gravações silenciosas, entre em contato com o Suporte da Twilio.
Ao modificar uma chamada ao vivo para redirecionar para um verbo <Record>, um URL de ação deve ser fornecido. Falha em fornecer um URL de ação resultará em um erro 11100.
Se você iniciou ou atualizou uma chamada com um parâmetro twiml
, os URLs action
para <Record>
, <Gather>
e <Pay>
devem ser absolutos.
Os Documentos da API Recursos de chamada têm exemplos específicos de idioma de criação e atualização de chamadas com o TwiML:
- Consulte "Create a Call resource with TwiML" (Criar um recurso de chamada com o TwiML) em Create a Call Resource (Criar um recurso de chamada) para ver exemplos de como criar uma chamada com um parâmetro
twiml
. - Consulte "Update a Call resource with TwiML" (Atualizar um recurso de chamada com o TwiML) em Update a Call Resource (Atualizar um recurso de chamada)para ver exemplos de atualização de uma chamada com um parâmetro
twiml
.
Parâmetros da solicitação
Além dos parâmetros da solicitação padrão do TwiML Voice, a Twilio passará os seguintes parâmetros com
sua solicitação para o URL de action
:
Parâmetro | Descrição |
---|---|
RecordingUrl | O URL do áudio gravado. O arquivo de gravação pode ainda não estar acessível quando o callback do action é enviado. Use recordingStatusCallback para obter uma notificação confiável de quando a gravação estiver disponível para acesso. |
RecordingDuration | A duração do áudio gravado (em segundos). Para obter uma duração final da gravação precisa após qualquer corte de silêncio, use recordingStatusCallback. |
Digits | A tecla (se houver) pressionada para finalizar a gravação ou hangup se o autor da chamada desligar. |
Por padrão, uma solicitação ao RecordingUrl
retornará uma gravação em formato de áudio WAV binário. Para solicitar a gravação no formato MP3, acrescente ".mp3" ao valor do RecordingUrl
.
method
O atributo method
usa o valor GET
ou POST
. Isso informa à Twilio se deve solicitar o URL de action
via HTTP GET ou POST. Este atributo é modelado no atributo method
do formulário HTML. POST
é o valor padrão.
timeout
O atributo timeout
informa a Twilio para encerrar a gravação após alguns segundos de silêncio. Para desativar este recurso, defina timeout
como 0. O padrão é 5 segundos.
finishOnKey
O atributo finishOnKey
permite escolher um conjunto de dígitos que, quando inseridos, encerram a gravação. Por exemplo, se você definir finishOnKey
para #
e o autor da chamada pressionar a tecla #
, a Twilio interromperá imediatamente a gravação e enviará RecordingUrl
, RecordingDuration
e #
como parâmetros em uma solicitação ao URL de action
. Os valores permitidos são os dígitos de 0 a 9, # e *. O padrão é 1234567890*#
, ou seja, qualquer tecla finalizará a gravação. Ao contrário de <Gather>
, é possível especificar mais de um caractere como um valor de finishOnKey
.
Em alguns casos, ao usar o atributo finishOnKey
, a última parte do áudio (aproximadamente um segundo antes de a tecla ser pressionada) pode não ser gravada.
maxLength
O atributo maxLength
permite definir o tamanho máximo da gravação em segundos. Se você definir maxLength
como 30, a gravação é encerrada automaticamente após 30 segundos de tempo gravado. Os padrões são 3.600 segundos (uma hora) para uma gravação normal e 120 segundos (dois minutos) para uma gravação transcrita. As chamadas do Twilio Client que usam o <Record>
são limitadas a 600 segundos (dez minutos).
playBeep
O atributo playBeep
permite alternar entre reproduzir um som antes do início de uma gravação. Se você definir o valor para false
, nenhum bipe será reproduzido.
trim
O atributo trim
permite especificar se você deseja cortar o silêncio inicial e final dos seus arquivos de áudio. O padrão é trim-silence
, que remove qualquer silêncio no início e no final da gravação. Isso pode fazer com que a duração da gravação seja ligeiramente inferior à duração da chamada.
recordingStatusCallback
O atributo recordingStatusCallback
usa um URL relativo ou absoluto como um argumento. Se for fornecido um URL recordingStatusCallback
, a Twilio fará uma solicitação de GET ou POST ao URL especificado quando a gravação estiver disponível para acesso.
Parâmetros da solicitação
A Twilio passará os seguintes parâmetros com sua solicitação para ao URL recordingStatusCallback
:
Parâmetro | Descrição |
---|---|
AccountSid | O identificador exclusivo da conta responsável pela gravação. |
CallSid | Um identificador exclusivo para a chamada associada à gravação. |
RecordingSid | O identificador exclusivo da gravação. |
RecordingUrl | O URL do áudio gravado. |
RecordingStatus | O status da gravação. Os valores possíveis são: completed , failed . |
RecordingDuration | A duração da gravação, em segundos. |
RecordingChannels | O número de canais no arquivo de gravação final como um número inteiro. Apenas um canal é compatível com o verbo <Record> . |
RecordingSource | O método de início usado para criar a gravação. O RecordVerb é retornado para gravações iniciadas por meio do verbo <Record> . |
recordingStatusCallbackMethod
Este atributo indica qual método HTTP usar ao solicitar o recordingStatusCallback
. O padrão é POST.
recordingStatusCallbackEvent
O recordingStatusCallbackEvent
permite especificar quais alterações do status da gravação devem gerar um webhook para o URL especificado no atributo recordingStatusCallback
. Os valores disponíveis são:
in-progress
: a gravação foi iniciada.completed
: a gravação foi concluída e está disponível.absent
: a gravação está ausente e inacessível.
Para especificar mais de um valor, separe cada um com um espaço. O valor padrão é completed
.
transcribe
O atributo transcribe
informa a Twilio que você gostaria de uma representação de texto do áudio da gravação. A Twilio passará esta gravação pelo mecanismo de conversão de fala em texto e tentará converter o áudio em texto legível. A opção transcribe
não está ativa por padrão. Se você não quiser realizar a transcrição, não inclua o atributo transcribe
.
Observações
- A transcrição é um recurso pago. Se você incluir um atributo
transcribe
outranscribeCallback
no verboRecord
, sua conta será cobrada. Consulte a página de preços para saber os preços da transcrição. - A transcrição tem suporte apenas no idioma inglês americano.
Além disso, a transcrição está atualmente limitada a gravações iniciadas por meio do verbo <Record>
do TwiML com duração superior a dois segundos e inferior a 120 segundos. Se você solicitar uma transcrição para uma gravação fora desses limites de duração, a Twilio escreverá um aviso no log de depuração em vez de transcrever a gravação.
transcribeCallback
O atributo transcribeCallback
é usado em conjunto com o atributo transcribe
. Ele permite especificar um URL para o qual a Twilio fará uma solicitação de POST assíncrona quando a transcrição estiver concluída. Esta não é uma solicitação para o TwiML e a resposta não mudará o fluxo de chamada, mas a solicitação conterá os parâmetros padrão de solicitação do TwiML, bem como os específicos da transcrição.
Se transcribeCallback
for especificado, não há necessidade de especificar transcribe=true
, pois já está implícito. Se você especificar transcribe=true
sem um transcribeCallback
, a transcrição completa será armazenada para que possa ser recuperada mais tarde (consulte a seção [Transcriptions] (/docs/Voice/api/recording-transcription) da API REST), mas a Twilio não notificará seu aplicativo de forma assíncrona.
A Twilio não fará uma solicitação para o URL transcribeCallback
fornecido se a gravação de voz for inexistente ou ausente.
O atributodo URL transcribeCallback
é considerado não IPI.
Parâmetros da solicitação
A Twilio passará os seguintes parâmetros com sua solicitação para o URL transcribeCallback
:
Parâmetro | Descrição |
---|---|
TranscriptionSid | O ID exclusivo de 34 caracteres da transcrição. |
TranscriptionText | O texto da transcrição. |
TranscriptionStatus | O status da tentativa de transcrição: completed ou failed . |
TranscriptionUrl | O URL para o recurso de API REST da transcrição. |
RecordingSid | O ID exclusivo de 34 caracteres da gravação a partir da qual a transcrição foi gerada. |
RecordingUrl | O URL do recurso de gravação de origem da transcrição. |
CallSid | Um identificador exclusivo para a chamada, gerado pela Twilio. |
AccountSid | O ID da conta da Twilio. Tem 34 caracteres e sempre começa com as letras AC . |
From | O número de telefone ou o identificador do cliente da pessoa que iniciou a chamada. Os números de telefone são formatados com um + e o código de país, por exemplo: +16175551212 (formato [E.164][e164]). Os identificadores de cliente começam com o esquema URI client: . Por exemplo: para uma chamada de um cliente chamado tommy , o parâmetro From será client:tommy . |
Para | o número de telefone ou o identificador do cliente da pessoa chamada. Os números de telefone são formatados com um + e o código de país, por exemplo: +16175551212 (formato [E.164][e164]). Os identificadores de cliente começam com o esquema URI client: . Por exemplo: para uma chamada a um cliente chamado joey , o parâmetro To será client:joey . |
CallStatus | Um status descritivo da chamada. O valor pode ser um desses: queued , ringing , in-progress , completed , busy , failed ou no-answer . Para obter mais detalhes, consulte a seção CallStatus. |
ApiVersion | A versão da API da Twilio usada para lidar com esta chamada. Para chamadas recebidas, isso é determinado pela versão da API definida no número chamado. Para chamadas realizadas, esta é a versão da API usada pela solicitação da API REST da chamada realizada. |
Direction | Uma string que descreve a direção da chamada: Inbound para chamada inbound, outbound-api para chamadas iniciadas pela API REST, ou outbound-dial para chamadas iniciadas por um verbo <Dial> . |
ForwardedFrom | Este parâmetro é definido apenas quando a Twilio recebe uma chamada encaminhada, mas seu valor depende da operadora do autor da chamada incluir informações ao encaminhar. Nem todas as operadoras oferecem suporte para passar essas informações. |
Regras de aninhamento
Não é possível aninhar verbos dentro de <Record>
e nem aninhar <Record>
em nenhum outro verbo.
Veja também
Exemplos
Exemplo 1: Gravação simples
A Twilio executará o verbo <Record>
, fazendo com que o autor da chamada ouça um bipe e a gravação inicie. Se o autor da chamada ficar em silêncio por mais de cinco segundos, pressionar a tecla # ou o tempo maxLenght
de gravação for atingido, a Twilio fará uma solicitação HTTP POST para o URL action
padrão (ou seja, o URL do documento atual) com os parâmetros RecordingUrl
e RecordingDuration
.
Exemplo 2: Gravação de um correio de voz
Este exemplo mostra um prompt de correio de voz simples. O autor da chamada é solicitado a deixar uma mensagem após o bipe. O verbo <Record>
emite um bipe e começa a gravar até 20 segundos de áudio.
Se o autor da chamada falar por menos de 20 segundos e ficar em silêncio durante 5 segundos, a Twilio faz uma solicitação GET ao URL action
. O verbo <Say>
nunca é alcançado.
* Se o autor da chamada falar durante os 20 segundos completos, a Twilio faz uma solicitação GET ao URL action
. O verbo <Say>
nunca é alcançado.
Exemplo 3: Transcrição de uma gravação
A Twilio gravará o autor da chamada. Quando a gravação estiver concluída, a Twilio transcreverá a gravação e fará uma solicitação HTTP POST para o URL transcribeCallback
com um parâmetro que contém uma transcrição da gravação.
Dicas e usos avançados
- A Twilio corta o silêncio inicial e final de seus arquivos de áudio. Isso pode fazer com que a duração dos arquivos seja ligeiramente inferior ao tempo que um autor da chamada gasta gravando‐os.
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.