Recurso de Chamada
Uma Chamada é um objeto que representa uma conexão entre um telefone e a Twilio.
Usando esse recurso, você pode iniciar uma chamada, buscar informações sobre uma chamada concluída, buscar uma lista de chamadas feitas de e para sua conta, redirecionar ou encerrar uma chamada em andamento e excluir registros de chamadas passadas de sua conta.
Uma chamada inbound ocorre quando uma pessoa liga para um dos números de telefone da Twilio, conexões de cliente ou endpoints habilitados para SIP. Uma chamada outbound ocorre quando você inicia uma chamada de um número de telefone da Twilio para um número de telefone externo, cliente ou domínio SIP.
Você pode iniciar uma chamada outbound POSTando no Recurso de Chamada, criando uma nova chamada.
Você também pode iniciar uma chamada a partir de uma chamada ativa (por exemplo, encaminhando para outro número ou discando para uma conferência) incluindo o verbo <Dial> do TwiML em seu aplicativo TwiML. No entanto, a única maneira de iniciar uma chamada diretamente da Twilio é com uma solicitação de API.
Propriedades da chamada
Resource Properties in REST API format | |
---|---|
sid
|
The unique string that we created to identify this Call resource. |
date_created
|
The date and time in GMT that this resource was created specified in RFC 2822 format. |
date_updated
|
The date and time in GMT that this resource was last updated, specified in RFC 2822 format. |
parent_call_sid
|
The SID that identifies the call that created this leg. |
account_sid
|
The SID of the Account that created this Call resource. |
to
|
The phone number, SIP address, Client identifier or SIM SID that received this call. Phone numbers are in E.164 format (e.g., +16175551212). SIP addresses are formatted as |
to_formatted
|
The phone number, SIP address or Client identifier that received this call. Formatted for display. Non-North American phone numbers are in E.164 format (e.g., +442071838750). |
from
|
The phone number, SIP address, Client identifier or SIM SID that made this call. Phone numbers are in E.164 format (e.g., +16175551212). SIP addresses are formatted as |
from_formatted
|
The calling phone number, SIP address, or Client identifier formatted for display. Non-North American phone numbers are in E.164 format (e.g., +442071838750). |
phone_number_sid
|
If the call was inbound, this is the SID of the IncomingPhoneNumber resource that received the call. If the call was outbound, it is the SID of the OutgoingCallerId resource from which the call was placed. |
status
|
The status of this call. Can be: |
start_time
|
The start time of the call, given as GMT in RFC 2822 format. Empty if the call has not yet been dialed. |
end_time
|
The time the call ended, given as GMT in RFC 2822 format. Empty if the call did not complete successfully. |
duration
|
The length of the call in seconds. This value is empty for busy, failed, unanswered, or ongoing calls. |
price
|
The charge for this call, in the currency associated with the account. Populated after the call is completed. May not be immediately available. |
price_unit
|
The currency in which |
direction
|
A string describing the direction of the call. Can be: |
answered_by
|
Either |
api_version
|
The API version used to create the call. |
forwarded_from
|
The forwarding phone number if this call was an incoming call forwarded from another number (depends on carrier supporting forwarding). Otherwise, empty. |
group_sid
|
The Group SID associated with this call. If no Group is associated with the call, the field is empty. |
caller_name
|
The caller's name if this call was an incoming call to a phone number with caller ID Lookup enabled. Otherwise, empty. |
queue_time
|
The wait time in milliseconds before the call is placed. |
trunk_sid
|
The unique identifier of the trunk resource that was used for this call. The field is empty if the call was not made using a SIP trunk or if the call is not terminated. |
uri
|
The URI of this resource, relative to |
subresource_uris
|
A list of subresources available to this call, identified by their URIs relative to |
Valores de status da chamada
A seguir estão os valores possíveis para o parâmetro Status
:
Status | Descrição |
---|---|
queued (em fila) |
A chamada está pronta e aguardando na linha antes de discar. |
ringing (tocando) |
A chamada está tocando no momento. |
in-progress (em andamento) |
A chamada foi atendida e está em andamento no momento. |
canceled (cancelado) |
A chamada foi desligada enquanto estava na fila ou tocando. |
completed (concluído) |
A chamada foi atendida e terminou normalmente. |
busy (ocupado) |
O autor da chamada recebeu um sinal de ocupado. |
no-answer (sem resposta) |
Não houve resposta ou a chamada foi rejeitada. |
falha |
A chamada não pôde ser concluída como discada, provavelmente porque o número de telefone não era existente. |
Criar um Recurso de Chamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls.json
As chamadas podem ser feitas por meio da API REST para números de telefone, endereços SIP ou identificadores de cliente. Para fazer uma nova chamada outbound, faça uma solicitação HTTP POST para o recurso de chamada da sua conta.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
O SID da Account (Conta) para create (criar) o recurso. |
to
Required
|
The phone number, SIP address, or client identifier to call. |
from
Required
|
The phone number or client identifier to use as the caller id. If using a phone number, it must be a Twilio number or a Verified outgoing caller id for your account. If the |
method
Optional
|
The HTTP method we should use when calling the |
fallback_url
Optional
|
The URL that we call using the |
fallback_method
Optional
|
The HTTP method that we should use to request the |
status_callback
Optional
|
The URL we should call using the |
status_callback_event
Optional
|
The call progress events that we will send to the |
status_callback_method
Optional
|
The HTTP method we should use when calling the |
send_digits
Optional
|
A string of keys to dial after connecting to the number, maximum of 32 digits. Valid digits in the string include: any digit ( |
timeout
Optional
|
The integer number of seconds that we should allow the phone to ring before assuming there is no answer. The default is |
record
Optional
|
Whether to record the call. Can be |
recording_channels
Optional
|
The number of channels in the final recording. Can be: |
recording_status_callback
Optional
|
The URL that we call when the recording is available to be accessed. |
recording_status_callback_method
Optional
|
The HTTP method we should use when calling the |
sip_auth_username
Optional
|
The username used to authenticate the caller making a SIP call. |
sip_auth_password
Optional
|
The password required to authenticate the user account specified in |
machine_detection
Optional
|
Whether to detect if a human, answering machine, or fax has picked up the call. Can be: |
machine_detection_timeout
Optional
|
The number of seconds that we should attempt to detect an answering machine before timing out and sending a voice request with |
recording_status_callback_event
Optional
|
The recording status events that will trigger calls to the URL specified in |
trim
Optional
|
Whether to trim any leading and trailing silence from the recording. Can be: |
caller_id
Optional
|
The phone number, SIP address, or Client identifier that made this call. Phone numbers are in E.164 format (e.g., +16175551212). SIP addresses are formatted as |
machine_detection_speech_threshold
Optional
|
The number of milliseconds that is used as the measuring stick for the length of the speech activity, where durations lower than this value will be interpreted as a human and longer than this value as a machine. Possible Values: 1000-6000. Default: 2400. |
machine_detection_speech_end_threshold
Optional
|
The number of milliseconds of silence after speech activity at which point the speech activity is considered complete. Possible Values: 500-5000. Default: 1200. |
machine_detection_silence_timeout
Optional
|
The number of milliseconds of initial silence after which an |
async_amd
Optional
|
Select whether to perform answering machine detection in the background. Default, blocks the execution of the call until Answering Machine Detection is completed. Can be: |
async_amd_status_callback
Optional
|
The URL that we should call using the |
async_amd_status_callback_method
Optional
|
The HTTP method we should use when calling the |
byoc
Optional
|
The SID of a BYOC (Bring Your Own Carrier) trunk to route this call with. Note that |
call_reason
Optional
|
The Reason for the outgoing call. Use it to specify the purpose of the call that is presented on the called party's phone. (Branded Calls Beta) |
call_token
Optional
|
A token string needed to invoke a forwarded call. A call_token is generated when an incoming call is received on a Twilio number. Pass an incoming call's call_token value to a forwarded call via the call_token parameter when creating a new call. A forwarded call should bear the same CallerID of the original incoming call. |
recording_track
Optional
|
The audio track to record for the call. Can be: |
time_limit
Optional
|
The maximum duration of the call in seconds. Constraints depend on account and configuration. |
url
Required if
twiml,
application_sid
is not passed
|
The absolute URL that returns the TwiML instructions for the call. We will call this URL using the |
twiml
Required if
url,
application_sid
is not passed
|
TwiML instructions for the call Twilio will use without fetching Twiml from url parameter. If both |
application_sid
Required if
url,
twiml
is not passed
|
The SID of the Application resource that will handle the call, if the call will be handled by an application. |
Example 1
Example 2
Example 3
Example 4
StatusCallback
Depois de concluir uma chamada outbound, a Twilio fará uma solicitação HTTP assíncrona ao StatusCallback
especificado em sua solicitação (se houver).
Parâmetros enviados ao URL de StatusCallback
Quando a Twilio envia sua solicitação assíncrona para seu URL StatusCallback
, ele inclui todos os seguintes parâmetros:
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 |
O número de telefone ou identificador do cliente da parte que iniciou a chamada. Os números de telefone usam a formatação E.164, o que significa que eles começam com um + e um código de país, por exemplo Os identificadores de cliente começam com o esquema URI |
To (Para) |
O número de telefone ou identificador do cliente da parte chamada. Os números de telefone usam a formatação E.164, o que significa que eles começam com um Os identificadores de cliente começam com o esquema URI |
CallStatus |
Um status descritivo para a chamada. The value is one of the following: |
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 discado. Para chamadas de saída, esta é a versão usada na solicitação da API REST da chamada de saída. |
Direction |
Uma string que descreve a direção da chamada:
|
ForwardedFrom |
Este parâmetro pode ser definido quando a Twilio recebe uma chamada encaminhada. A operadora que encaminha a chamada determina o conteúdo do parâmetro. Nem todas as operadoras oferecem suporte para a aprovação dessas informações. Algumas operadoras fornecem essas informações ao fazer uma chamada direta para um número da Twilio. |
CallerName | Esse parâmetro é definido quando o IncomingPhoneNumber que recebeu a chamada definiu seu valor VoiceCallerIdLookup para true (US$ 0,01 por pesquisa). |
ParentCallSid |
Um identificador exclusivo para a chamada que criou este trecho. Se este for o primeiro trecho de uma chamada, esse parâmetro não será incluído. |
StatusCallbackEvent
Se você especificar qualquer evento de progresso de chamada no parâmetro StatusCallbackEvent
, a Twilio fará uma solicitação assíncrona para o URL StatusCallback
fornecido em sua solicitação POST.
Os eventos de progresso de chamada que você pode especificar são:
Evento | Descrição |
---|---|
initiated (iniciado) |
A Twilio remove sua chamada da fila e inicia a discagem. |
ringing (tocando) |
A chamada começa a tocar. |
answered (atendido) |
A chamada é atendida. Se esse evento for especificado, a Twilio enviará um status in-progress . |
completed (concluído) |
A chamada é concluída, independentemente do status de encerramento (que pode ser busy , cancelled , completed , failed ou no-answer ). Se nenhum StatusCallbackEvent for especificado, completed (concluído) será acionado por padrão. |
Quando esses eventos ocorrem, a solicitação StatusCallback
da Twilio também incluirá estes parâmetros adicionais:
Parâmetro | Descrição |
---|---|
CallStatus |
Um status descritivo para a chamada. O valor é um de queued , initiated , ringing , in-progress , busy , failed ou no-answer . Para obter mais detalhes, consulte os valores de CallStatus em nossa introdução ao TwiML. |
Duration (Duração) |
A duração em minutos da chamada recém‐concluída; as chamadas são cobradas por minuto. Presente apenas no evento completed . |
CallDuration |
A duração em segundos da chamada recém‐concluída. Presente apenas no evento completed . |
SipResponseCode |
O código SIP que resultou em uma chamada com falha. Presente apenas no evento |
RecordingUrl |
O URL do áudio gravado da chamada telefônica. Esse parâmetro é incluído somente se Record=true estiver definido na solicitação da API REST e não incluir gravações iniciadas de outras maneiras. RecordingUrl está presente somente no evento completed . O arquivo de gravação talvez ainda não esteja acessível quando o StatusCallback for enviado. Observação: Use RecordingStatusCallback para notificação confiável sobre quando a gravação estiver disponível para acesso. |
RecordingSid |
O ID exclusivo da Gravação desta chamada. RecordingSid está presente somente com o evento completed . |
RecordingDuration |
A duração do áudio gravado (em segundos). RecordingDuration está presente somente no evento completed . Para obter uma duração de gravação final precisa após um corte de silêncio, use RecordingStatusCallback . |
Timestamp |
O carimbo de data/hora quando o evento foi disparado, fornecido como UTC no formato RFC 2822. |
CallbackSource |
Uma cadeia de caracteres que descreve a origem do webhook. Isso é fornecido para ajudar a esclarecer por que o webhook foi feito. Em Retornos de Chamada de Status, esse valor é sempre call-progress-events . |
SequenceNumber |
A ordem em que os eventos foram disparados, começando no 0 . Embora os eventos sejam disparados em ordem, eles são feitos como solicitações HTTP separadas, e não há garantia de que eles chegarão na mesma ordem. |
Para saber mais sobre o parâmetro StatusCallbackEvent
e o que você pode esperar da Twilio durante e após uma chamada outbound, consulte nossa página de visão geral sobre making outbound calls (como fazer chamadas outbound).
RecordingStatusCallback
Se você solicitou uma gravação de sua chamada outbound e especificou um URL RecordingStatusCallback
, a Twilio fará uma solicitação GET ou POST para esse URL quando a gravação estiver disponível.
A Twilio passará ao longo dos seguintes parâmetros para o seu URL 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. O CallSid sempre fará referência ao trecho principal de uma chamada de dois trechos. |
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: in-progress , completed , absent . |
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. Os valores possíveis são 1 ,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 quando Record=true for definido na API REST,OutboundAPI será retornado. |
RecordingTrack |
A faixa de áudio gravada. Os valores possíveis são inbound , outbound ou both . |
RecordingStatusCallbackEvent
Assim como você pode especificar eventos de progresso de chamada com StatusCallbackEvent
, também é possível especificar quais alterações de status de gravação devem acionar um retorno de chamada para seu aplicativo.
Os valores de status de gravação disponíveis são:
Parâmetro | Descrição |
---|---|
in-progress (em andamento) |
A gravação foi iniciada. |
completed (concluído) |
A gravação está completa e disponível para acesso. |
absent (ausente) |
A gravação está ausente e inacessível. |
Esse parâmetro assume como padrão completed
. Para especificar vários valores, separe‐os com um espaço.
Para pausar, retomar ou parar gravações, consulte o recurso Call Recording (Gravação de chamadas).
Buscar um Recurso de Chamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json
Esta chamada de API retorna o Recurso de Chamada de uma chamada individual, identificada por seu CallSid
. Este recurso é eventualmente consistente.
Para obter atualizações de status de chamada em tempo real, recomendamos o uso do StatusCallbackEvent na solicitação da API de saída ou o atributo statusCallbackEvent do verbo <Dial> do TwiML para o caso de chamadas filhas.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
The SID of the Account that created the Call resource(s) to fetch. |
sid
Path
|
The SID of the Call resource to fetch. |
Example 1
Gravações de chamadas
Você pode acessar o sub‐recurso da lista de Gravações em qualquer Chamada específica.
O seguinte retornará uma lista de todas as gravações geradas com uma determinada chamada (identificada por seu CallSid
):
/2010-04-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Recordings
Consulte os documentos do recurso Call Recording (Gravação de chamadas) para obter as propriedades do recurso e os formatos de resposta.
Feedback de Chamada
Você pode acessar as informações de feedback de qualidade da chamada de uma determinada chamada telefônica solicitando o sub‐recurso Feedback em qualquer Chamada (identificado por seu CallSid
):
/2010-04-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Feedback
Consulte também a documentação do recurso de Feedback Call Quality (Qualidade de chamada) para obter as propriedades e os formatos de resposta. Consulte também o recurso FeedbackSummary para obter informações resumidas sobre a qualidade da chamada.
Ler vários recursos de Chamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls.json
Retorna uma lista de chamadas telefônicas feitas de e para uma conta, identificada por seu AccountSid
.
Os parâmetros de string de consulta a seguir permitem filtrar e limitar a lista retornada a você pela API REST. Esses parâmetros diferenciam maiúsculas de minúsculas.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
The SID of the Account that created the Call resource(s) to read. |
to
Optional
|
Only show calls made to this phone number, SIP address, Client identifier or SIM SID. |
from
Optional
|
Only include calls from this phone number, SIP address, Client identifier or SIM SID. |
parent_call_sid
Optional
|
Only include calls spawned by calls with this SID. |
status
Optional
|
The status of the calls to include. Can be: |
start_time
Optional
|
Only include calls that started on this date. Specify a date as |
end_time
Optional
|
Only include calls that ended on this date. Specify a date as |
Example 1
Example 2
Example 3
Example 4
Example 5
Example 6
Você pode anexar uma extensão .csv
a qualquer URI de recurso para obter a representação CSV (Comma Separated Values, valores separados por vírgula). Especificar o CSV pode ser especialmente útil para registros de chamadas. Tente isto:
GET /2010-04-01/Accounts/{AccountSid}/Calls.csv
Leia o guia para Returning JSON, CSV, and HTML (Retornar JSON, CSV e HTML) para obter mais informações sobre todas as representações alternativas disponíveis.
Paginação
Se você estiver usando a API REST da Twilio, a lista retornada a você incluirá informações de paginação.
Se planeja solicitar mais registros do que caberá em uma única página, você pode usar o nextpageuri
fornecido em vez de incrementar as páginas por número de página.
O uso de nextpageuri
para a paginação garante que sua próxima solicitação retome de onde você parou. Isso pode ajudar a impedir que você recupere dados duplicados se estiver fazendo ou recebendo chamadas ativamente.
Todas as Twilio Helper Libraries (Bibliotecas auxiliares da Twilio) lidam com a paginação automaticamente. Você não precisa solicitar explicitamente páginas individuais ao usar uma Biblioteca auxiliar para buscar listas de recursos.
Atualizar um recurso de Chamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json
A atualização de um recurso de Chamada permite que você modifique uma chamada ativa.
A modificação de chamadas em tempo real permite interromper uma chamada em andamento e encerrá‐la ou fazer com que ela comece a processar o TwiML a partir de um novo URL ou do TwiML fornecido com modificação. A modificação de chamadas é útil para qualquer aplicativo em que você deseja alterar o comportamento de uma chamada em execução de forma assíncrona. Por exemplo, colocar música em espera, filas de chamadas, transferir chamadas ou forçar um desligamento.
Ao usar POST em uma instância de Chamada específica, você pode redirecionar uma chamada que está em andamento ou encerrar uma chamada.
Para obter orientações passo a passo sobre como modificar chamadas em andamento, consulte o tutorial Modify Calls in Progress (Modificar chamadas em andamento) no idioma de sua preferência na web.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
The SID of the Account that created the Call resource(s) to update. |
sid
Path
|
The Twilio-provided string that uniquely identifies the Call resource to update |
url
Optional
|
The absolute URL that returns the TwiML instructions for the call. We will call this URL using the |
method
Optional
|
The HTTP method we should use when calling the |
status
Optional
|
The new status of the resource. Can be: |
fallback_url
Optional
|
The URL that we call using the |
fallback_method
Optional
|
The HTTP method that we should use to request the |
status_callback
Optional
|
The URL we should call using the |
status_callback_method
Optional
|
The HTTP method we should use when requesting the |
twiml
Optional
|
TwiML instructions for the call Twilio will use without fetching Twiml from url. Twiml and url parameters are mutually exclusive |
time_limit
Optional
|
The maximum duration of the call in seconds. Constraints depend on account and configuration. |
Example 1
Example 2
Example 3
Quando você redireciona uma chamada ativa para outro número de telefone, a Twilio cria uma instância de Chamada totalmente nova para esse novo número de telefone. A chamada original é a chamada principal e qualquer número adicional discado estabelece uma chamada secundária. As chamadas principal e secundária terão SIDs de Chamada com identificação exclusiva.
Observe que qualquer chamada principal que execute atualmente um <Dial> é considerada em andamento pela Twilio. Mesmo que você tenha redirecionado sua chamada inicial para um novo número, a chamada principal ainda estará ativa e, portanto, você deverá usar Status=completed
para encerrá‐la.
Se os Enhanced SIP Features (Recursos SIP aprimorados) não estiverem ativados em sua conta, as chamadas secundárias não atendidas não poderão ser canceladas pela API REST, mas a chamada principal poderá ser modificada para apontar para o novo TwiML. Esta ação encerrará a chamada secundária.
Example 4
Para atualizar um StatusCallback
em uma Chamada, é necessário definir o Url
na mesma instrução.
Excluir um recurso de Chamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json
Isso excluirá um registro de chamada da sua conta. Depois que o registro for excluído, ele não aparecerá mais nos logs da API e do Portal da Conta.
Se bem‐sucedido, esse DELETE retornará um HTTP 204 (Sem conteúdo) sem corpo.
Observe que um erro ocorrerá se você tentar remover um registro de chamada para uma chamada que está em andamento.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
O SID da Account (Conta) que criou os recursos de Chamada para delete (excluir). |
sid
Path
|
A SID de chamada fornecida pela Twilio que identifica exclusivamente o recurso de Chamada para delete (excluir) |
Observação: Para chamadas com menos de 13 meses de idade, os recursos excluídos desse endpoint também serão excluídos nos arquivos de log. Chamadas com mais de 13 meses podem ser excluídas apenas por meio da API de Exportação em Massa.
Example 1
Retenção de recurso de Chamada
Você pode recuperar recursos via GET para o endpoint /Calls
13 meses após a criação do recurso. Registros com mais de treze meses só podem ser recuperados via Exportação em Massa.
Fornecemos um utilitário de Exportação em Massa no Console e via API. A Exportação em massa gerará arquivos S3 contendo um dia de dados por arquivo e entregará o link de download via webhook, e‐mail ou Console.
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.