TwiML™ Voice: <Record>

O verbo <Record> grava a voz do autor da chamada e retorna o URL de um arquivo que contém a gravação de áudio. Opcionalmente, é possível gerar transcrições de texto de chamadas gravadas definindo o atributo transcribe do verbo <Record> como true.

Implicações legais da gravação de chamadas

Se você optar por gravar chamadas de voz ou vídeo, precisará estar em conformidade com determinadas leis e regulamentações, incluindo as relacionados à obtenção de consentimento para gravar (como a Lei de Invasão de Privacidade da Califórnia e leis semelhantes em outras jurisdições). Informações adicionais sobre as implicações legais da gravação de chamadas podem ser encontradas aqui.

Aviso: A Twilio recomenda que você consulte o seu conselho jurídico para se certificar do cumprimento de todas as leis aplicáveis em relação às comunicações que você registra ou armazena usando a Twilio.

Atributos do verbo

O verbo <Record> é compatível com os seguintes atributos que modificam seu comportamento:

Nome do atributo	Valores permitidos	Valor padrão
action	URL relativo ou absoluto	URL do documento atual
method	`GET`, `POST`	`POST`
timeout	Número inteiro positivo	`5`
finishOnKey	Qualquer dígito, `#`, `*`	`1234567890*#`
maxLength	Nú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:

Loading Code Sample...

Example JSON response

Using attributes in a Record verb

action

O atributo action usa um URL relativo ou absoluto como um valor. Quando a gravação é concluída, a Twilio faz uma solicitação GET ou POST para este URL, incluindo os parâmetros abaixo. Se nenhum action for fornecido, o <Record> solicitará o URL do documento atual.

Após fazer esta solicitação, a Twilio continuará a chamada atual usando o TwiML recebido em sua resposta. Lembre‐se de que, por padrão, a Twilio solicitará novamente o URL do documento atual. Isso pode levar a um comportamento de loop indesejado se você não tiver cuidado. Quaisquer verbos TwiML que ocorram após um <Record> não podem ser alcançados.

Por padrão, as gravações silenciosas são salvas pela Twilio. Se você não precisar manter gravaçõ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 ação deve ser fornecido. Falha em fornecer um URL de ação resultará em um erro 11100.

Se você iniciou ou atualizou uma chamada com um parâmetro twiml, os URLs action para <Record>, <Gather> e <Pay> devem ser absolutos.

Os Documentos da API Recursos de chamada têm exemplos específicos de idioma de criação e atualizaçã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 parâ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 atualização de uma chamada com um parâmetro twiml.

Parâmetros da solicitação

Além dos parâmetros da solicitação padrão do TwiML Voice, a Twilio passará os seguintes parâmetros com sua solicitação para o URL de action:

Parâmetro	Descrição
RecordingUrl	O URL do áudio gravado. O arquivo de gravação pode ainda não estar acessível quando o callback do `action` é enviado. Use recordingStatusCallback para obter uma notificação confiável de quando a gravação estiver disponível para acesso.
RecordingDuration	A duração do áudio gravado (em segundos). Para obter uma duração final da gravação precisa após qualquer corte de silêncio, use recordingStatusCallback.
Digits	A tecla (se houver) pressionada para finalizar a gravação ou `hangup` se o autor da chamada desligar.

Por padrão, uma solicitação ao RecordingUrl retornará uma gravação em formato de áudio WAV binário. Para solicitar a gravação no formato MP3, acrescente ".mp3" ao valor do RecordingUrl.

method

O atributo method usa o valor GET ou POST. Isso informa à Twilio se deve solicitar o URL de action via HTTP GET ou POST. Este atributo é modelado no atributo method do formulário HTML. POST é o valor padrão.

timeout

O atributo timeout informa a Twilio para encerrar a gravação após alguns segundos de silêncio. Para desativar este recurso, defina timeout como 0. O padrão é 5 segundos.

finishOnKey

O atributo finishOnKey permite escolher um conjunto de dígitos que, quando inseridos, encerram a gravação. Por exemplo, se você definir finishOnKey para # e o autor da chamada pressionar a tecla #, a Twilio interromperá imediatamente a gravação e enviará RecordingUrl, RecordingDuration e # como parâmetros em uma solicitação ao URL de action. Os valores permitidos são os dígitos de 0 a 9, # e *. O padrão é 1234567890*#, ou seja, qualquer tecla finalizará a gravação. Ao contrário de <Gather>, é possível especificar mais de um caractere como um valor de finishOnKey.

Em alguns casos, ao usar o atributo finishOnKey, a última parte do áudio (aproximadamente um segundo antes de a tecla ser pressionada) pode não ser gravada.

maxLength

O atributo maxLength permite definir o tamanho máximo da gravação em segundos. Se você definir maxLength como 30, a gravação é encerrada automaticamente após 30 segundos de tempo gravado. Os padrões são 3.600 segundos (uma hora) para uma gravação normal e 120 segundos (dois minutos) para uma gravação transcrita. As chamadas do Twilio Client que usam o <Record> são limitadas a 600 segundos (dez minutos).

playBeep

O atributo playBeep permite alternar entre reproduzir um som antes do início de uma gravação. Se você definir o valor para false, nenhum bipe será reproduzido.

trim

O atributo trim permite especificar se você deseja cortar o silêncio inicial e final dos seus arquivos de áudio. O padrão é trim-silence, que remove qualquer silêncio no início e no final da gravação. Isso pode fazer com que a duração da gravação seja ligeiramente inferior à duração da chamada.

recordingStatusCallback

O atributo recordingStatusCallback usa um URL relativo ou absoluto como um argumento. Se for fornecido um URL recordingStatusCallback, a Twilio fará uma solicitação de GET ou POST ao URL especificado quando a gravação estiver disponível para acesso.

Parâmetros da solicitação

A Twilio passará os seguintes parâmetros com sua solicitação para ao URL recordingStatusCallback:

Parâmetro	Descrição
AccountSid	O identificador exclusivo da conta responsável pela gravação.
CallSid	Um identificador exclusivo para a chamada associada à gravação.
RecordingSid	O identificador exclusivo da gravação.
RecordingUrl	O URL do áudio gravado.
RecordingStatus	O status da gravação. Os valores possíveis são: `completed`, `failed`.
RecordingDuration	A duração da gravação, em segundos.
RecordingChannels	O número de canais no arquivo de gravação final como um número inteiro. Apenas um canal é compatível com o verbo `<Record>`.
RecordingSource	O método de início usado para criar a gravação. O `RecordVerb` é retornado para gravações iniciadas por meio do verbo `<Record>`.

recordingStatusCallbackMethod

Este atributo indica qual método HTTP usar ao solicitar o recordingStatusCallback. O padrão é POST.

recordingStatusCallbackEvent

O recordingStatusCallbackEvent permite especificar quais alterações do status da gravação devem gerar um webhook para o URL especificado no atributo recordingStatusCallback. Os valores disponíveis são:

in-progress: a gravação foi iniciada.
completed: a gravação foi concluída e está disponível.
absent: a gravação está ausente e inacessível.

Para especificar mais de um valor, separe cada um com um espaço. O valor padrão é completed.

transcribe

O atributo transcribe informa a Twilio que você gostaria de uma representação de texto do áudio da gravação. A Twilio passará esta gravação pelo mecanismo de conversão de fala em texto e tentará converter o áudio em texto legível. A opção transcribe não está ativa por padrão. Se você não quiser realizar a transcrição, não inclua o atributo transcribe.

Observações

A transcrição é um recurso pago. Se você incluir um atributo transcribe ou transcribeCallback no verbo Record, sua conta será cobrada. Consulte a página de preços para saber os preços da transcrição.
A transcrição tem suporte apenas no idioma inglês americano.

Além disso, a transcrição está atualmente limitada a gravações iniciadas por meio do verbo <Record> do TwiML com duração superior a dois segundos e inferior a 120 segundos. Se você solicitar uma transcrição para uma gravação fora desses limites de duração, a Twilio escreverá um aviso no log de depuração em vez de transcrever a gravação.

transcribeCallback

O atributo transcribeCallback é usado em conjunto com o atributo transcribe. Ele permite especificar um URL para o qual a Twilio fará uma solicitação de POST assíncrona quando a transcrição estiver concluída. Esta não é uma solicitação para o TwiML e a resposta não mudará o fluxo de chamada, mas a solicitação conterá os parâmetros padrão de solicitação do TwiML, bem como os específicos da transcrição.

Se transcribeCallback for especificado, não há necessidade de especificar transcribe=true, pois já está implícito. Se você especificar transcribe=true sem um transcribeCallback, a transcrição completa será armazenada para que possa ser recuperada mais tarde (consulte a seção [Transcriptions] (/docs/Voice/api/recording-transcription) da API REST), mas a Twilio não notificará seu aplicativo de forma assíncrona.

A Twilio não fará uma solicitação para o URL transcribeCallback fornecido se a gravação de voz for inexistente ou ausente.

O atributodo URL transcribeCallback é considerado não IPI.

Parâmetros da solicitação

A Twilio passará os seguintes parâmetros com sua solicitação para o URL transcribeCallback:

Parâmetro	Descrição
TranscriptionSid	O ID exclusivo de 34 caracteres da transcrição.
TranscriptionText	O texto da transcrição.
TranscriptionStatus	O status da tentativa de transcrição: `completed` ou `failed`.
TranscriptionUrl	O URL para o recurso de API REST da transcrição.
RecordingSid	O ID exclusivo de 34 caracteres da gravação a partir da qual a transcrição foi gerada.
RecordingUrl	O URL do recurso de gravação de origem da transcrição.
CallSid	Um identificador exclusivo para a chamada, gerado pela Twilio.
AccountSid	O ID da conta da Twilio. Tem 34 caracteres e sempre começa com as letras `AC`.
From	O número de telefone ou o identificador do cliente da pessoa que iniciou a chamada. Os números de telefone são formatados com um `+` e o código de país, por exemplo: `+16175551212` (formato [E.164][e164]). Os identificadores de cliente começam com o esquema URI `client:`. Por exemplo: para uma chamada de um cliente chamado `tommy`, o parâmetro `From` será `client:tommy`.
Para	o número de telefone ou o identificador do cliente da pessoa chamada. Os números de telefone são formatados com um `+` e o código de país, por exemplo: `+16175551212` (formato [E.164][e164]). Os identificadores de cliente começam com o esquema URI `client:`. Por exemplo: para uma chamada a um cliente chamado `joey`, o parâmetro `To` será `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 seção CallStatus.
ApiVersion	A versão da API da Twilio usada para lidar com esta chamada. Para chamadas recebidas, isso é determinado pela versão da API definida no número chamado. Para chamadas realizadas, esta é a versão da API usada pela solicitação da API REST da chamada realizada.
Direction	Uma string que descreve a direçã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 parâmetro é definido apenas quando a Twilio recebe uma chamada encaminhada, mas seu valor depende da operadora do autor da chamada incluir informações ao encaminhar. Nem todas as operadoras oferecem suporte para passar essas informações.

Regras de aninhamento

Não é possível aninhar verbos dentro de <Record> e nem aninhar <Record> em nenhum outro verbo.

Veja também

Exemplos

Exemplo 1: Gravação simples

A Twilio executará o verbo <Record>, fazendo com que o autor da chamada ouça um bipe e a gravação inicie. Se o autor da chamada ficar em silêncio por mais de cinco segundos, pressionar a tecla # ou o tempo maxLenght de gravação for atingido, a Twilio fará uma solicitação HTTP POST para o URL action padrão (ou seja, o URL do documento atual) com os parâmetros RecordingUrl e RecordingDuration.

Loading Code Sample...

Example JSON response

Simple Record

Exemplo 2: Gravação de um correio de voz

Este exemplo mostra um prompt de correio de voz simples. O autor da chamada é solicitado a deixar uma mensagem após o bipe. O verbo <Record> emite um bipe e começa a gravar até 20 segundos de áudio.

Loading Code Sample...

Example JSON response

Record a voicemail

Se o autor da chamada falar por menos de 20 segundos e ficar em silêncio durante 5 segundos, a Twilio faz uma solicitação GET ao URL action. O verbo <Say> nunca é alcançado. * Se o autor da chamada falar durante os 20 segundos completos, a Twilio faz uma solicitação GET ao URL action. O verbo <Say> nunca é alcançado.

Exemplo 3: Transcrição de uma gravação

A Twilio gravará o autor da chamada. Quando a gravação estiver concluída, a Twilio transcreverá a gravação e fará uma solicitação HTTP POST para o URL transcribeCallback com um parâmetro que contém uma transcrição da gravação.

Loading Code Sample...

Example JSON response

Transcribe a recording

Dicas e usos avançados

A Twilio corta o silêncio inicial e final de seus arquivos de áudio. Isso pode fazer com que a duraçã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.

Using attributes in a Record verb

Simple Record

Record a voicemail

Transcribe a recording

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!