Infocaller allows your applications to log real-time data from your calls an to interact with them exchanging call data which the user might have entered using the dialpad. Communication between infocaller and its applications is done through the HTTP or HTTPS protocol. 

There are two types of functions: informative and interactive. For any questions you can contact our customer service at help@infocaller.com.



1- INFORMATIVE API


 In an Infocaller line you can configure up to 4 informative events. At the moment the corresponding event occurs, Infocaller launches a call to the URL that you have specified for each one. The URLs can be configured in the "API" section of the "home" tab of the infocaller configuration. You can choose to specify URLs for all events or only for some, depending on the information you want to collect. You can also choose the XML or JSON format.


  The events that can be communicated are:


  

INICIO 

It occurs when a call has been answered, but before processing any action 

  

DESVIO_CORRECTO 

Se produce cuando la llamada ha sido contestada por una extensión 

  

DESVIO_FALLIDO 

It occurs when the call has been answered by an extension 

  

FIN 

It occurs immediately after the end of the call 

  


The URL for each event can include variables with call information. The variables available for the URL are: 

  

_NumLlamante ........... :  Telephone number of call origin 

_NumInfocaller............ :  Main number of the infocaller service

_NumLlamado ............ :  Infocaller number that received the call (different from the main number only if you have additional numbers)

_IdLlamada ................ :  Numerical ID that identifies each call 

_UUID........................ :  Alphanumeric string of 32 characters (8-4-4-4-12). Unique per call. 

_NumDesvio ............... : Number to which the call has been diverted or attempted to divert

       (Only available for the DEVIO_CORRECTO and DESVIO_FALLIDO events)

 

1.1- URLS Examples

 

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- Information sent by POST

 

In the informative events START, CORRECT_DIVERY AND FAILED DEVICE, a XML or JSON structure with call authentication (section <UserID>) main data (section <Infocaller>) and variables are sent by POST, within a variable called apiInfocaller of user (section <CustVars>). In the FIN event, the call data is completed in the <Infocaller> section and the <Status> section is added with the breakdown of the actions performed on the call.

  

JSON Format

 

{ "ApiCall": {

    "UserID": { 

      "LineNumber": "DATO", 

      "LineNumberInt": "DATO", 

      "CallSequence": "DATO", 

      "Signature": "DATO" 

    }, 

    "Infocaller": { 

      "CallType": "DATO", 

      "CallerNumber": "DATO", 

      "InboundNumber": "DATO", 

      "InboundNumberInt": "DATO", 

      "OutboundNumber": "DATO", 

      "OutboundNumberInt": "DATO", 

      "idcall": "DATO", 

      "CallSeconds": "DATO", 

      "StartDate": "DATO", 

      "EndDate": "DATO", 

      "CostRX": 0.000000, 

      "CostTX": 0.000000 

    }, 

    "Status": { 

      "Events": { 

        "Event": [ 

          { "EventType": "DATO", 

            "EventDate": "DATO", 

            "EventName": "DATO", 

            "EventAddInfo1": "DATO", 

            "EventAddInfo2": "DATO", 

            "EventAddInfo3": "DATO", 

            "EventAddInfo4": "DATO", 

            "EventAddInfo5": "DATO" 

          }, 

          { "EventType": "DATO", 

            "EventDate": "DATO", 

            "EventName": "DATO", 

            "EventAddInfo1": "DATO", 

            "EventAddInfo2": "DATO", 

            "EventAddInfo3": "DATO", 

            "EventAddInfo4": "DATO", 

            "EventAddInfo5": "DATO" 

          } 

        ] 

      } 

    }, 

    "CustVars": { 

      "CustVar": [ 

        { "VarName": "DATO", 

          "VarValue": "DATO" 

        }, 

        { "VarName": "DATO", 

          "VarValue": "DATO" 

        } 

      ] 

    } 

  } 

} 




XML Format

 

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

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

 


'Authentication' section

 

Authentication commands allow the client, optionally, to validate that the request is authentic and comes from our servers. The authentication section includes three data, which are:


  • LineNumber: main number of the infocaller service.
  • LineNumberInt: main number of the infocaller service in international format, including the country code
  • CallSequence: unique identifier of the call generated by infocaller.
  • Signature: This is a security measure to ensure authentication. To obtain the signature, three values are concatenated first: <LineNumber> + <CallSequence> + <telephone password>. The “telephone password” can be viewed or changed in the configuration of the infocaller service on our website (Start tab of the configuration of your infocaller line). An algorithm called MD5 (explained in Appendix 1 of this document) must be applied to the text obtained from the concatenation of these three values. The result is what should be indicated as “Signature”.


An example of authentication:

 

    If the LineNumber infocaller were: 123456789

    If the CallSequence of this call were: 98565656

    If the “telephone password” of the service were: 3956


 Applying the MD5 algorithm to 123456789985656563956 gives the result ae73e4b16a280726fb2e0e6bfb43902a


 The authentication section you will receive will be:


XML


<UserID>

  <LineNumber>123456789</LineNumber>

  <LineNumberInt>34123456789</LineNumberInt>

  <CallSequence>98565656</CallSequence>

   <Signature>ae73e4b16a280726fb2e0e6bfb43902a</Signature>

</UserID>


JSON


"UserID": {

      "LineNumber": "123456789", 

      "LineNumberInt": "123456789", 

      "CallSequence": "98565656", 

      "Signature": "ae73e4b16a280726fb2e0e6bfb43902a" 

    }


  

 

'Infocaller' section

 

This section includes call data:


  • CallType: “R” if it is an incoming call or “E” if it is an issued call
  • CallerNumber: For incoming calls is the caller's phone number. If it is hidden it will have a value of “X”. In issued calls, is the Infocaller number that originates the call. In this case, it will be the same as LineNumber unless the infocaller service has additional numbers and the call has been issued by one of these numbers
  • CallerNumberInt: In issued calls, it is the Infocaller number that originates the call. In this case, it will be the same as LineNumberInt unless the infocaller service has additional numbers and the call has been issued by one of these numbers. In international format, including the country code.
  • InboundNumber: is the infocaller number that received the call. It will be the same as LineNumber unless the infocaller service has additional numbers and the call has been answered by one of these numbers.
  • InboundNumberInt: as InboundNumber but in international format, including the country code.
  • OutboundNumber: is the destination telephone number of an issued call.
  • idcall: it is the unique identifier of the request of an issued call (see call issuing API).
  • CallSeconds: Total duration in seconds of the call received or issued (FIN event only).
  • StartDate: Date and time of the start of the call yyyy-mm-ddThh: mm: ss (FIN event only).
  • EndDate: Date and time of the end of the call yyyy-mm-ddThh: mm: ss (FIN event only).
  • CostRX: Tax-free cost of the call received (FIN event only)
  • CostTX: Tax-free cost of the issued call (FIN event only)

 

  

'Status' section

  

This section includes the breakdown of all the actions that have occurred in the call (FIN event only


  • EventType: is a numerical code that indicates the type of action:


1- Message


2- Call


     The destination number is indicated in EventName


     [EventAddInfo3: Duration in seconds]


     [EventAddInfo4: Amount without taxes]


3- Answering machine


4- Keypad data entry


     [EventAddInfo1: Data collected]


5- Data request by voice


6- Numeric menu


     [EventAddInfo1: Option checked]


7- End Call


     [EventAddInfo4: Cost without taxes optional SMS notice]


8- Go to


11- Sending email


12- SMS sending


     [EventAddInfo4: Amount]


13- Script


14- Start call and rules applied


15- Call transfer


16- Waiting queue


17- Query API


     [EventAddInfo1: Result (0/1)]


18- Verified condition of a list of conditions


21- Continue the script after a detour



ü    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 

  

 

'CustVars' section

 

This section includes the user variables that have been defined in the call so far:

  • VarName: the name of the variable
  • VarValue: the value of the variable


2- INTERACTIVE API 

 

From an Infocaller script you can interact with your web application at any time during the call. You can send to your application the data that you can collect in the call and also obtain data from your application and use them in the call. To do this you must define ‘Queries”. Each Query has an associated URL. Queries can be configured in the "API" section of the "start" tab of the infocaller configuration.


Once the Query is defined, you can use it anywhere in the script.

  

Each "Query" will send an XML or JSON structure by POST with:


- line identification and authentication data


- variables with the call data


- user variables defined in other infocaller actions prior to the Query



Your web application must respond to this HTTP request with an XML or JSON structure where it can list user variables that will modify the existing ones in the call (if any with the same name) or will be created as new variables in the call. If the appropriate response is not obtained or if the waiting time expires, the action indicated by the user for these cases will be executed in the definition of the Query.

  

The infocaller actions that can define new user variables are:

  - GET DATA BY MARKING, within a script

  - QUERY itself


   

The infocaller actions that can be used by user variables are:

- CALL: the destination of a call can be specified using a user variable

- LIST OF CONDITIONS: within the script, it allows defining actions based on the evaluation of call variables

- QUERY itself

  

  

2.1 Information sent by POST

 

n each call of Infocaller to the Query that you have defined, a variable called apiInfocaller will be included. Depending on your account settings, the content of the variable can be in XML format or in JSON format.


JSON Format

 

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

        } 

      ] 

    } 

  } 

}

 


XML Format

 

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

 

Authentication

 

Authentication commands allow you to optionally validate that the request is authentic and comes from our servers. The authentication section includes four data, which are:


  • LineNumber: main number of the infocaller service
  • LineNumberInt: main number of the infocaller service but in international format, including the country code
  • CallSequence: unique identifier of the call generated by infocaller.
  • Signature: This is a security measure to ensure authentication. To obtain the signature, three values are concatenated first: <LineNumber> + <CallSequence> + <telephone password>. The “telephone password” can be viewed or changed in the configuration of the infocaller service on our website (Start tab of the configuration of your infocaller line). An algorithm called MD5 (explained in Appendix 1 of this document) must be applied to the text obtained from the concatenation of these three values. The result is what should be indicated as “Signature”.



An example of authentication:

 

  •     If the LineNumber infocaller were: 123456789
  •     If the CallSequence of this call were: 98565656
  •     If the “telephone password” of the service were: 3956


 Applying the MD5 algorithm to 123456789985656563956 gives the result ae73e4b16a280726fb2e0e6bfb43902a


And the authentication commands would be:

 

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>

 


 

'Infocaller' section

 

This section includes call data:

   

  • CallType: "R" if it is a received call or "E" if it is an issued call


  • CallerNumber: For incoming calls is the caller's phone number. If it is hidden it will have a value of “X”. In issued calls, it is the number


Infocaller that originates the call. In this case, it will be the same as LineNumber unless the infocaller service has additional numbers and the call


has been issued by one of these numbers.


  • CallerNumberInt: In issued calls it is like CallerNumber but in international format, including the country code


  • InboundNumber: is the infocaller number that received the call. It will be the same as LineNumber unless the infocaller service has numbers


additional and the call has been answered by one of these numbers.


  • InboundNumberInt: as InboundNumber but in international format, including the country code


  • OutboundNumber: is the destination telephone number of an issued call.


  • idcall: it is the unique identifier of the request of an issued call (see call issuance API).


  • QueryName: is the name of the user-defined Query.

 

 

'CustVars' section

 

This section includes the user variables that have been defined in the call until the time of the Query:


     VarName: the name of the variable


     VarValue: the value of the variable

 


2.2 POST response information

 

Your web application should respond with a data structure (in JSON or XML, depending on your account settings).


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>

 


'Status' section

   

This section includes two variables:


  • Result: the value must be "0" (zero) if the request or other user-defined value has been processed correctly in case of error. Any non-zero value will result in the execution of the action that the user indicated for these cases in the definition of the Query
  •  ResultText: is a user-defined description of the reported result.

 

  

'CustVars' Section

 

In this section you can include the variables that you want to make available to the call. If it is not necessary to return any value, an empty section will be returned: <CustVars> </CustVars>.


  •  VarName: the name of the variable (conditions of Appendix 2)
  •  VarValue: the value of the variable (conditions of Appendix 3)

 

 

2.3 Query use examples

 

Example 1: Automatic information on the status of an order.

 

Script:

  

- 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 

  

The XML that would be sent would be similar to:

 

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

 

And the answer:

 

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

 

Example 2: Diversion to extension

    

In this example, the user dials an extension, the corresponding telephone number is consulted via query and the call is diverted to the PHONE obtained in response.

    

Script:

- 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



Appendix 1– MD5 Algorithm

 

The MD5 algorithm converts a text into a cryptographic reduction using mathematical formulas.


For example, the text "This is an MD5 test" becomes the "hash" "e99008846853ff3b725c27315e469fbc" in a unique way. But it is not possible to obtain the original phrase from the "hash". This makes it especially useful for serve as an authentication system when the original text is not known A more comprehensive explanation can be obtained at http://es.wikipedia.org/wiki/MD5.

 

The MD5 is used to increase security in the client authentication process.


For the purposes of this application, an MD5 conversion function must be obtained in the language of the application or web page from which the message will be sent. There are many different free applications that can be found using search phrases such as "MD5 ASP", "MD5 PHP", "MD5 Java", "MD5 Visual Basic", etc., depending on the language that will be used. It is the client's responsibility to verify the quality and reliability of the MD5 conversion function that he will use in his application.

 

If you have any difficulty or limitation in the use of the MD5, please contact our customer service department at help@infocaller.com or at 900 80 50 89.




Appendix 2 – Requirements for variable names

 

It must consist of the letters A to Z or digits from 0 to 9, without spaces or other characters. And a maximum length of 15 positions.

 


Appendix 3 – Allowed characters in variable values

 

The printable characters ASCII and those of ISO-8559-1, except>, <, &, ‘and“. The latter should be included using:

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

 


More info in our blog