With Infocaller it is possible to issue phone calls from any application that can make an HTTPS call and send information by POST.


Once the call is issued, the actions carried out in it are defined in the actions and rules of infocaller and can be used within the Interactive API script. In an infocaller script you can connect the call made with another outgoing call and thus achieve a very powerful “click-to-call” system that gives you the flexibility to call the customer first and then your call center (to optimize the time of the agents), or first call the agent and then the client (to optimize the quality of the call).


This section describes how HTTPS calls should be prepared to be authenticated and processed correctly by infocaller.


The call issuance request must be sent by POST in JSON or XML format. The petition is divided into two sections; one of identification and another with the data of the call.


  • URL - The address to send call forwarding requests is https://apicall.infoe.es
  • POST - When accessing the previous URL, you must send via POST a variable called apiCALLjson or apiCALLxml, as appropriate, which will contain the request information:
  • Authentication data on our platform
  • The data of the call to be made
  • The variables that you want to use in the call


Estructura del XML
 

The XML must have the following structure, divided into a first identification section and another with the information of the call request:


<callRequest xmlns='http://tempuri.org/'>
   <UserID>
 

      <idinfocaller></idinfocaller>  

      <firma></firma>
   </UserID> 
 

   <callData>
<numtelefono></numtelefono>
      <gruporeglas></gruporeglas>
 

<fechahora></fechahora>
<EsperaMax></EsperaMax>
<Reintentos></Reintentos>
      <CustVars> 
 

         <CustVar>
<VarName></VarName>
            <VarValue></VarValue> 
 

         </CustVar>
         <CustVar> 
 

            <VarName></VarName>  

            <VarValue></VarValue>
         </CustVar> 
 

      </CustVars>   

   </callData>
</callRequest>

 

Azul: mandatory data Rojo: optional data


JSON structure

 

The XML must have the following structure, divided into a first identification section and another with the information of the call request:


{"callRequest": {

     "UserID": { 

      "idinfocaller": "DATO", 

      "firma": "DATO" 

    }, 

    "callData": { 

      "numtelefono": "DATO", 

      "gruporeglas": "DATO", 

      "fechahora": "DATO", 

      "EsperaMax": "DATO", 

      "Reintentos": "DATO", 

      "CustVars": { 

        "CustVar": [ 

          { 

            "VarName": "DATO", 

            "VarValue": "DATO" 

          }, 

          { 

            "VarName": "DATO", 

            "VarValue": "DATO" 

          } 

        ] 

      } 

    } 

  } 

}


Blue: mandatory data    Red: optional data 


'Autenticación' section


Authentication commands are used to validate that the request comes from an authorized client and to associate the call with an infocaller line.


The authentication section includes two data, which are:


<UserID>
 <idinfocaller>
 
numero</idinfocaller>
 <firma>
cadena_md5
</firma>
</UserID>
    


  • idinfocaller: Infocaller service number with which calls will be made, including the country code. You can check the service number in your account, in the "Configure" tab. 
    • firma: It is an infocaller security measure to ensure authentication. To obtain the signature, two values are concatenated first: <idinfocaller> + <line password>. The “password line” can be obtained in the configuration of the infocaller service in the ‘home’ tab. An algorithm called MD5 (explained in Appendix 1 of this document) must be applied to the text obtained from the concatenation of these two values. The result is what should be indicated as "md5_string" in the signature.
       

Autenticación example:

If the infocaller service number were: 123456789

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

 

Applying the MD5 algorithm to 1234567893956 the result is obtained

a2e12e9171fec3ebbb9c3c2a41b0b722 And the authentication commands would be:

 

     <idinfocaller> 123456789 </idinfocaller>
     <firma>
a2e12e9171fec3ebbb9c3c2a41b0b722  </firma>  



'callData' section (with * are required)


  • numtelefono *: Destination phone of the call in international format. If no country is specified, the one configured in the infocaller service is assumed.
  • gruporeglas *: The name of the rule group of the infocaller service that you want to use for the Emission of calls. This group of rules does not need to be in the "Active" state. When in the "Active" state, it always acts on incoming calls to the infocaller number. Therefore, the Call Forwarding rules group should not be confused with the one used for Incoming Calls.
  • Fechahora: if they are not specified, it is assumed that the call will be made immediately. Format: YYYY-MM-DDTHH: MM: SS (24 hours) 
  • EsperaMax: time in minutes, from the date and time of shipment, during which the request will be kept on hold in case of not having available simultaneous lines. Upon expiration of the time, the request will be canceled and the failed attempt will be recorded in the activity query. Default value: 5 minutes. Maximum value 300 minutes.   
  • Reintentos: Number of retries in case the call communicates. The retries will be made with minimum intervals of 5 minutes. Calls that do not answer will not be retried. Default value: 0 retries. Maximum value: 4 retries


Response to the request


  

At the time of receiving the request, a simple XML or JSON response will be sent indicating whether the request has been accepted or not. If it is not accepted, the reason will be indicated.

 

 

XML structure

 

    

<?xml version='1.0'?>
<callRequest>
<idcall></idcall>
<Resultado></Resultado>
<ResultadoTexto></ResultadoTexto>
</callRequest>

  


  

Estructura del JSON 

    

{ "callRequest": {

  

    "idcall": "DATO",

  

    "Resultado": "DATO",

  

    "ResultadoTexto": "DATO"

  

  }

  

}

  


  

idcall: Unique identifier assigned by infocaller to valid call requests. 

  


  

Resultado 

ResultadoTexto 

Aceptada 

-1 

Identificación no correcta 

-2 

Identificación no indicada 

-3 

Formato XML no correcto 

-99 

No se recibe el parámetro XML 

-100 

Error interno 

Firma no correcta 

Línea infocaller no válida 

Línea infocaller apagada 

Fecha/Hora no válida 

Teléfono no válido 

Valor Esperamax no válido 

Valor reintentos no válido 

Grupo de reglas no existe o no es válido 

Regla de fin de llamada 

10 

Línea suspendida 

11 

Saldo insuficiente 

12 

Límite de crédito excedido 

13 

Ninguna regla válida en grupo de reglas 

14 

Excedido número máximo de emisión de llamadas. Contactar con Atención al Cliente. 

  


  

Note: additional controls to those made by the HTTPS API will be performed at the time of making the call (customer administrative controls, validity of advanced options, etc.). In case of not being approved, notifications can be sent to the client via email.

  

 

 


Examples:


Informative call with possible diversion:

 

Calls are issued to report the status of a repair. A rule group "Repair Status" is created with a script in infocaller that, depending on the STATUS variable, will reproduce one or the other message and will pass the call to the workshop in one of the cases:

  

STATUS = 1 - “We inform you that your repair has been carried out and you can go through the workshop”

STATUS = 2 - “We inform you that to finalize the repair you must approve the budget. We passed the call with the workshop to get all the details and give their approval ”


<callRequest xmlns='http://tempuri.org/'>
<UserID>
<idinfocaller>123456789</idinfocaller>
<firma>a2e12e9171fec3ebbb9c3c2a41b0b722</firma></UserID>
<callData>
<numtelefono>34911888920</numtelefono>
<gruporeglas>Estado Reparación</gruporeglas>
<esperamax>30</esperamax>
<CustVars>
<CustVar>
<VarName>ESTADO</VarName>
<VarValue>2</VarValue>
</CustVar>
</CustVars>
</callData>
</callRequest>



Click-to-call:


A call is issued at a specific time to connect the recipient to a provider you have chosen (a variable destination). A “Click to Call” group of rules is created with a script in infocaller that issues a speech and makes a call to the telephone number indicated in the CALLCENTER variable:


<callRequest xmlns='http://tempuri.org/'>
<UserID>
<idinfocaller>123456789</idinfocaller>
<firma>a2e12e9171fec3ebbb9c3c2a41b0b722</firma>
</UserID>
<callData>
<numtelefono>+34611222333</numtelefono>
<gruporeglas>Click to Call</gruporeglas>
<fecha>30/04/2015</fecha>
<hora>16:00:00</hora>
<esperamax>180</esperamax>
<reintentos>2</reintentos>
<CustVars>
<CustVar>
<VarName>CALLCENTER</VarName>
<VarValue>+34911888920</VarValue>
<CustVar>
</CustVars>
</callData>
</callRequest>




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 unknown. A more comprehensive explanation can be obtained at https://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 requests will be made. 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 MD5, please contact our customer service department at help@infocaller.com


More info in our blog