Recurso de llamada
Una llamada es un objeto que representa una conexión entre un teléfono y Twilio.
Con este recurso, puedes iniciar una llamada, obtener información sobre una llamada completada, obtener una lista de llamadas realizadas a tu cuenta y desde ella, redirigir o finalizar una llamada en curso y eliminar registros de llamadas pasadas de tu cuenta.
Una llamada entrante se produce cuando una persona llama a uno de tus números de teléfono de Twilio, conexiones de cliente o puntos finales habilitados para SIP. Una llamada saliente se produce cuando se inicia una llamada desde un número de teléfono de Twilio a un número de teléfono, cliente o dominio SIP externo.
Puedes iniciar una llamada saliente realizando un POST en el recurso de llamada, lo que creará una nueva llamada.
También puedes iniciar una llamada desde una llamada activa (p. ej., redirigir la llamada a otro número o marcar para entrar en una conferencia); para ello, incluye el verbo de TwiML <Dial> en tu aplicación de TwiML. Sin embargo, la única manera de iniciar una llamada directamente desde Twilio es con una solicitud de API.
Propiedades de llamada
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 del estado de la llamada
Los siguientes son los valores posibles para el parámetro Status
:
Estado | Descripción |
---|---|
queued |
La llamada está lista y esperando su turno antes de marcar. |
ringing |
La llamada está sonando actualmente. |
in-progress |
Se contestó la llamada y está en curso. |
canceled |
La llamada se colgó mientras estaba en cola o sonando. |
completed |
Se contestó la llamada y se finalizó normalmente. |
busy |
El agente de llamada recibió una señal de ocupado. |
no-answer |
No hubo respuesta o se rechazó la llamada. |
failed |
No se pudo completar la llamada como se marcó, probablemente porque el número de teléfono no existía. |
Crear un recurso de llamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls.json
Las llamadas se pueden realizar a través de la API REST a números de teléfono, direcciones SIP o identificadores de cliente. Para realizar una nueva llamada saliente, realiza una solicitud HTTP POST al recurso de llamada de tu cuenta.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
El SID de la Account que creará el 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
Después de completar una llamada saliente, Twilio hará una solicitud HTTP asíncrona a la URL de StatusCallback
que especificaste en tu solicitud (si la hubiera).
Parámetros enviados a la URL de StatusCallback
Cuando Twilio envía su solicitud asíncrona a tu URL de StatusCallback
, incluye todos los parámetros siguientes:
Parámetro | Descripción |
---|---|
CallSid | Un identificador único para esta llamada, generado por Twilio. |
AccountSid | Tu ID de cuenta de Twilio. Tiene 34 caracteres y siempre comienza con las letras AC . |
De |
El número de teléfono o identificador de cliente de la parte que inició la llamada. Los números de teléfono utilizan el formato E.164, lo que significa que comienzan con un signo de + y el código de país, por ejemplo Los identificadores de cliente comienzan con el esquema de URI |
To (Para) |
El número de teléfono o identificador de cliente de la parte a la que se llama. Los números de teléfono utilizan el formato E.164, lo que significa que comienzan con un signo de Los identificadores de cliente comienzan con el esquema de URI |
CallStatus |
Un estado descriptivo de la llamada. The value is one of the following: |
ApiVersion |
La versión de la API de Twilio que se utilizó para gestionar esta llamada. En el caso de las llamadas entrantes, esto se determina según la versión de la API establecida en el número que se marca. Para las llamadas salientes, esta es la versión utilizada en la solicitud de la API REST de la llamada saliente. |
Direction |
Una cadena que describe la dirección de la llamada:
|
ForwardedFrom |
Este parámetro puede establecerse cuando Twilio recibe una llamada transferida. El operador móvil que transfiere la llamada determina el contenido del parámetro. No todos los operadores móviles admiten el paso de esta información. Algunos operadores móviles proporcionan esta información cuando realizan una llamada directa a un número de Twilio. |
CallerName | Este parámetro se establece cuando el IncomingPhoneNumber que recibió la llamada estableció su valor VoiceCallerIdLookup en true (USD 0,01 por búsqueda). |
ParentCallSid |
Un identificador único para la llamada que creó este tramo. Si se trata del primer tramo de una llamada, este parámetro no se incluye. |
StatusCallbackEvent
Si especificas cualquier evento de progreso de llamada en el parámetro StatusCallbackEvent
, Twilio hará una solicitud asíncrona a la URL de StatusCallback
que proporcionaste en tu solicitud de POST.
Los eventos de progreso de llamada que puedes especificar son estos:
Evento | Descripción |
---|---|
initiated |
Twilio quita tu llamada de la cola y comienza a marcar. |
ringing |
La llamada comienza a sonar. |
answered |
Se contesta la llamada. Si se especifica este evento, Twilio enviará un estado in-progress . |
completed |
La llamada se completa, independientemente del estado de finalización (que puede ser busy , cancelled , completed , failed o no-answer ). Si no se especifica ningún StatusCallbackEvent , se indica como completada de forma predeterminada. |
Cuando se producen estos eventos, la solicitud de StatusCallback
de Twilio también incluirá estos parámetros adicionales:
Parámetro | Descripción |
---|---|
CallStatus |
Un estado descriptivo de la llamada. El valor puede ser queued , initiated , ringing , in-progress , busy , failed o no-answer . Para obtener más información, consulta los valores de CallStatus en nuestra introducción a TwiML. |
Duration |
La duración en minutos de la llamada que acaba de finalizar; las llamadas se facturan por minuto. Solo presente en el evento completed . |
CallDuration |
La duración en segundos de la llamada que acaba de finalizar. Solo presente en el evento completed . |
SipResponseCode |
El código SIP que produjo un error en la llamada. Solo está presente en el evento |
RecordingUrl |
La URL del audio grabado de la llamada telefónica. Este parámetro solo se incluye si Record=true se establece en la solicitud de la API REST y no incluye las grabaciones iniciadas de otras formas. RecordingUrl solo está presente en el evento completed . Es posible que no se pueda acceder al archivo de grabación cuando se envía la devolución de llamada de estado. Nota: Utiliza RecordingStatusCallback para obtener una notificación confiable cuando se pueda acceder a la grabación. |
RecordingSid |
ID exclusivo de la grabación de esta llamada. RecordingSid solo está presente con el evento completed . |
RecordingDuration |
La duración del audio grabado (en segundos). RecordingDuration solo está presente en el evento completed . Para obtener la duración exacta de la grabación después de cualquier recorte de silencio, utiliza RecordingStatusCallback . |
Timestamp |
La marca de tiempo cuando se desencadenó el evento, dada como UTC en formato RFC 2822. |
CallbackSource |
Una cadena que describe el origen del webhook. Esto se proporciona para ayudar a aclarar por qué se hizo el webhook. En las devoluciones de llamada de estado, este valor es siempre call-progress-events . |
SequenceNumber |
Orden en el que se desencadenaron los eventos, empezando por 0 . Aunque los eventos se desencadenan en orden, se realizan como solicitudes HTTP independientes y no hay garantía de que lleguen en el mismo orden. |
Para obtener más información sobre el parámetro StatusCallbackEvent
y lo que puedes esperar de Twilio durante y después de una llamada saliente, consulta nuestra página de descripción general sobre cómo realizar llamadas salientes.
RecordingStatusCallback
Si solicitaste una grabación de tu llamada saliente y especificaste una URL de RecordingStatusCallback
, Twilio realizará una solicitud GET o POST a esa URL cuando la grabación esté disponible.
Twilio pasará los siguientes parámetros a tu URL de RecordingStatusCallback
:
Parámetro | Descripción |
---|---|
AccountSid |
El identificador exclusivo de la cuenta responsable de esta grabación. |
CallSid |
Un identificador exclusivo de la llamada asociada a la grabación. CallSid siempre se referirá al tramo principal de una llamada de dos tramos. |
RecordingSid |
El identificador exclusivo de la grabación. |
RecordingUrl |
La URL del audio grabado. |
RecordingStatus |
El estado de la grabación. Estos son los valores posibles: in-progress , completed , absent . |
RecordingDuration |
La duración de la grabación, en segundos. |
RecordingChannels |
La cantidad de canales en el archivo de grabación final como un entero. Los valores posibles son 1 , 2 . |
RecordingStartTime |
La marca de hora de inicio de la grabación. |
RecordingSource |
El método de inicio utilizado para crear esta grabación. Para las grabaciones iniciadas cuando Record=true se establece en la API REST, se devolverá OutboundAPI . |
RecordingTrack |
La pista de audio grabada. Los valores posibles son inbound , outbound o both . |
RecordingStatusCallbackEvent
Al igual que puedes especificar eventos de progreso de llamada con StatusCallbackEvent
, también puedes especificar qué cambios de estado de grabación deben desencadenar una devolución de llamada a la aplicación.
Estos son los valores de estado de grabación disponibles:
Parámetro | Descripción |
---|---|
in-progress |
La grabación comenzó. |
completed |
La grabación está completa y se puede acceder a ella. |
absent |
No está la grabación y no se puede acceder a ella. |
El valor predeterminado de este parámetro es completed
. Para especificar varios valores, sepáralos con un espacio.
Para pausar, reanudar o detener grabaciones, consulta el recurso de grabación de llamadas.
Obtén un recurso de llamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json
Esta llamada de API devuelve el recurso de llamada de una llamada individual, identificada por su CallSid
. Este recurso es , en última instancia, coherente.
Para obtener actualizaciones del estado de las llamadas en tiempo real, se recomienda utilizar StatusCallbackEvent en la solicitud de la API saliente o el atributo statusCallbackEvent del verbo de TwiML <Dial> en el caso de las llamadas secundarias.
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
Grabaciones de llamadas
Puedes acceder al subrecurso de lista de grabaciones en cualquier llamada determinada.
Lo que aparece a continuación devolverá una lista de todas las grabaciones generadas con una llamada determinada (identificada por su CallSid
):
/2010-04-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Recordings
Consulta la documentación del recurso de grabación de llamadas para ver las propiedades del recurso y los formatos de respuesta.
Comentarios de llamada
Para acceder a la información de comentarios sobre la calidad de una llamada telefónica determinada, solicita el subrecurso de comentarios de cualquier llamada (identificado por su CallSid
):
/2010-04-01/Accounts/{YourAccountSid}/Calls/{CallSid}/Feedback
Consulta la documentación del recurso de comentarios de calidad de la llamada para ver las propiedades y los formatos de respuesta. Consulta también el recurso FeedbackSummary para obtener información resumida sobre la calidad de las llamadas.
Leer varios recursos de llamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls.json
Devuelve una lista de llamadas telefónicas realizadas a una cuenta y desde ella, identificada por su AccountSid
.
Los siguientes parámetros de cadena de consulta permiten filtrar y limitar la lista devuelta por la API REST. Estos parámetros distinguen entre mayúsculas y 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
Puedes agregar una extensión .csv
a cualquier URI de recurso para obtener una representación CSV (valores separados por comas). La especificación de CSV puede resultar especialmente útil para los registros de llamadas. Prueba esto:
GET /2010-04-01/Accounts/{AccountSid}/Calls.csv
Lee la guía para devolver JSON, CSV y HTML a fin de obtener más información sobre todas las representaciones alternativas disponibles.
Paginación
Si utilizas la API REST de Twilio, la lista que se te devuelve incluye información de paginación.
Si tienes pensado solicitar más registros de los que caben en una sola página, puedes utilizar el nextpageuri
proporcionado en lugar de aumentar las páginas por número de página.
El uso de nextpageuri
para la paginación garantiza que la siguiente solicitud se retome en el lugar en que la dejaste. Esto puede ayudarte a evitar que recuperes datos duplicados si realizas o recibes llamadas de forma activa.
Todas las bibliotecas auxiliares de Twilio gestionan la paginación automáticamente. No es necesario solicitar explícitamente páginas individuales cuando se utiliza una biblioteca auxiliar para obtener listas de recursos.
Actualizar un recurso de llamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json
La actualización de un recurso de llamada permite modificar una llamada activa.
La modificación de llamadas en tiempo real te permite interrumpir una llamada en curso y terminarla o hacer que comience a procesar TwiML desde una nueva URL o desde el TwiML proporcionado con la modificación. La modificación de llamadas es útil para cualquier aplicación en la que desees cambiar el comportamiento de una llamada en ejecución de forma asíncrona, por ejemplo, música de espera, colas de llamadas, transferencia de llamadas o forzar una finalización.
Al realizar POST en una instancia de llamada específica, puedes redirigir una llamada que está en curso o terminar una llamada.
Para obtener orientación paso a paso sobre la modificación de llamadas en curso, consulta el tutorial Modificar llamadas en curso en el idioma web que elijas.
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
Al redirigir una llamada activa a otro número de teléfono, Twilio crea una instancia de llamada completamente nueva para ese nuevo número de teléfono. La llamada original es la llamada principal, y cualquier número adicional marcado establece una llamada secundaria. Las llamadas principales y secundarias tendrán SID de llamada de identificación única.
Ten en cuenta que Twilio considera que está en curso cualquier llamada principal que esté ejecutando actualmente un <Dial>. Incluso si redirigiste la llamada inicial a un nuevo número, la llamada principal sigue activa y, por lo tanto, debes utilizar Status=completed
para finalizarla.
Si las funciones SIP mejoradas no están activadas en tu cuenta, las llamadas secundarias no contestadas no se pueden cancelar a través de la API REST, pero la llamada principal se puede modificar para que apunte a un nuevo TwiML. Esta acción finalizará la llamada secundaria.
Example 4
Para actualizar StatusCallback
en una llamada, es necesario establecer la Url
en la misma afirmación.
Eliminar un recurso de llamada
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{Sid}.json
Esto eliminará un registro de llamadas de tu cuenta. Una vez eliminado el registro, ya no aparecerá en los registros de la API y el portal de la cuenta.
Si se realiza correctamente, esta ELIMINACIÓN devuelve un HTTP 204 (Sin contenido) sin cuerpo.
Ten en cuenta que se producirá un error si intentas eliminar el registro de una llamada que está activamente en curso.
Parameters
Parameters in REST API format | |
---|---|
account_sid
Path
|
El SID de la Cuenta que creó los recursos de llamada que se eliminarán. |
sid
Path
|
El SID de llamada proporcionado por Twilio que identifica de forma exclusiva el recurso de llamada que se eliminará. |
Nota: Para las llamadas con menos de 13 meses de antigüedad, los recursos eliminados de este punto final también se eliminarán de los archivos de registro. Las llamadas de más de 13 meses solo se pueden eliminar a través de la API de exportación masiva.
Example 1
Retención de recursos de llamadas
Puedes recuperar recursos mediante la realización de GET al punto final /Calls
durante 13 meses después de crear el recurso. Los registros de más de 13 meses solo se pueden recuperar mediante exportación masiva.
Proporcionamos una utilidad de exportación masiva en la consola y a través de la API. La exportación masiva generará archivos S3 que contienen un día de datos por archivo y enviará el enlace de descarga a través del webhook, el correo electrónico o la consola.
¿Necesitas ayuda?
Todos la necesitamos a veces; la programación es difícil. Obtén ayuda ahora de nuestro equipo de soporte, o recurre a la sabiduría de la multitud visitando Stack Overflow Collective de Twilio o navegando por la etiqueta de Twilio en Stack Overflow.