API de llamadas de devolución de llamada

Las llamadas de devolución son las que solicita un usuario final. Con la API de llamadas de devolución de llamada, puedes programar llamadas de devolución de llamada y cancelar llamadas programadas de manera programática. Con estas funciones, puedes crear aplicaciones que permitan a los usuarios finales solicitar llamadas de devolución desde una cola que especifiques. Los usuarios finales también pueden cancelar las llamadas que programaron anteriormente. Para obtener información sobre la autenticación con la API de llamada de devolución de llamada, consulta Autenticación básica.

Usa la API de llamadas de devolución de llamada

Puedes usar la API de llamadas de devolución para programar llamadas de devolución y cancelar llamadas programadas.

Programar una llamada

Para programar una llamada, llama a POST https://<subdomain>.<domain>/apps/api/v1/calls y, luego, incluye un cuerpo de solicitud similar al siguiente:

{
    "call_type": "ScheduledCall",
    "menu_id": 12345,
    "end_user_number": "[phone]",
    "scheduled_at": "2025-09-02T14:30:00Z"
}

Una solicitud correcta devuelve un objeto de llamada, incluido el ID de llamada.

Cómo cancelar una llamada programada

Para cancelar una llamada programada, llama a PATCH https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/{id}/cancel. Especifica el ID de la llamada que deseas cancelar.

Una solicitud correcta devuelve un 200 OK con el objeto de llamada actualizado. El status del objeto de llamada es cancelled cuando la llamada estaba esperando su hora programada o estaba ingresando o esperando en la cola, y completed cuando cancelas una devolución de llamada de agente virtual activa que ya realizó su primer intento de marcado. Si la llamada ya se canceló, la solicitud devuelve 204 No Content con un cuerpo vacío. Una solicitud de una llamada que ya falló por un motivo que no sea la cancelación, o que se encuentra en un estado que no se puede cancelar, devuelve 400.

Cómo cancelar varias llamadas programadas

Para cancelar varias llamadas programadas, llama a PATCH https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/cancel. Incluye un cuerpo de solicitud que contenga un array call_ids de los IDs de las llamadas que se cancelarán.

Consulta la siguiente muestra de código:

{
    "call_ids": [123, 456, 789]
}

Una solicitud correcta devuelve un 202 Accepted con un encabezado de respuesta Location que apunta a un recurso de trabajo que puedes sondear para verificar que se haya completado. La respuesta 202 Accepted no significa que todas las llamadas se hayan cancelado todavía; sigue el encabezado Location para confirmar la finalización y, luego, inspecciona las fallas parciales.

Usa llamadas de devolución con CRM

Puedes usar la API de llamadas de devolución de llamada con las integraciones de CRM de Salesforce, Zendesk y ServiceNow.

Comportamiento general de las devoluciones de llamada

Si usas cualquier CRM compatible (Salesforce, Zendesk o ServiceNow), las siguientes condiciones afectan el comportamiento de la devolución de llamada programada:

• Un registro está abierto y ya tiene una llamada programada activa: Si una búsqueda de ID de ticket indica que el registro está abierto y ya tiene una llamada programada activa, la llamada no se programa. El siguiente comentario se adjunta al registro de CRM: A scheduled call was not created because the record already has an active scheduled call.

• No se puede acceder a la CRM: Si una búsqueda de ID de ticket indica que no se puede acceder a la CRM, se cancela la llamada. Se adjuntó el siguiente comentario al registro de CRM: A scheduled call was canceled because the CRM was unreachable.

Comportamiento de las devoluciones de llamada con registros cerrados

La forma en que se manejan las llamadas de devolución para los registros cerrados varía según el CRM que uses:

• Usuarios de Zendesk y ServiceNow: Si una búsqueda de ID de ticket indica que el registro está cerrado, no se programa la llamada. El siguiente comentario se adjunta al registro de CRM: A scheduled call was not created because the record is closed.

• Usuarios de Salesforce: Consulta Llamadas de devolución con Salesforce para configurar cómo tu instancia controla las llamadas programadas para los registros cerrados.

Llamadas de devolución con Salesforce

Si integraste CCAI Platform con Salesforce, puedes configurar cómo tu instancia controla las llamadas programadas para los registros cerrados. Estas son las opciones de configuración para las integraciones de Salesforce:

• No verifiques el estado del registro.

• Verifica el estado de los registros y vuelve a abrir los registros cerrados.

• Verifica el estado de los registros y cancela las llamadas programadas para los registros cerrados.

Nota: La búsqueda del ID de ticket para verificar el estado del registro se realiza cinco minutos antes de que comience la cuenta regresiva de la llamada programada. La cuenta regresiva de la llamada programada es la cantidad de minutos entre el momento en que se asigna una llamada a un agente y el momento en que comienza la llamada programada. Para obtener más información, consulta Configura llamadas programadas.

No verifiques el estado del registro

Puedes configurar CCAI Platform para que no verifique el estado del registro antes de realizar una llamada programada. Con esta configuración, la llamada se realiza según lo programado, independientemente de si el registro está abierto o cerrado.

Para configurar CCAI Platform de modo que no verifique el estado del registro, sigue estos pasos:

1. En el portal de CCAI Platform, haz clic en Configuración > Administración de operaciones. Si no ves el menú Configuración, haz clic en Menú.

2. Ve a CRM Record Creation Details > Closed record options when initiating an API-scheduled call.

3. Selecciona No verificar el estado del registro. Siempre inicia la llamada programada por la API.

4. Haz clic en Guardar configuración general.

Verifica el estado de los registros y vuelve a abrir los que estén cerrados

Puedes configurar CCAI Platform para que verifique el estado del registro antes de realizar una llamada programada y vuelva a abrir los registros que estén cerrados. Con esta configuración, si el estado del registro es cerrado, se realizan las siguientes acciones:

• La llamada se realiza según lo programado.

• Se vuelve a abrir el registro.

• El siguiente comentario se adjuntó al registro de CRM: The record was reopened at the time of a scheduled call.

Para configurar CCAI Platform de modo que verifique el estado de los registros y vuelva a abrir los cerrados, sigue estos pasos:

1. En el portal de CCAI Platform, haz clic en Configuración > Administración de operaciones. Si no ves el menú Configuración, haz clic en Menú.

2. Ve a CRM Record Creation Details > Closed record options when initiating an API-scheduled call.

3. Selecciona Verificar el estado del registro. Si el registro está cerrado > Vuelve a abrir el registro.

4. Haz clic en Guardar configuración general.

Verifica el estado de los registros y cancela las llamadas programadas para los registros cerrados.

Puedes configurar CCAI Platform para que verifique el estado del registro antes de realizar una llamada programada y cancelar las llamadas programadas para los registros que estén cerrados. Con esta configuración, si el estado del registro es cerrado, se realizan las siguientes acciones:

• Se cancelará la llamada programada.

• El siguiente comentario se adjuntó al registro de CRM: A scheduled call was canceled because the record is closed.

Para configurar CCAI Platform de modo que verifique el estado de los registros y cancele las llamadas programadas para los registros cerrados, sigue estos pasos:

1. En el portal de CCAI Platform, haz clic en Configuración > Administración de operaciones. Si no ves el menú Configuración, haz clic en Menú.

2. Ve a CRM Record Creation Details > Closed record options when initiating an API-scheduled call.

3. Selecciona Verificar el estado del registro. Si el registro está cerrado, > Cancela la llamada programada.

4. Haz clic en Guardar configuración general.