Saltar a contenido

Integraciones - Webhooks

Los Webhooks se generan en base a los eventos de llamada ocurridos en el sistema. Tales como llamada en timbre, llamada respondida, llamada terminada, etz. Cuando estos eventos pasan, la plataforma de VoIPstudio hace una petición HTTPS (POST) a la URL configurada para el Webhook - Una API de un tercero. Vea mas en Wikipedia

webhooks-config.png

Figura 10.1 Habilitar y Configurar Webhooks.
  1. Haga clic en Integraciones.
  2. Descienda hasta Webshooks y habilite la integración.
  3. Seleccione Añadir Webhook para crear uno.
  4. Introduzca el Nombre para el nuevo Webhook de tal manera que lo pueda identificar.
  5. Seleccione los eventos a los que tiene que reaccionar. Tenga en cuenta que la categoria Cambio de Estado en la llamada incluye todos los eventos.
  6. Introduzca la URL de su aplicación.
  7. Para modificar un Webhooks existente solo haga click en el nombre.
  8. Si no los necesita puede desactivar los Webhooks.

NOTE: Los Webhooks solo funcionan en HTTPS.

NOTE: Para que la URL se guarde tiene que ser válida y responder a peticiones HTTPS. (el servicio tiene que estar levantado)

Eventos Disponibles

En VoIPstudio puede monitorizar las siguientes categorías de eventos:

  • Llamada perdida
  • Llamada en timbre
  • Llamada conectada
  • Llamada terminada
  • Cambio en el estado de la llamada - Incluye todos los eventos anteriores. Reacciona a los siguientes cambios de estado: INITIAL, RINING, CONNECTED, ON_HOLD, HANGUP.

Tenga en cuenta que los eventos monitorizados muestran los cambios en los estados de la llamada en base a la señalización SIP tal como se muestra:

  • INITIAL: SIP INVITE enviado a la terminación SIP (Teléfono IP o Softphone).
  • RINGING: respuesta al SIP INVITE. Indica que el Teléfono o Softphone del usuario está activo y sonando.
  • CONNECTED: Mensaje SIP 200 indicando que el Teléfono o Softphone ha atendido la llamada entrante.
  • ON_HOLD: Llamada pausada. Corresponde a una trama SIP INVITE con el campo body: a=sendonly
  • HANGUP: Indica que la llamada ha terminado. corresponde a un mensaje SIP tipo BYE.

Aparte de los eventos de llamada, tenemos los siguientes eventos disponibles:

  • SMS Recibido.

Atributos de los eventos

Los eventos se entregan como peticiones POST HTTPs en formato JSON body - por ejemplo:

{
  "id":"uk003.608920d55f7ac3.77053295",
  "event_time":"2021-04-28 08:46:13",
  "event_name":"call.hangup",
  "call_id":139543232,
  "state":"HANGUP",
  "connected_at":"2021-04-28 08:46:02",
  "start_time":"2021-04-28 08:45:55",
  "context":"LOCAL_USER",
  "destination":"in",
  "duration":11,
  "t_cause":"Normal Clearing",
  "src":"447854740947",
  "src_id":"0",
  "src_name":"\"442035141598\" <2035141598>",
  "src_hash":"fe5935cefbc82fc4e924bdaa21342a49c18c5dd9",
  "dst":"441183211001",
  "dst_id":"10002",
  "dst_name":"John Smith"
}

Definición de cada atributo:

  • id (string) - identificador único para el evento
  • event_time (string) - tiempo de evento en formato: Y-m-d H:i:s y zona horaria: UTC
  • event_name (string) - Tipo del evento, valores válidos:
    • call.initial - Llamada iniciada
    • call.ringing - Llamada en timbre
    • call.missed - Llamada no atendida/perdida
    • call.connected - Llamada conectada
    • call.hangup - Llamada terminada
    • call.hold - Llamada en espera
    • call.unhold - Llamada retomada
    • call_id (integer) - Identificador numérico de la llamada. Este es el identificador a utilizar en caso de querer referenciar esta llamada dentro de la REST API. La relación con REST API es:
    • call.id - ejemplo de petición via REST API:
    • cdr.live_id - ejemplo de petición REST API: GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
    • monitor.live_id - ejemplo de petición REST API: GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"{call.id}"}]
  • state (string) - Estado de la llamada, valores válidos:
    • INITIAL - Llamada iniciada
    • ACCEPTED - Click2call aceptado
    • RINGING - Destino en timbre
    • CONNECTED - Llamada conectada
    • ON_HOLD - Llamada en espera
    • HANGUP - Llamada finalizada
  • connected_at (string) - Momento en el que la llamada fue conectada, formato: Y-m-d H:i:s zona horaria UTC . Valor por defecto null
  • start_time (string) - Momento en el que la llamada fue iniciada in Y-m-d H:i:s zona horaria UTC
  • context (string) - Contexto de la llamada dentro del entorno de la PBX
  • destination (string) - in para llamadas entrantes, out para llamadas salientes
  • duration (integer) - duración de la llamada en segundos
  • t_cause (string) - motivo de terminación de la llamada
  • src (string) - Número de origen de la llamada
  • src_id (integer) - Identificador numérico del origen de la llamada
  • src_name (string) - Nombre del origen de la llamada
  • src_hash (string) - Identificador único para cada llamada
  • dst (string) - Número de destino de la llamada
  • dst_id (integer) - Identificador numérico del destino de la llamada
  • dst_name (string) - Nombre del destino de la llamada

Los atributos del evento SMS Recibido son:

  • id (string) - Identificador único para el evento
  • event_time (string) - Fecha del evento A-m-d H:m:s en zona horaria UTC
  • event_name (string) - Nombre del tipo evento sms.received
  • customer_id (integer) - Identificado numérico de la cuenta de cliente donde se ha recibido el SMS
  • user_id (integer) - Identificador numérico del usuario que ha recibido el SMS (opcional, por defecto el valor es: null)
  • from_no (string) - Número de origen
  • to_no (string) - Número de destino, o número que ha recibido el SMS
  • text (string) - Conteido del SMS

Terminaciones REST API

Después de recibir un evento de Webhook como en el ejemplo a continuación (call_id = 139543232), uno puede recuperar los detalles de la llamada o aplicar acciones sobre la misma mediante nuestra REST API:

GET /v1.1/calls/139543232

Para transferir a la extensión 2002:

PATCH /v1.1/calls/139543232
{
  "dst": "2002"
}

Nota: /calls REST API muestra las llamadas activas. Una vez terminada y recibamos el call.hangup ya no estará disponible mediante la llamada /calls. Pero puede ser accedida mediante la llamada /cdrs (Call Details Report) y /monitors (Grabaciones de llamadas) filtrando por el atributo live_id con el valor call_id del evento Webhook, por ejemplo:

GET /v1.1/cdrs?filter=[{"property":"live_id","operator":"=","value":"139543232"}]

or

GET /v1.1/monitors?filter=[{"property":"live_id","operator":"=","value":"139543232"}]

Atributo Context - Queue

Tal como hemos visto anteriormente el atributo context puede tomar varios valores dependiendo del objeto que nos interese monitorizar. Si deseamos vigilar los eventos ocurridos en un usuario este atributo toma el valor LOCAL_USER pero si nos interesa vigilar los eventos que acontecen en una cola filtraremos por el contexto QUEUE.

Nota: para empezar a recibir estos eventos necesitaremos un Webhook de tipo Cambio de Estado de la llamada. De esta manera recibiremos todos los eventos generados en la centralita.

Estos eventos de contexto colo nos permiten entre otras cosas identificar cuando una llamada no ha sido respondida por ningún agente. Ya sea que se ha alcanzado el tiempo máximo de espera o simplemente se ha cansado de esperar y ha terminado la llamada. Para identificar una llamada no respondida dentro de una cola en lugar de inspeccionar el Context=User buscaremos un evento con context=Queue y event_name:call.missed.

Troubleshooting Webhooks

Desde el historial de llamadas de VoIPstudio CDR puede monitorizar todo el flujo de mensajes SIP en un modo gráfico por cada llamada. Ahora este panel también muestra las notificaciones de Webhooks emitidas hacia su URL, mostrando también el contenido. Esto puede resultar muy útil para solucionar problemas de implementación de notificaciones de Webhooks.

Solo necesita examinar el Informe detallado de llamadas y hacer clic en las llamadas correspondientes y verificar los eventos enviados y su contenido. Esto debe coincidir con la notificación que recibió en el servidor. Siga los pasos a continuación:

webhooks-troubleshooting.png

Figura 10.2 Troubleshooting Webhooks.
  1. Desde el panel de Administrador abrir la sección de Historial.
  2. Haga clic en CDR, se mostraran todas las llamadas que ha procesado VoIPstudio.
  3. Localice y haga click en la llamada para obtener los detalles.
  4. En la tabla de flujo de paquetes localice la columna correspondiente a su servidor.
  5. Deben aparecer las peticiones POST remitidas a su servidor. Haga clic para expandir.
  6. Los detalles del POST generado en el Webhook aparecerán.