Action URL y Action URI… porque la potencia sin control no sirve nada

¡Y si encima se trata de control remoto mejor! Por esto mismo los desarrolladores de Yealink han implementando en todos sus terminales las herramientas suficientes para que podamos interactuar con ellos como si estuviéramos delante. Unas funcionalidades que al menos a nosotros en Irontec nos parecen geniales. Por eso mismo vamos a ver y explicar de forma sencilla cómo sacarles el máximo partido.

Antes de comenzar, tenemos que saber que Yealink presenta 2 metodologías diferentes para poder interactuar con sus terminales. Estas son “Action URI” y “Action URL” y, tal y como vamos a comprobar a continuación, son funcionalmente opuestas.

¡Comencemos!

 

Action URL

Este método permite al terminal enviarnos información, algo que es posible porque simula una petición GET mediante http o https desde un servidor centralizado cuando el terminal realiza un acción específica, como por ejemplo llamar, activar la funcionalidad de DND (Do Not Disturb), etc…

actionurl

La sintaxis estándar para configurar este tipo de peticiones es:

http(s)://IP_DEL_SERVIDOR/help.xml?

Disponemos de un gran listado de eventos predefinidos con los que podremos trabajar desde el principio.

EventoDescripción
Setup CompletedCuando el terminal completa el arranque.
RegisteredCuando el terminal completa de forma satisfactoria el registro de una cuenta.
UnregisteredCuando el terminal pierde el registro una cuenta que tenia previamente registrada.
Register FailedCuando el terminal falla durante el registro de una cuenta.
Off HookCuando el teléfono esta descolgado.
On HookCuando el teléfono esta colgado.
Incoming CallCuando el terminal recibe una llamada.
Outgoing CallCuando el terminal realiza una llamada.
EstablishedCuando el terminal establece una llamada.
TerminatedCuando el terminal termina una llamada.
Open DNDCuando el terminal activa el DND.
Close DNDCuando el terminal desactiva el DND.
Open Always ForwardCuando el terminal activa el “Desvío siempre”.
Close Always ForwardCuando el terminal desactiva el “Desvío siempre”.
Open Busy ForwardCuando el terminal activa el “Desvío si ocupado”.
Close Busy ForwardCuando el terminal desactiva el “Desvío si ocupado”.
Open NoAnswer ForwardCuando el terminal activa el “Desvío si no contesta”.
Close NoAnswer ForwardCuando el terminal desactiva el “Desvío si no contesta”.
Transfer CallCuando el terminal realiza una transferencia.
Blind TransferCuando el terminal realiza una transferencia ciega o directa.
Attended TransferCuando el terminal realiza una transferencia atendida o semi atendida.
HoldCuando el terminal retiene una llamada.
UnHoldCuando el terminal recupera una llamada previamente retenida.
HeldCuando la llamada del teléfono esta retenida.
UnHeldCuando la llamada del teléfono es recuperada.
MuteCuando el terminal silencie o mutee una llamada.
UnMuteCuando el terminal de-silencie una llamada o haga un-mute.
Missed CallCuando el terminal tenga una llamada perdida.
IP ChangedCuando la IP del terminal cambie.
Idle To BusyCuando el estado del terminal pase de reposo a ocupado.
Busy To IdleCuando el estado del terminal pase de ocupado a reposo.
Reject Incoming CallCuando el terminal rechace una llamada entrante.
Answer New-In CallCuando el terminal conteste una nueva llamada.
Transfer FailedCuando el terminal falle a la hora de transferir una llamada.
Transfer FinishedCuando el terminal termine de realizar una transferencia.
Forward Incoming CallCuando el terminal desvíe una llamada entrante.
Autop FinishCuando el terminal termine de provisionarse mediante el método de encendido.
Open Call WaitingCuando el terminal habilite la “llamada en espera”.
Close Call WaitingCuando el terminal deshabilite la “llamada en espera”.
HeadsetCuando se presione en el terminal el botón de cascos o headset.
HandfreeCuando se presione en el terminal el botón de altavoz.
Cancel Call OutCuando el teléfono cancela una llamada saliente habiendo obtenido tono.
Remote BusyCuando una llamada saliente es rechazada.
Call Remote CanceledCuando el se cancela una llamada entrante que ha obtenido tono.

 

También contamos con una gran cantidad de variables de entorno que nos puede hacer llegar información referente al terminal en el que ha ocurrido la acción, como por ejemplo la IP del terminal, la MAC del terminal, o incluso, en caso de tener diferentes cuentas registradas, en cuál de ellas ha ocurrido la acción.

La sintaxis estándar de este tipo de peticiones con variables es:

http(s)://IP_DEL_SERVIDOR/help.xml?NOMBRE_DE_VARIABLE=$nombre_de_variable

Al igual que con los eventos, disponemos de muchas variables diferentes que podemos utilizar.

VariableDescripción
$active_userFragmento de la parte usuario de la cabecera URI SIP de la cuenta activa cuando el terminal IP realiza, contesta o establece una llamada.
$active_hostFragmento de la parte usuario de la cabecera URI SIP de la cuenta activa cuando el terminal IP realiza, contesta o establece una llamada.
$localURI SIP del llamante cuando el terminal realiza una llamada.
URI SIP del llamante cuando el terminal recibe una llamada.
$remoteURI SIP del llamante cuando el terminal realiza una llamada.
URI SIP del llamante cuando el terminal recibe una llamada.
$display_localMuestra el nombre del llamante cuando el terminal recibe una llamada.
$display_remoteMuestra el nombre del llamante cuando el terminal realiza una llamada.
Muestra el nombre del llamante cuando el terminal recibe una llamada.
$call_idCALL-ID de la llamada activa.
$callerIDEl nombre a mostrar del llamante cuando el teléfono recibe una llamada entrante.
$calledNumberMuestra el numero de llamante cuando el terminal realiza una llamada.

¿Cómo se configura en un terminal?

Podemos hacerlo de dos formas diferentes: ya sea haciéndolo llegar como parámetro en el fichero de provisión o directamente accediendo a la página web del terminal, hasta la sección específica.

 

Mediante los ficheros de provisión

Debemos añadir al fichero <y0000000000xx>.cfg las líneas de cada uno de los eventos que queramos que nos envíe información, seguido de la URL y variable, en caso de querer obtenerla.

action_url.incoming_call = http://192.168.1.100/help.xml?IP=$ip
...
..
.

 

Mediante la interfaz web

Para ello tendremos que abrir un navegador e introducir la IP del terminal en el que queremos configurar la Action URL y logearnos.

login_yealink

Ahora tendremos que ir al menú Features >> Action URL

secciones

Aquí veremos los diferentes eventos que podemos llegar a configurar, y sólo nos quedará introducir la URL en la casilla correspondiente al evento.

 

¿Y ahora qué?

Una vez configurado, tendremos la posibilidad de obtener información en tiempo real de los diferentes eventos que tienen lugar en todos los terminales en los que hayamos configurado Action URL. Asimismo, obtendremos información relativa al terminal en el que ha ocurrido, gracias a las diferentes variables.

Pero… ¿Y si quisiéramos poder interactuar con el terminal en función de los eventos que tienen lugar y que ahora recibimos?

¡Vamos con ello!

 

Action URI

Tal y como se ha apuntado al comienzo del post, este método, en vez de escuchar eventos, nos permite enviar instrucciones al terminal con peticiones GET mediante http o https, con el fin de que realice diferente operaciones. Como hemos señalado, se puede llamar, contestar una llamada, activar el DND, reiniciarlo y un larguísimo etc…

 

¿Cómo funciona exactamente?

Tendremos que enviar una petición http mediante un navegador o cualquier aplicación de terminal de tipo curl o wget.

La sintaxis de la petición http(s) es:

http(s)://IP_del_terminal/servlet?valor=variable

Disponemos de muchas acciones predefinidas diferentes listas para usarse.

ValorDescripción
OKPulsar el botón Ok.
ENTERPulsar el botón software Enter de la pantalla.
SPEAKERPulsar el botón altavoz del terminal.
F_TRANSFERTransfiere una llamada.
VOLUME_UPAumenta el volumen.
VOLUME_DOWNBaja el volumen.
MUTESilencia la llamada en curso.
F_HOLD / HOLDRetiene la llamada activa
F_CONFERENCEPulsar el botón software Conf de la pantalla.
Cancel / CANCELCancela opciones, rechaza una llamada o termine una llamada en curso.
XCancela acciones, rechazada una llamada o silencia o desilencia una llamada.
0-9 / * / POUNDPulsa el botón correspondiente, del 0 -9, asterisco o almohadilla.
L1-LXPulsa el botón de linea correspondiente.
F1-F4Pulsa los botón equivalentes ubicados debajo de la pantalla.
MSGPulsa el botón de mensaje.
HEADSETPulsa el botón de cascos.
RDPulsa el botón de rellamada.
UP / DOWN / LEFT / RIGHTPulsa el botón de navegación correspondiente de la cruceta.
RebootReinicia el terminal.
AutoPRealiza una petición al sistema de provisioning.
DNDOnActiva la funcionalidad de DND (no molestar).
DNDOffDesactiva la funcionalidad de DND (no molestar).
number=xxx&outgoing_uri=yRealiza una llamada el número ‘XXX’ utilizando el SIP URI ‘Y’
OFFHOOKContesta la llamada en el auricular.
ONHOOKCuelga la llamada.
ANSWER / ASW / AswContesta una llamada.
ResetReinicia el terminal.
ATrans=xxxRealiza una transferencia atendida o semi atendida al numero ‘XXX’
BTrans=xxxRealiza una transferencia ciega a ‘XXX’
CALLEND / CallEndFinaliza una llamada.
phonecfg=get[&accounts=x][&dnd=x][&fw=x]Obtiene información de la versión de firmware, registro del terminal, estado de la funcionalidad de DND o desvíos activos.
CallWaitingOnActiva la funcionalidad de llamada en espera.
CallWaitingOffDesactiva la funcionalidad de llamada en espera.
AlwaysFwdOn/BusyFwdOn/NoAnswF
wdOn=xxx=n
Activa la funcionalidad de desvío en caso de ocupado/no disponible/no contesta para el número ‘XXX’.
AlwaysFwdOff/BusyFwdOff/NoAnswF
wdOff=xxx=n
Desactiva la funcionalidad de desvío en caso de ocupado/no disponible/no contesta para el número ‘XXX’.
ASW / CANCEL / HOLD / UNHOLD:xxxContestar/terminar/retener/recuperar la llamada con callid ‘XXX’

Una vez lanzada la petición, utilizando un navegador por ejemplo, el terminal ejecutará la acción y nos responderá con un mensaje SIP 200 OK en caso éxito.

actionurl_1

Comentar que también es posible enviar ordenes al terminal mediante mensajes de SIP NOTIFY. Para ello, tendremos que añadir en la cabecera del mensaje:

Event: ACTION-URI

En el cuerpo, una sección con los valores y variables.

Key=OK

Quedando de la siguiente forma:

NOTIFY sip:[email protected]:5061 SIP/2.0
Via: SIP/2.0/UDP 192.168.1.110:5062;branch=x728dhT8uyshe736R
From: <sip:[email protected]>;tag=2435241536
To: "1001" <sip:[email protected]>;tag=490600926
Call-ID: [email protected]
CSeq: 4 NOTIFY
Contact: <sip:[email protected]:5062>
Max-Forwards: 70
User-Agent: Yealink SIP-T23G
Event: ACTION-URI
Content-Type: message/sipfrag
Content-Length: 6
Message Body
key=OK

 

¿Cómo se configura un terminal para poder utilizar Action URI?

De la misma forma que con el método Action URL, en este caso también podremos hacerlo de 2 maneras. Por un lado, haciéndolo llegar como parámetro en el fichero de provisión o directamente accediendo a la página web del terminal, hasta la sección específica.

 

Mediante los ficheros de provisión

Debemos añadir al fichero <y0000000000xx>.cfg las líneas de cada uno de los eventos que queramos que nos envíe información, seguido de la URL y variable, en caso de querer obtenerla.

features.action_uri.enable=1
features.show_action_uri_option=1
features.action_uri_limit_ip=192.168.1.100

 

Mediante la interfaz web

Para ello tendremos que abrir un navegador e introducir la IP del terminal en el que queremos configurar la Action URL y logearnos.

login_yealink

Ahora tendremos que ir al menú Features >> Remote Control y rellenar los diferentes campos.

 

IMPORTANTE

En caso de que utilicemos el método de configuración web, tendremos que pulsar el botón OK en el propio terminal la primera vez que mandemos una petición http.  Es decir, físicamente, ya que, al menos con el firmware actual (44.81.0.XX), no se permite añadir o configurar el valor de ‘features.show_action_uri_option’ en la propia web.

 

¡Ya tenemos el control de nuestros terminales! Sabemos escucharlos y sabemos comunicarnos con ellos. Ahora tú decides cómo sacarles el mejor de los partidos.

¿Quizás una aplicación de escritorio/web/terminal para automatizar todo esto? Atentos, porque lo veremos en el siguiente post;)

¡Hasta la próxima!



¿Te gusta este post? Es solo un ejemplo de cómo podemos ayudar a tu empresa...
Sobre Héctor Prieto Pérez

Miembro del Departamento de soporte, apasionado del Software libre y su filosofia... y en mis ratos libres estrella del rock frustrada Xd

Queremos tu opinión :)