ü 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)

Sección 'Status'

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

ü 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)]

18- Condición verificada de una lista de condiciones

21- Continúa el guion después de un desvío

ü    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 

Sección 'CustVars'

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

ü    VarName: el nombre de la variable 

ü   VarValue: el valor de la variable 

2- API INTERACTIVA

Desde un guion Infocaller se puede interactuar con tu aplicación web en cualquier momento de la llamada. Puedes enviar a tu aplicación los datos que puedas recoger en la llamada y también obtener datos de tu aplicación y usarlos en la llamada. Para ello debes definir ‘Queries”. Cada Query lleva asociada una URL. Las Queries se pueden configurar en la sección “API” de la pestaña de “inicio” de la configuración de infocaller.

Una vez definida la Query, la puedes usar en cualquier parte del guion.

Cada “Query” enviará por POST una estructura XML o JSON 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  

Tu aplicación web deberá responder a esta petición HTTP con una estructura XML o JSON 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  

2.1 Información enviada por POST

En cada llamada de Infocaller a la Query que hayas definido, se incluirá una variable llamada apiInfocaller. Según la configuración de tu cuenta, el contenido de la variable puede estar en formato XML o en formato JSON. .

Formato JSON

{ "ApiCall": {

    "UserID": {

      "LineNumber": "DATO",

      "LineNumberInt": "DATO",

      "CallSequence": "DATO",

      "Signature": "DATO"

    },

    "Infocaller": {

      "CallType": "DATO",

      "CallerNumber": "DATO",

      "InboundNumber": "DATO",

      "InboundNumberInt": "DATO",

      "OutboundNumber": "DATO",

      "idcall": "DATO",

      "QueryName": "DATO",

 },

    "CustVars": {

      "CustVar": [

        { "VarName": "DATO",

          "VarValue": "DATO"

        },

        { "VarName": "DATO",

          "VarValue": "DATO"

        }

      ]

    }

  }

}

Formato XML

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

   <UserID>

        <LineNumber></LineNumber>

        <LineNumberInt></LineNumberInt>

        <CallSequence></CallSequence>

        <Signature></Signature>

    </UserID>

    <Infocaller>

        <CallType></CallType>

        <CallerNumber></CallerNumber>

        <CallerNumberInt></CallerNumberInt> 

        <InboundNumber></InboundNumber>

        <InboundNumberInt></InboundNumberInt>

        <OutboundNumber></OutboundNumber>

        <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 puedas, opcionalmente, validar que la petición es auténtica y proviene de nuestros servidores.  La sección de autenticación incluye cuatro datos, que son:

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:

JSON

"UserID": {

      "LineNumber": "123456789",

      "LineNumberInt": "123456789",

      "CallSequence": "98565656",

      "Signature": "ae73e4b16a280726fb2e0e6bfb43902a"

    }

XML

<UserID>

    <LineNumber>123456789</LineNumber>

    <LineNumberInt>34123456789</LineNumberInt>

    <CallSequence>98565656</CallSequenc>

    <Signature>ae73e4b16a280726fb2e0e6bfb43902a</Signature>

</UserID>

Sección 'Infocaller'

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

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. 

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. 

Sección 'CustVars'

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

VarName: el nombre de la variable 

VarValue: el valor de la variable

2.2 Información de respuesta al POST

Tu aplicación web deberá responder con una estructura de datos (en JSON o XML, dependiendo de la configuración de tu cuenta). 

JSON

{ "ApiCall": {

    "Status": {

      "Result": "DATO",

      "ResultText": "DATO",

    },

    "CustVars": {

      "CustVar": [

        { "VarName": "DATO",

          "VarValue": "DATO"

        },

        { "VarName": "DATO",

          "VarValue": "DATO"

        }

      ]

    }

XML

<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>

Sección '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.

Sección 'CustVars'

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>.

ü 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 3 “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 [email protected] 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:

• &   → &
• <  → <
• >   → >
• " → "
• '  → '

Tienes más información en nuestro blog.