Gravação
Para clientes que estão criando fluxos de trabalho compatíveis com HIPAA com Gravações, exigimos que os clientes apliquem pelo menos a autenticação HTTP. Para saber mais sobre como criar conformidade com a HIPAA, visite os requisitos mais recentes aqui.
Um recurso de gravação representa a gravação associada a uma chamada de voz, conferência ou SIP Trunk. Usando a API REST de gravações, você pode buscar, iniciar, parar, pausar, retomar e excluir gravações de voz.
Você pode iniciar uma gravação para sua chamada, conferência ou tronco por meio de um dos métodos a seguir.
- <Record> em TwiML
- <Dial record> em TwiML
- <Conference record> em TwiML
- Record=true em uma chamada de saída por meio da API REST
- Ative a gravação em um SIP Trunk elástico no Console da Twilio
- POST para recurso de gravação de um SID de chamada em andamento
Quando uma gravação é iniciada, você pode pausar, retomar ou parar a gravação
Propriedades de gravação
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account that created the Recording resource. |
api_version
|
The API version used during the recording. |
call_sid
|
The SID of the Call the Recording resource is associated with. This will always refer to the parent leg of a two-leg call. |
conference_sid
|
The Conference SID that identifies the conference associated with the recording, if a conference recording. |
date_created
|
A data e a hora em GMT em que o recurso foi criado especificadas no formato RFC 2822. |
date_updated
|
A data e a hora em GMT em que o recurso foi atualizado pela última vez especificadas no formato RFC 2822. |
start_time
|
The start time of the recording in GMT and in RFC 2822 format. |
duration
|
The length of the recording in seconds. |
sid
|
The unique string that that we created to identify the Recording resource. |
price
|
The one-time cost of creating the recording in the |
price_unit
|
The currency used in the |
status
|
The status of the recording. Can be: |
channels
|
The number of channels in the final recording file. Can be: |
source
|
How the recording was created. Can be: |
error_code
|
The error code that describes why the recording is |
uri
|
O URI do recurso, relativo a “https://api.twilio.com”. |
encryption_details
|
How to decrypt the recording if it was encrypted using Call Recording Encryption feature. |
subresource_uris
|
A list of related resources identified by their relative URIs. |
media_url
|
The URL of the media file associated with this recording resource. When stored externally, this is the full URL location of the media file. |
Criar um recurso de gravação
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallsSid}/Recordings.json
Para iniciar uma gravação em uma chamada ao vivo, faça uma solicitação HTTP POST para o recurso da lista de gravações de uma chamada em andamento.
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.
Parâmetros opcionais
Os seguintes parâmetros opcionais estão disponíveis para POST ao iniciar uma gravação em uma chamada ao vivo:
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
O SID da Account (Conta) para create (criar) o recurso. |
call_sid
Path
|
The SID of the Call to associate the resource with. |
recording_status_callback_event
Optional
|
The recording status events on which we should call the |
recording_status_callback
Optional
|
The URL we should call using the |
recording_status_callback_method
Optional
|
The HTTP method we should use to call |
trim
Optional
|
Whether to trim any leading and trailing silence in the recording. Can be: |
recording_channels
Optional
|
The number of channels used in the recording. Can be: |
recording_track
Optional
|
The audio track to record for the call. Can be: |
RecordingStatusCallback
A Twilio passará os seguintes parâmetros com sua solicitação para seu URL de RecordingStatusCallback:
| Parâmetro | Descrição |
|---|---|
| AccountSid | O identificador exclusivo da conta responsável por esta 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: "em andamento", "concluído", "ausente". |
| RecordingDuration | A duração da gravação, em segundos. (fornecido apenas quando RecordingStatus é "concluído") |
| RecordingChannels | O número de canais no arquivo de gravação final como um número inteiro. Os valores possíveis são "1" e "2". |
| RecordingStartTime | O carimbo de data/hora de quando a gravação foi iniciada. |
| RecordingSource | O método de início usado para criar esta gravação. Para gravações iniciadas com esta API, o valor será "StartCallRecordingAPI". |
| RecordingTrack | A faixa de áudio gravada. Os valores possíveis são "entrada", "saída" ou "ambos". |
Buscar um recurso de gravação
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.json
Como os URLs que hospedam gravações individuais são úteis para muitos aplicativos externos, eles são públicos e não exigem autenticação básica HTTP para acesso. Isso permite incorporar o URL de gravação em um aplicativo da Web sem revelar suas credenciais de API da Twilio.
Os URLs de gravação da Twilio são muito longos e difíceis de adivinhar; portanto, o conteúdo das gravações deve ser razoavelmente privado, a menos que você distribua o URL. Para maior segurança, você pode aplicar a autenticação básica HTTP para acessar a mídia usando seu token AccountSid e Authentication por meio da página de configurações de voz no console.
Parâmetros
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the Recording resource to fetch. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Recording resource to fetch. |
include_soft_deleted
Optional
|
A boolean parameter indicating whether to retrieve soft deleted recordings or not. Recordings metadata are kept after deletion for a retention period of 40 days. |
Buscar metadados de gravação
Os metadados do recurso de gravações podem ser retornados em json ou xml ao incluir o sufixo ".json" ou "xml" ao URI.
Buscar um arquivo de mídia de gravação
Só é possível buscar um arquivo de mídia de gravação quando a gravação tem o status "Concluído" e a mídia é armazenada na Twilio. Se a mídia associada ao recurso de gravação não estiver disponível, for excluída ou tiver sido carregada em armazenamento externo, a solicitação retornará "Não encontrado".
WAV
Sem uma extensão, ou com ".wav", um arquivo de áudio WAV binário é retornado com o tipo mime "audio/x-wav". Por exemplo:
GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485
Os arquivos WAV têm uma taxa de bits de 128 kbps
MP3
Anexar ".mp3" ao URI retorna um arquivo de áudio MP3 binário com o tipo mime "audio/mpeg". Por exemplo:
GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.mp3
Os arquivos MP3 têm uma taxa de bits de 32 kbps
Faça download do arquivo de mídia de canal duplo
Por padrão, as gravações de chamadas são armazenadas na Twilio em canal duplo. O arquivo de mídia associado ao recurso de gravação de uma chamada de dois participantes tem dois canais e contém o áudio de cada segmento de chamada em um canal separado. O parâmetro de consulta requestedChannels pode ser usado para especificar se o arquivo deve passar por downmix para um único canal ou se o arquivo deve ser baixado em seu formato original de canal duplo.
Para compatibilidade com versões anteriores, se o parâmetro de consulta requestedChannels não for especificado, o formato do arquivo baixado será o formato que foi especificado quando a gravação foi criada.
Para gravações de voz em que o canal duplo não é suportado, como as que são criadas com <Conference> ou <Record>, todo o áudio de uma gravação será salvo em um arquivo de canal único. Se uma gravação de canal duplo for explicitamente solicitada para download nesses casos, a resposta será Not Found.
Exemplo: Faça o download da mídia MP3 no formato de canal duplo
Inclua .mp3?requestedChannels=2 ao URL da gravação
GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.mp3?requestedChannels=2Exemplo: Faça download da mídia WAV no formato de canal duplo
Inclua .wav?requestedChannels=2 ao URL da gravação
GET https://api.twilio.com/2010-04-01/Accounts/ACXXXXX.../Recordings/RE557ce644e5ab84fa21cc21112e22c485.wav?requestedChannels=2Buscar as transcrições de uma gravação
Cada recurso de instância de gravação tem um sub‐recurso de transcrições que representa o conjunto de transcrições geradas com base na gravação (se houver):
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{RecordingSid}/Transcriptions
Isso retornará o conjunto de transcrições disponíveis para a gravação identificada por {RecordingSid}. Consulte a Documentação do recurso de transcrições para obter as propriedades e os formatos de resposta.
Ler vários recursos de gravação
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings.json
Esta chamada de API retorna uma lista de Gravações, cada uma representando uma gravação gerada durante uma chamada ou conferência para a conta em questão. A lista retornada inclui informações de paginação.
A lista de Gravações é protegida pelas credenciais da sua conta, como a maioria das partes desta API. Você deve usar a autenticação básica HTTP para acessar o recurso de lista de Gravações.
Você também pode obter uma lista de gravações de uma chamada ou conferência específica incluindo o SID da chamada ou da conferência em sua solicitação da seguinte forma:
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings.json
Parâmetros
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the Recording resources to read. |
date_created
Optional
|
Only include recordings that were created on this date. Specify a date as |
call_sid
Optional
|
The Call SID of the resources to read. |
conference_sid
Optional
|
The Conference SID that identifies the conference associated with the recording to read. |
include_soft_deleted
Optional
|
A boolean parameter indicating whether to retrieve soft deleted recordings or not. Recordings metadata are kept after deletion for a retention period of 40 days. |
Exemplos
Atualizar um recurso de gravação
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Recordings/{Sid}.json
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings/{Sid}.json
Uma gravação de chamada ativa ou de conferência pode ser pausada e retomada. Além disso, uma gravação de chamada ativa pode ser interrompida, o que encerrará a gravação imediatamente. (parada não suportada para gravações de conferência)
Parâmetros
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the Recording resource to update. |
call_sid
Path
|
The Call SID of the resource to update. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Recording resource to update. |
status
Required
|
The new status of the recording. Can be: |
pause_behavior
Optional
|
Whether to record during a pause. Can be: |
Exemplos:
Observe, nos exemplos abaixo, que as respostas da API para atualizações do recurso de gravação fornecerão um "status" adicional mais detalhado, incluindo pausado, em andamento ou interrompido, mas uma busca no recurso de gravação mostrará apenas em processamento ou concluído.
Nos dois exemplos a seguir, observe o uso de Twilio.CURRENT para fazer referência à gravação ativa no momento sem exigir um SID de gravação explícito.
Twilio.CURRENT pode ser usado para pausar, retomar ou interromper ações em chamadas com apenas uma gravação ativa.
Observe que, se o caso de uso tiver várias gravações ou gravações simultâneas para uma chamada ou conferência, será necessário usar o SID de gravação para fazer referência ao correto. O uso de Twilio.CURRENT para fazer referência a uma gravação em um recurso que tem várias gravações resultará em um erro de falha na solicitação porque há mais de uma gravação para a chamada em questão.
Excluir um recurso de gravação
DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Recordings/{Sid}.json
Exclui uma gravação da sua conta. Depois que a gravação for excluída:
- Você não será mais cobrado pelo armazenamento desses minutos
- A gravação é definida com um status de
deleted - Os metadados são preservados por um período de 40 dias, durante o qual os metadados ainda ficam visíveis no Console e na API.
- A mídia de gravação não pode ser recuperada.
Se bem‐sucedido, DELETE retorna HTTP 204 (sem conteúdo) sem corpo.
Observe que somente as gravações completed podem ser excluídas. Gravações com qualquer outro status não estão disponíveis para exclusão.
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the Recording resources to delete. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Recording resource to delete. |
Para excluir um grande conjunto de gravações de voz, você pode usar os recursos de exclusão em massa disponíveis no Console da Twilio.
Exemplo:
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.
