Infocaller permite que sus aplicaciones puedan registrar en tiempo real la actividad de las llamadas recibidas e interactuar con ellas intercambiando datos de la llamada o datos que el llamante ha proporcionado mediante marcación. La comunicación entre infocaller y sus aplicaciones se realiza mediante el protocolo HTTP o HTTPS. Hay dos tipos de funciones:  informativas e interactivas. Para cualquier consulta puede contactar con nuestro servicio de atención al cliente en la dirección soporte@infoe.es o llamar al teléfono 900 80 50 89.


1- Funciones informativas

 

En una línea infocaller se pueden configurar hasta 4 eventos informativos. En el instante en que se produce el correspondiente evento infocaller lanza una llamada a la URL definida por el usuario. Las URLs se pueden configurar en la sección “API” de la pestaña de “inicio” de la configuración de infocaller.

 

Los eventos que se pueden comunicar son:

 

INICIO

Se produce cuando una llamada ha sido contestada, pero antes de procesar cualquier acción.

 

DESVIO_CORRECTO

Se produce cuando la llamada desviada ha sido contestada

 

DESVIO_FALLIDO

Se produce cuando no se ha conseguido desviar la llamada

 

FIN

Se produce inmediatamente después de la finalización de la llamada.

 

Se puede optar por especificar URLs para todos los eventos o solo para algunos, dependiendo de la información que se quiera recopilar.

 

La URL para cada evento puede incluir variables con información de la llamada. Las variables disponibles para la URL son:

 

_NumLlamante ........... :  Número telefónico de origen de la llamada

_NumInfocaller............ :  Número principal del servicio infocaller

_NumLlamado ............ :  Número infocaller que ha recibido la llamada (diferente al número principal solo si tiene números adicionales)

_IdLlamada ................ :  ID numérico que identifica cada llamada

_UUID........................ :  Cadena alfanumérica única de 32 caracteres (8-4-4-4-12)

_NumDesvio ............... :  Número al que se ha desviado o intentado desviar la llamada

  (Solo disponible para los eventos DESVIO_CORRECTO y DESVIO_FALLIDO)

 

1.1- Ejemplos de URLS

 

INICIO

http://www.miadserver.com/report.aspx?eve=inicio&caller=[_NumLlamante]&
num=[_NumInfocaller]&id=[_IdLlamada]

 

DESVIO_CORRECTO

http://www.miadserver.com/report.aspx?eve=desvio&caller=[_NumLlamante]&

num=[_NumInfocaller]&id=[_IdLlamada]&desvio=[_NumDesvio]

 

1.2- XML enviado por POST

 

En los eventos informativos INICIO, DESVIO_CORRECTO Y DESVIO FALLIDO se envía por POST una estructura XML con la autenticación de la llamada (seccion <UserID>) datos principales (sección <Infocaller>) y las variables de usuario (sección <CustVars>). En el evento FIN se completan los datos de la llamada en la sección <Infocaller> y se añade la sección <Status> con el desglose de las acciones realizadas en la  llamada. Todo el XML estará dentro de la variable apiInfocaller, que deberá ser recogida por la URL desarrollada por el cliente.

 

Los elementos resaltados solo se entregarán en el evento FIN.

 

<ApiCall xmlns='http://tempuri.org/' encoding=” ISO-8559-1”>

  <UserID>

      <LineNumber></LineNumber>

      <LineNumberInt></LineNumberInt>

      <CallSequence></CallSequence>

      <Signature></Signature>

  </UserID>

  <Infocaller>

      <CallType></CallType>

      <CallerNumber></CallerNumber>

      <InboundNumber></InboundNumber>

      <InboundNumberInt></InboundNumberInt>

      <OutboundNumber></OutboundNumber>

      <OutboundNumberInt></OutboundNumberInt>

      <idcall></idcall>

      <CallSeconds></Callseconds>

      <StartDate></StartDate>

      <EndDate></EndDate>

      <CostRX></CostRX>

      <CostTX></CostTX>

  </Infocaller>

  <Status>

      <Events>

       <Event>

              <EventType></EventType>

              <EventDate></EventDate>

              <EventName></EventName>

              <EventAddInfo1></EventAddInfo1>

              <EventAddInfo2></EventAddInfo2>

              <EventAddInfo3></EventAddInfo3>

              <EventAddInfo4></EventAddInfo4>

              <EventAddInfo5></EventAddInfo5>

          </Event>

      </Events>

  </Status>

  <CustVars>

      <CustVar>

          <VarName></VarName>

          <VarValue></VarValue>

      </CustVar>

  </CustVars>

</ApiCall>

 

Autenticación

 

Los comandos de autenticación sirven para que el cliente, opcionalmente, pueda validar que la petición es auténtica y proviene de nuestros servidores.  La sección de autenticación incluye tres datos, que son:

 

    <UserID>

           <LineNumber>numero</LineNumber>

           <LineNumberInt>numero</LineNumberInt>

           <CallSequence>texto</CallSequence>

           <Signature>cadena_md5</Signature>

    </UserID>

 

 

ü LineNumber: número principal del servicio infocaller. 

ü LineNumberInt: número principal del servicio infocaller en formato internacional, incluyendo el código país

ü CallSequence: identificador único de la llamada generado por infocaller.

ü Signature: se trata de una medida de seguridad de para garantizar la autenticación. Para obtener la firma primero se concatenan tres valores: <LineNumber> + <CallSequence> + <contraseña telefónica>. La  “contraseña telefónica” la puede ver o cambiar en la configuración del servicio infocaller en nuestra página web (Pestaña de Inicio de la configuración de su línea infocaller). Al texto obtenido de la concatenación de estos tres valores se le debe aplicar un algoritmo denominado MD5 (explicado en el Apéndice 1 de este documento). El resultado es el que se debe indicar como “Signature”.


Un ejemplo de autenticación:

 

ü Si el LineNumber infocaller fuese: 123456789

ü Si la CallSequence de esta llamada fuera: 98565656

ü Si la “contraseña telefónica” del servicio fuese: 3956

 

Aplicando el algoritmo MD5 a 123456789985656563956 se obtiene el resultado ae73e4b16a280726fb2e0e6bfb43902a

 

Y los comandos de autenticación serían:

 

<UserID>

  <LineNumber>123456789</LineNumber>

  <LineNumberInt>34123456789</LineNumberInt>

  <CallSequence>98565656</CallSequence>

  <Signature>ae73e4b16a280726fb2e0e6bfb43902a</Signature>

</UserID>

 

 

Infocaller

 

En esta sección se incluyen datos de la llamada:

 

    <Infocaller>

        <CallType></CallType>

        <CallerNumber></CallerNumber>

        <InboundNumber></InboundNumber>

        <InboundNumberInt></InboundNumberInt>

        <OutboundNumber></OutboundNumber>

        <OutboundNumberInt></OutboundNumberInt>

        <idcall></idcall>

        <CallSeconds></Callseconds>

        <StartDate></StartDate>

        <EndDate></EndDate>

        <CostRX></CostRX>

        <CostTX></CostTX>

    </Infocaller>

  

ü CallType: “R” si es una llamada Recibida o “E” si es una llamada emitida

ü CallerNumber: Para llamadas recibidas es el número de teléfono del llamante. Si está oculto tendrá un valor de “X”. En llamadas emitidas, es el número Infocaller que origina la llamada. En este caso, será el mismo que LineNumber salvo que el servicio infocaller tenga números adicionales y la llamada haya sido  emitida por uno de estos números

ü CallerNumberInt: En llamadas emitidas, es el número Infocaller que origina la llamada. En este caso, será el mismo que LineNumberInt salvo que el servicio infocaller tenga números adicionales y la llamada haya sido  emitida por uno de estos números. En formato internacional, incluyendo el código país.

ü InboundNumber: es el número infocaller que ha recibido la llamada. Será el mismo que LineNumber salvo que el servicio infocaller tenga números adicionales y la llamada haya sido atendida por uno de estos números.

ü InboundNumberInt: como InboundNumber pero en formato internacional, incluyendo el código país.

ü OutboundNumber: es el número telefónico de destino de una llamada emitida.

ü OutboundNumberInt: como OutboundNuber pero en formato internacional, incluyendo el código país.


ü idcall: es el identificador único de la petición de una llamada emitida (ver API de emisión de llamadas).

ü CallSeconds: Duración total en segundos de la llamada recibida o emitida (solo evento FIN).

ü StartDate: Fecha y hora del inicio de la llamada aaaa-mm-ddThh:mm:ss (solo evento FIN).

ü EndDate: Fecha y hora del fin de la llamada aaaa-mm-ddThh:mm:ss (solo evento FIN).

ü CostRX: Coste sin impuestos de la llamada recibida (solo evento FIN)

ü CostTX: Coste sin impuestos de la llamada emitida (solo evento FIN)

 

 Acciones de la llamada (solo evento FIN):

 

En esta sección se incluye el desglose de todas las acciones que se han producido en la llamada

 

<Status>

  <Events>

      <Event>

          <EventType></EventType>

          <EventDate></EventDate>

          <EventName></EventName>

          <EventAddInfo1></EventAddInfo1>

          <EventAddInfo2></EventAddInfo2>

          <EventAddInfo3></EventAddInfo3>

          <EventAddInfo4></EventAddInfo4>

          <EventAddInfo5></EventAddInfo5>

      </Event>

  </Events>

</Status>

 

ü EventType: es un código numérico que indica el tipo de acción:

1- Mensaje

2- Llamada

    El número de destino se indica en EventName

    [EventAddInfo3: Duración en segundos]

    [EventAddInfo4: Importe sin impuestos]

3- Contestador

4- Entrada de datos por teclado

    [EventAddInfo1: Datos recogidos]

5- Petición de datos por voz

6- Menú numérico

    [EventAddInfo1: Opción marcada]

7- FinLlamada

    [EventAddInfo4: Coste sin imp. aviso opcional SMS]

8- Ir a

11- Envío de email

12- Envío de SMS

    [EventAddInfo4: Importe]

13- Guion

14- Inicio llamada y reglas aplicadas

15- Transferencia de llamada

16- Cola de espera

17- Query API

    [EventAddInfo1: Resultado (0/1)]

 

ü EventDate: Fecha y hora de la acción (aaaa-mm-ddThh:mm:ss)

ü EventName: Descripción de la acción

ü EventAddinfo1 a 5: Datos adicionales de cada acción, según se indica en EventType

 

 

Variables del Usuario

 

En esta sección se incluyen las variables de usuario que se hayan definido en la llamada hasta el momento:

 

    <CustVars>

    <CustVar>

            <VarName></VarName>

            <VarValue></VarValue>

    </CustVar>

    <CustVar>

            <VarName></VarName>

            <VarValue></VarValue>

    </CustVar>

  </CustVars>


2- Funciones interactivas

 

En el guion de una línea infocaller se pueden definir acciones de tipo “Query”. Esta acción lanza una llamada HTTP a la URL correspondiente definida por el usuario y permite intercambiar datos entre Infocaller y la aplicación web del cliente.

 

En la definición de cada acción de tipo “Query”, el usuario define una URL, un nombre del Query y un tiempo máximo de espera. El nombre sirve para diferenciar las peticiones cuando se utilice una sola URL para peticiones distintas.

 

La acción “Query” enviará por POST una estructura XML con:

- datos de identificación y autenticación de la línea

- variables con los datos de la llamada

- variables de usuario definidas en otras acciones de infocaller previas al Query

 

La aplicación del cliente deberá responder a esta petición HTTP con una estructura XML donde podrá enumerar variables de usuario que modificarán las existentes en la llamada (si las hubiere con el mismo nombre) o se crearán como variables nuevas en la llamada. Si no se obtiene la respuesta adecuada o si expira el tiempo de espera, se ejecutará la acción que el usuario indicó para estos casos en la definición del Query.

 

Las acciones de infocaller que pueden definir nuevas variables de usuario son:

 

- OBTENER DATO POR MARCACIÓN, dentro de un guion 

- La propia QUERY 

 

Las acciones de infocaller que pueden usar variables de usuario son:

 

- LLAMADA: el destino de una llamada puede especificarse mediante una variable de usuario

- LISTA DE CONDICIONES: dentro del guion, permite definir acciones en función a la evaluación de variables de la llamada

- La propia QUERY

 

 

En la siguiente sección encontrará ejemplos de uso de “Query”.


2.1 Estructura del XML enviado por POST

 

El XML tendrá la siguiente estructura, dividida en una primera sección de identificación (<UserID>) y otra sección con datos básicos de la llamada (<Infocaller>) junto con el nombre de la query. Por último encontraremos el área dedicada a las variables personales del cliente. Todo el XML estará dentro de la variable apiInfocaller, que deberá ser recogida por la URL desarrollada por el cliente.

 

<ApiCall xmlns='http://tempuri.org/' encoding=” ISO-8559-1”>

   <UserID>

        <LineNumber></LineNumber>

        <LineNumberInt></LineNumberInt>

        <CallSequence></CallSequence>

        <Signature></Signature>

    </UserID>

    <Infocaller>

        <CallType></CallType>

        <CallerNumber></CallerNumber>

        <InboundNumber></InboundNumber>

        <InboundNumberInt></InboundNumberInt>

        <OutboundNumberInt></OutboundNumberInt>

        <idcall></idcall>

        <QueryName></QueryName>

    </Infocaller>

    <CustVars>

        <CustVar>

            <VarName></VarName>

            <VarValue></VarValue>

           </CustVar>

      <CustVar>

            <VarName></VarName>

            <VarValue></VarValue>

           </CustVar>

    </CustVars>

</ApiCall>

 

Autenticación

 

Los comandos de autenticación sirven para que el cliente, opcionalmente, pueda validar que la petición es auténtica y proviene de nuestros servidores.  La sección de autenticación incluye tres datos, que son:

 

  <UserID>

      <LineNumber>numero</LineNumber>

      <LineNumberInt>numero</LineNumberInt>

      <CallSequence>texto</CallSequence>

      <Signature>cadena_md5</Signature>

  </UserID>

 

 

LineNumber: número principal del servicio infocaller

LineNumberInt: número principal del servicio infocaller pero en formato internacional, incluyendo el código país

CallSequence: identificador único de la llamada generado por infocaller.

Signature: se trata de una medida de seguridad de para garantizar la autenticación. Para obtener la firma primero se concatenan tres valores: <LineNumber> + <CallSequence> + <contraseña telefónica>. La  “contraseña telefónica” la puede ver o cambiar en la configuración del servicio infocaller en nuestra página web (Pestaña de Inicio de la configuración de su línea infocaller). Al texto obtenido de la concatenación de estos tres valores se le debe aplicar un algoritmo denominado MD5 (explicado en el Apéndice 1 de este documento). El resultado es el que se debe indicar como “Signature”.


Un ejemplo de autenticación:

 

- Si el LineNumber infocaller fuese: 123456789

- Si la CallSequence de esta llamada fuera: 98565656

- Si la “contraseña telefónica” del servicio fuese: 3956

 

Aplicando el algoritmo MD5 a 123456789985656563956 se obtiene el resultado ae73e4b16a280726fb2e0e6bfb43902a

 

Y los comandos de autenticación serían:

 

<UserID>

    <LineNumber>123456789</LineNumber>

    <LineNumberInt>34123456789</LineNumberInt>

    <CallSequence>98565656</CallSequenc>

    <Signature>ae73e4b16a280726fb2e0e6bfb43902a</Signature>

</UserID>

 

 

Infocaller

 

En esta sección se incluyen datos de la llamada:

 

        <Infocaller>

            <CallType></CallType>

            <CallerNumber></CallerNumber>

            <InboundNumber></InboundNumber>

            <OutboundNumber></OutboundNumber>

            <idcall></idcall>

            <QueryName></QueryName>

        </Infocaller>

 

CallType: “R” si es una llamada Recibida o “E” si es una llamada emitida

CallerNumber: Para llamadas recibidas es el número de teléfono del llamante. Si está oculto tendrá un valor de “X”. En llamadas emitidas, es el número

Infocaller que origina la llamada. En este caso, será el mismo que LineNumber salvo que el servicio infocaller tenga números adicionales y la llamada

haya sido  emitida por uno de estos números. 

CallerNumberInt: en llamadas emitidas es como CallerNumber pero en formato internacional, incluyendo el código país

InboundNumber: es el número infocaller que ha recibido la llamada. Será el mismo que LineNumber salvo que el servicio infocaller tenga números

adicionales y la llamada haya sido atendida por uno de estos números.

InboundNumberInt: como InboundNumber pero en formato internacional, incluyendo el código país

OutboundNumber: es el número telefónico de destino de una llamada emitida.

OutboundNumberInt: es el número telefónico de destino de una llamada emitida en formato internacional, incluyendo el código país

idcall: es el identificador único de la petición de una llamada emitida (ver API de emisión de llamadas).

QueryName: es el nombre del Query definido por el usuario.

 

 

Variables del Usuario

 

En esta sección se incluyen las variables de usuario que se hayan definido en la llamada hasta el momento del Query:

 

   <CustVars>

    <CustVar>

            <VarName></VarName>

            <VarValue></VarValue>

    </CustVar>

    <CustVar>

            <VarName></VarName>

            <VarValue></VarValue>

    </CustVar>

  </CustVars>

 

2.2 Estructura del XML de respuesta

 

La aplicación del cliente deberá responder con una estructura XML. Los valores de las variables deben cumplir con los requisitos de los apéndices 2 y 3.

 

<ApiCall xmlns='http://tempuri.org/' encoding=” ISO-8559-1>

  <Status>

        <Result></Result>

        <ResultText></ResultText>

  </Status>

  <CustVars>

      <CustVar>

          <VarName>Var1</VarName>

          <VarValue>Correcto</VarValue>

      </CustVar>

      <CustVar>

          <VarName>VarLlamar</VarName>

          <VarValue>900805089</VarValue>

      </CustVar>

  </CustVars>

</ApiCall>

 

Status

 

En esta sección se incluyen dos variables:

 

Result: el valor debe ser “0” (cero) si se ha procesado correctamente la petición u otro valor definido por el usuario en caso de error. Todo valor diferente de cero producirá la ejecución de la acción que el usuario indicó para estos casos en la definición del Query

 

ResultText: es una descripción definida por el usuario del resultado reportado.

 

 

 

 

Variables de usuario

 

En esta sección se pueden incluir las variables que se quiere poner a disposición de la llamada. En caso que no sea necesario retornar ningún valor se devolverá una sección vacía: <CustVars></CustVars>.

 

  <CustVars>

      <CustVar>

          <VarName>Var1</VarName>

          <VarValue>Correcto</VarValue>

      </CustVar>

      <CustVar>

          <VarName>VarLlamar</VarName>

          <VarValue>900805089</VarValue>

      </CustVar>

  </CustVars>


 

ü VarName: el nombre de la variable (condiciones del Apéndice 2) 

ü VarValue: el valor de la variable (condiciones del Apéndice 3)

 

 

2.3 Ejemplos de uso de Query

 

Ejemplo 1: Información automática del estado de un pedido.

 

Guión:

 

- MENSAJE 1: Bienvenida

- OBTENER DATO POR MARCACIÓN

o “Por favor marque su código de pedido”

o Guardar valor en variable “NUMPEDIDO”

- QUERY

o URL: http://www.miweb.es/infocaller.htm

o Nombre: “ESTADO PEDIDO”

o Acción en Error:

IR A – Mensaje 5

- LISTA CONDICIONES

o PEDIDO=0

MENSAJE 2 “No se ha encontrado un pedido con el número indicado. Muchas gracias por su llamada”

FIN DE LLAMADA

o PEDIDO=1

MENSAJE “Su pedido está siendo preparado. Muchas gracias por su llamada”

FIN DE LLAMADA

o PEDIDO=2

MENSAJE 4 “Su pedido ha sido enviado. Muchas gracias por su llamada”

FIN DE LLAMADA

 

o RESTO DE CASOS

MENSAJE “Hay una incidencia en su pedido. Un momento por favor, le pasamos con nuestro departamento de atención al cliente.”

LLAMADA 9XXXXXXX

- MENSAJE 5 “No ha sido posible obtener la información solicitada. Un momento por favor, le pasamos con nuestro departamento de atención al cliente”

- LLAMADA 9XXXXXXX

 

El XML que se enviaría sería similar a:

 

<ApiCall xmlns='http://tempuri.org/' encoding=” ISO-8559-1”>

  <UserID>

      <LineNumber>123456789</LineNumber>

      <CallSequence>98565656</CallSequence>

      <Signature>ae73e4b16a280726fb2e0e6bfb43902a</Signature>

  </UserID>

  <Infocaller>

      <CallerNumber>911888920</CallerNumber>

      <InboundNumber>900805089</InboundNumber>

      <InboundNumberInt>34900805089</InboundNumberInt>

      <QueryName>ESTADO PEDIDO</QueryName>

  </Infocaller>

  <CustVars>

      <CustVar>

                <VarName>NUMPEDIDO</VarName>

                <VarValue>123456789</VarValue>

      </CustVar>

  </CustVars>

</ApiCall>

 

Y la respuesta:

 

<ApiCall xmlns='http://tempuri.org/' encoding=” ISO-8559-1>

  <Status>

     <Result>0</Result>

     <ResultText>Petición correcta</ResultText>

  </Status>

  <CustVars>

      <CustVar>

        <VarName>PEDIDO</VarName>

             <VarValue>2</VarValue>

      </CustVar>

  </CustVars>

</ApiCall>

 

Ejemplo 2: Desvío a extensión

 

En este ejemplo, el usuario marca una extensión, se consulta via query el número de teléfono que le corresponde y se desvía la llamada al TELEFONO que se obtiene como respuesta.

 

Guión:

- OBTENER DATO POR MARCACIÓN

o “Por favor marque el número de extensión a la que quiere llamar”

o Guardar valor en variable “EXTENSION”

 

 

- QUERY

o URL: http://www.miweb.es/infocaller.htm

o Nombre: “NUMERO EXTENSION”

o Acción en Error:

§ IR A – Mensaje 2

- LISTA DE CONDICIONES

o TELEFONO=0

§ MENSAJE 1 “La extensión no es válida, por favor inténtelo nuevamente”

§ IR A – Obtener dato por marcación

o RESTO DE CASOS

§ LLAMADA “TELEFONO”

- MENSAJE 2 “La extensión no está disponible, le pasamos con un operador.”

- LLAMADA 9XXXXXXX


Apéndice 1– Algoritmo MD5

 

El algoritmo MD5 convierte un texto en una reducción criptográfica mediante unas fórmulas matemáticas.

 

Por ejemplo, el texto "Esto sí es una prueba de MD5” se convierte en el “hash” “e99008846853ff3b725c27315e469fbc” de forma unívoca. Pero no es posible obtener la frase original a partir del “hash”. Esto lo hace especialmente útil para que sirva como sistema de autenticación cuando no se conoce el texto original. Se puede obtener una explicación más amplia en http://es.wikipedia.org/wiki/MD5 .

 

El MD5 es utilizado para que aumentar la seguridad en el proceso de autenticación del cliente.

 

A los efectos de esta aplicación se debe obtener una función de conversión MD5 en el lenguaje de la aplicación o página web desde la que se realizará el envío de mensajes. Existen muy diversas aplicaciones gratuitas que se pueden localizar utilizando en un buscador de internet frases de búsqueda como “MD5 ASP”, “MD5 PHP”, “MD5 Java”, “MD5 Visual Basic”, etc., dependiendo del lenguaje que se utilizará.  Es responsabilidad del cliente verificar la calidad y fiabilidad de la función de conversión MD5 que utilizará en su aplicación.

 

Si tuviera cualquier dificultad o limitación en el uso del MD5, por favor póngase en contacto con nuestro departamento de atención al cliente en la dirección soporte@infoe.es o en el teléfono 900 80 50 89.


 


Apéndice 2 – Requisitos para nombres de variables

 

Debe componerse de las letras A a Z o dígitos del 0 al 9, sin espacios u otros caracteres. Y una longitud máxima de 15 posiciones.

 


Apéndice 3 – Caracteres permitidos en valores de variables

 

Los caracteres imprimibles ASCII y los de ISO-8559-1, excepto  >, <, &, ‘ y “. Estos últimos deberán incluirse usando:

  • &amp;   → &
  • &lt;  → <
  • &gt;   → >
  • &quot; → "
  • &apos; → '