Procedimiento de integración de una centralita virtual con el sistema

Copiar enlace al artículo

Copiado

Contenido

1. Posibilidades de integración del sistema y una centralita virtual
2. Registro y configuración de la telefonía
   • Códigos de extensión
   • Números externos
   • Ejemplo de creación o edición de la telefonía
3. Obtención de información sobre la telefonía
4. Carga del historial de llamadas
   • Carga del historial inmediatamente después de la llamada
   • Carga periódica del historial de llamadas
   • Grabaciones de llamadas
5. Obtención del mánager responsable
6. Eventos de llamadas
   • Ejemplo de solicitud
7. Inicio de una llamada
   • Ejemplo de solicitud a makeCallUrl
8. Notificación del cambio de estado de un usuario en el sistema
   • Ejemplo de solicitud a changeUserStatusUrl

Al sistema se puede conectar cualquier centralita telefónica privada (PBX), ya sea en la nube o instalada localmente. Si no se encuentra el módulo deseado en el Marketplace, la telefonía puede conectarse mediante la API.

Posibilidades de integración del sistema y una centralita virtual

La API de telefonía del sistema permite:

1. Iniciar llamadas desde el sistema.
2. Cargar en el sistema el historial de llamadas.
3. Obtener por número de teléfono el mánager responsable para enrutar una llamada entrante.
4. Notificar al sistema los eventos de llamadas.

El trabajo con la API se realiza de acuerdo con las reglas de uso de la API. Para la integración se utilizan los métodos de las secciones «Telefonía» y «Usuarios» de la API.

El algoritmo de integración de una centralita virtual con el sistema consta de los siguientes pasos:

• USER Solicitar al usuario la clave API de acceso al sistema.
• API Registrar una nueva telefonía.
• API | USER Asignar códigos de extensión a los usuarios del sistema o definir la correspondencia al registrar la telefonía.
• API | USER Asignar números de teléfono externos o definir la correspondencia al registrar la telefonía.
• API Cargar en el sistema el historial de llamadas de la centralita virtual.
• API Utilizar los datos del mánager responsable al distribuir las llamadas.
• API Enviar al sistema notificaciones sobre eventos de llamadas.

Los pasos marcados con USER requieren que el usuario proporcione o complete los datos. Los demás pasos, marcados con API, se realizan mediante solicitudes API.

Registro y configuración de la telefonía

Para registrar una nueva telefonía o cambiar la configuración de una existente, se utiliza el método POST /api/v5/integration-modules/{code}/edit. Si ya existe una telefonía con el código code, el método modifica su configuración; de lo contrario, crea una nueva. Durante el registro se transmite el código único clientId, que permite identificar la cuenta de telefonía del sistema.

Si se transmite false en el campo allowEdit, la configuración de la integración solo podrá editarse mediante la API. Los usuarios del sistema únicamente podrán eliminar la integración.

El campo makeCallUrl contiene la dirección a la que el sistema enviará las solicitudes para el inicio de una llamada.

El campo changeUserStatusUrl contiene la dirección a la que el sistema enviará las solicitudes para notificar el cambio de estado de un usuario.

El parámetro personalAccountUrl permite transmitir la URL de acceso al área personal de la telefonía.

En el área personal se pueden configurar los códigos de extensión, las reglas de desvío, las colas y otros parámetros de la telefonía.

Códigos de extensión

La correspondencia entre los códigos de extensión y los usuarios puede configurarse de dos maneras:

• Mediante la API, completando el campo additionalCodes en el método de creación o edición de la telefonía.
• Desde la interfaz de configuración. En Marketplace → página de edición de la telefonía, indique en la sección «Códigos de extensión» las extensiones de los empleados que recibirán o iniciarán llamadas.

Si el campo makeCallUrl está configurado y el usuario autorizado tiene asignado un código de extensión, en las páginas del sistema aparecerá el icono del teléfono para iniciar llamadas.

Números externos

La correspondencia entre los números externos y las tiendas puede configurarse de dos maneras:

• Mediante la API, completando el campo externalPhones en el método de creación o edición de la telefonía.
• Desde la interfaz de configuración. En Marketplace → página de edición de la telefonía, configure en la sección «Números externos» la correspondencia entre cada tienda y su número externo.

Si se han configurado números externos y la llamada se inicia desde una entidad vinculada a una tienda, el parámetro externalPhone se enviará a la dirección makeCallUrl.

Si el parámetro externalPhone está presente en un evento de llamada y dicho número externo existe en la configuración de la telefonía, la ventana emergente mostrará el destino de la llamada, por ejemplo, «Tienda 1».

Ejemplo de creación o edición de la telefonía

Supongamos que existe el sistema https://example.retailcrm.ru, con dos usuarios cuyos ID son 1 y 2, y dos tiendas con los códigos simbólicos shop1 y shop2.

En la centralita están configuradas las extensiones 100 y 200, así como los números externos +7-499-999-99-99 y +7-499-888-88-88.

Para crear o editar la telefonía con el código my-telephony, es necesario enviar una solicitud POST a:

https://example.retailcrm.ru/api/v5/integration-modules/my-telephony/edit

El parámetro integrationModule debe contener el siguiente JSON:

{
    "code": "my-telephony",
    "active": true,
    "name": "Nombre de la telefonía",
    "logo": "http://api.telephony-test.ru/logo.svg",
    "clientId": "2dbh26tahjj26sg",
    "accountUrl": "http://api.telephony-test.ru/settings",
    "integrations": {
        "telephony": {
            "makeCallUrl": "http://api.telephony-test.ru/make-call",
            "allowEdit": false,
            "inputEventSupported": true,
            "additionalCodes": [
                {"userId": "1", "code": 100},
                {"userId": "2", "code": 200}
            ],
            "externalPhones": [
                {"siteCode": "shop1", "externalPhone": "+7-499-999-99-99"},
                {"siteCode": "shop2", "externalPhone": "+7-499-888-88-88"}
            ],
            "changeUserStatusUrl": "http://api.telephony-test.ru/change-status"
        }
    }
}

Respuesta

HTTP/1.1 201 OK

{
  "success": true
}

Obtención de información sobre la telefonía

Para obtener información sobre la integración con la telefonía, se utiliza el método GET /api/v5/integration-modules/{code}.

Carga del historial de llamadas

Para cargar el historial, se utiliza el método POST /api/v5/telephony/calls/upload. En una sola solicitud pueden guardarse hasta 50 llamadas. La centralita puede cargar el historial mediante una de las siguientes estrategias.

Carga del historial inmediatamente después de la llamada

Después de una llamada entrante o saliente, la centralita envía al sistema el historial de esa llamada. Por lo general, la solicitud contiene un único registro del historial.

Carga periódica del historial de llamadas

La centralita envía periódicamente al sistema, por ejemplo, una vez cada 10 minutos, el historial de las llamadas acumuladas desde la carga anterior.

Grabaciones de llamadas

El campo calls[][recordUrl] contiene el enlace a la grabación de la llamada.

Cuando se intenta reproducir la grabación, el sistema envía una solicitud GET a la dirección indicada en calls[][recordUrl] con el siguiente parámetro:

• clientId: código único del sistema transmitido durante el registro de la telefonía. Encontrará más información en el artículo sobre la activación de módulos.

Para reproducir correctamente el audio, es necesario indicar el encabezado Content-Type correcto.

Obtención del mánager responsable

El método GET /api/v5/telephony/manager permite transmitir un número de teléfono. El sistema intenta encontrar al cliente correspondiente y, si existe, devolver a su mánager responsable cuando este se encuentre disponible. El método resulta útil para enrutar una llamada entrante al código de extensión del mánager responsable.

El mánager se considera disponible si ha iniciado sesión en el sistema y tiene establecido el estado «libre». Además, debe tener asignado un código de extensión en la configuración de la integración. Si no se cumple alguna de estas condiciones, el método no devolverá al mánager responsable.

Eventos de llamadas

El método POST /api/v5/telephony/call/event permite notificar al sistema los eventos de una llamada. Deben transmitirse eventos de tres tipos: llamada entrante, llamada saliente y finalización de llamada.

Cuando se transmite un evento de llamada entrante, el mánager a cuyo código de extensión se dirige la llamada verá la ficha de la llamada.

Ejemplo de solicitud

Supongamos que el sistema https://example.retailcrm.ru tiene activa la integración con la telefonía. En la configuración están definidos los códigos de extensión 100 y 200, así como los números externos +7-499-999-99-99 y +7-499-888-88-88.

Es necesario enviar una solicitud POST a:

https://example.retailcrm.ru/api/v5/telephony/call/event

El parámetro event debe contener el siguiente JSON:

{
    "phone": "+7-555-555-55-55",
    "type": "in",
    "codes": ["100"],
    "externalPhone": "+7-444-444-44-44"
}

Respuesta

HTTP/1.1 200 OK

{
  "success": true
}

Inicio de una llamada

Al configurar la integración, el campo configuration["makeCallUrl"] contiene la dirección a la que el sistema enviará las solicitudes para iniciar una llamada.

El sistema envía una solicitud GET {configuration["makeCallUrl"]} con los siguientes parámetros:

• clientId: código único del sistema transmitido durante el registro de la telefonía.
• code: código de extensión del usuario que inicia la llamada.
• phone: número de teléfono al que se realiza la llamada.
• userId: ID del usuario en el sistema.
• externalPhone: número de teléfono externo, si está presente en la configuración de la telefonía.

Si la llamada se inicia correctamente, la centralita debe devolver el estado HTTP 200. Cualquier otro estado se interpretará como un error al iniciar la llamada y el usuario recibirá la notificación correspondiente. El cuerpo de la respuesta HTTP se ignora.

Ejemplo de solicitud a makeCallUrl

Supongamos que se ha registrado la dirección makeCallUrl http://api.telephony-test.ru/make-call. El mánager con el código de extensión 100 y el ID 1 llama a un cliente cuyo número es +7 (912) 123-45-67.

Solicitud

http://api.telephony-test.ru/make-call?clientId=2dbh26tahjj26sg&code=100&phone=+79121234567&userId=1

Respuesta

HTTP/1.1 200 OK

Notificación del cambio de estado de un usuario en el sistema

Si el campo changeUserStatusUrl está configurado y el usuario autorizado tiene asignado un código de extensión, el sistema enviará solicitudes para notificar los cambios de estado del usuario.

El sistema envía una solicitud GET {configuration["changeUserStatusUrl"]} con los siguientes parámetros:

• clientId: código único del sistema transmitido durante el registro de la telefonía.
• userId: ID del usuario en el sistema.
• code: código de extensión del usuario cuyo estado ha cambiado.
• status: nuevo estado del usuario en el sistema.

El campo status puede contener los valores free, busy, dinner o break.

Ejemplo de solicitud a changeUserStatusUrl

Supongamos que se ha registrado la dirección changeUserStatusUrl http://api.telephony-test.ru/change-status. El mánager con el código de extensión 100 y el ID 1 ha cambiado su estado a busy.

Solicitud

http://api.telephony-test.ru/change-status?clientId=2dbh26tahjj26sg&code=100&userId=1&status=busy

El cuerpo y el estado de la respuesta HTTP se ignoran.