API de campañas
Sumario
- 1 ¿Qué es la API de campañas?
- 2 Autenticación
- 3 Forma de uso
- 3.1 Listar campañas (accion=listar)
- 3.2 Crear una campaña (accion=nueva)
- 3.3 Ver una campaña (accion=ver)
- 3.4 Añadir números a una campaña (accion=anyadir)
- 3.5 Cambiar datos de una campaña (accion=cambiar)
- 3.6 Cerrar una campaña (accion=cerrar)
- 3.7 Siguiente llamada (accion=siguiente)
- 3.8 Guardar resultado de una llamada (accion=guardar)
- 3.9 Eliminar una campaña (accion=eliminar)
- 3.10 Respuesta del servicio
- 4 Ejemplos API de campañas
¿Qué es la API de campañas?
Descripción API de campañas
Este servicio web nos permite gestionar campañas de llamadas salientes en una cuenta Telefácil: crear campañas, listar las existentes, añadir números, iniciar llamadas y guardar los resultados de cada una.
Si no sabe lo que es una API lea ¿Qué son las APIs de Telefácil?
Autenticación
Todas las llamadas a esta API requieren los parámetros de autenticación:
- 'principal' es su número de usuario de la cuenta Telefácil (o teléfono principal).
- 'pass' es la contraseña de la cuenta Telefácil.
La URL base para todas las operaciones es:
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=...
Forma de uso
Listar campañas (accion=listar)
Devuelve la lista de campañas de la cuenta (en XML). Esta es también la acción por defecto si se omite el parámetro 'accion'.
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=listar
Ejemplo de respuesta:
<?xml version="1.0" encoding="UTF-8" ?>
<campanyas>
<error>0</error>
<campanya>
<id>2024-03-15_10-30-00_p12345.sqlite</id>
<nombre>Clientes marzo</nombre>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<estado>0</estado>
<grabamos>0</grabamos>
<total>150</total>
<pendientes>87</pendientes>
<acabadas>63</acabadas>
</campanya>
<campanya>
<id>2024-02-01_09-00-00_p54321.sqlite</id>
<nombre>Campaña febrero</nombre>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<estado>1</estado>
<grabamos>0</grabamos>
<total>200</total>
<pendientes>0</pendientes>
<acabadas>200</acabadas>
</campanya>
</campanyas>
El campo 'estado' indica si la campaña está abierta (0) o cerrada (1).
Crear una campaña (accion=nueva)
Crea una nueva campaña con la lista de números indicada.
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=nueva&nombre=...&llamante=...&mascara=...&numeros=...
donde:
- 'nombre' es el nombre descriptivo de la campaña.
- 'llamante' es el número desde el que se realizarán las llamadas (debe ser un número activado de la cuenta).
- 'mascara' es el número que verá el destinatario de la llamada (debe ser una máscara válida de la cuenta).
- 'numeros' es la lista de números a llamar, un número por línea. Opcionalmente, separado por coma o tabulador, se puede incluir información adicional sobre el contacto.
- 'repes' (opcional): si se incluye este parámetro, se eliminan los números duplicados.
- 'grabamos' (opcional): si se incluye este parámetro, las llamadas se grabarán.
El número puede incluir prefijo internacional con + (se convierte automáticamente a 00) o ser una extensión VoIP del tipo usuario@telefacil.com. Se admite un máximo de 5.000 números por campaña.
Ejemplo de respuesta:
<?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>0</error> <id>2024-03-15_10-30-00_p12345.sqlite</id> <telefonos>150</telefonos> </campanyas>
El campo 'id' es el identificador de la campaña creada, que se usará en el resto de operaciones. El campo 'telefonos' indica cuántos números se insertaron correctamente.
Ver una campaña (accion=ver)
Devuelve los datos completos de una campaña y la lista de todos sus números.
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=ver&campanya=...
donde:
- 'campanya' es el identificador de la campaña (campo 'id' devuelto por 'listar' o 'nueva').
Ejemplo de respuesta:
<?xml version="1.0" encoding="UTF-8" ?>
<campanyas>
<error>0</error>
<campanya>
<id>2024-03-15_10-30-00_p12345.sqlite</id>
<nombre>Clientes marzo</nombre>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<estado>0</estado>
<grabamos>0</grabamos>
<minutos>0</minutos>
<telefono>
<oid>1</oid>
<numero>666111222</numero>
<info>Juan García</info>
<comentario>Interesado en tarifa plana</comentario>
<estado>3</estado>
<resultado>4</resultado>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<momento>2024-03-15 11:05:32</momento>
<ref>abc123</ref>
<usuario>912345678</usuario>
<recordar></recordar>
</telefono>
<telefono>
<oid>2</oid>
<numero>666333444</numero>
<info>María López</info>
<comentario></comentario>
<estado>0</estado>
<resultado>0</resultado>
<llamante></llamante>
<mascara></mascara>
<momento></momento>
<ref></ref>
<usuario></usuario>
<recordar></recordar>
</telefono>
</campanya>
</campanyas>
Los valores del campo 'estado' de cada teléfono son: 0=libre, 1=intentando, 2=cogida, 3=acabada.
Los valores del campo 'resultado' son: 0=Sin resultado, 1=No contestada, 2=Comunicando, 3=Buzón, 4=Contestada.
Añadir números a una campaña (accion=anyadir)
Añade números a una campaña existente. Solo se pueden añadir números si la campaña está abierta (estado=0).
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=anyadir&campanya=...&numeros=...
donde:
- 'campanya' es el identificador de la campaña.
- 'numeros' es la lista de números a añadir, uno por línea (mismo formato que en 'nueva').
- 'repes' (opcional): si se incluye, se omiten números ya existentes en la campaña.
Ejemplo de respuesta:
<?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>0</error> <telefonos>25</telefonos> </campanyas>
Cambiar datos de una campaña (accion=cambiar)
Modifica el nombre, llamante y máscara de una campaña existente.
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=cambiar&campanya=...&nombre=...&llamante=...&mascara=...
donde:
- 'campanya' es el identificador de la campaña.
- 'nombre' es el nuevo nombre de la campaña.
- 'llamante' es el nuevo número llamante.
- 'mascara' es la nueva máscara.
Ejemplo de respuesta:
<?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>0</error> </campanyas>
Cerrar una campaña (accion=cerrar)
Marca la campaña como cerrada. Una vez cerrada no se pueden añadir números ni iniciar nuevas llamadas.
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=cerrar&campanya=...
donde:
- 'campanya' es el identificador de la campaña.
Ejemplo de respuesta:
<?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>0</error> </campanyas>
Siguiente llamada (accion=siguiente)
Selecciona el siguiente número pendiente de la campaña e inicia la llamada mediante callback: primero se llama al número 'llamante' y, cuando descuelga, se conecta automáticamente con el número de destino de la campaña.
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=siguiente&campanya=...
donde:
- 'campanya' es el identificador de la campaña.
- 'llamante' (opcional): sobreescribe el llamante almacenado en la campaña para esta llamada.
- 'mascara' (opcional): sobreescribe la máscara almacenada en la campaña para esta llamada.
Ejemplo de respuesta cuando la llamada se inicia correctamente:
<?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>0</error> <resultado>1</resultado> <oid>42</oid> <numero>666111222</numero> <info>Juan García</info> <comentario></comentario> <ref>abc123</ref> </campanyas>
El campo 'oid' identifica el registro del número llamado y debe usarse en la operación 'guardar' para guardar el resultado. El campo 'ref' es la referencia interna de la llamada. Si no hay más números pendientes:
<?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>0</error> <resultado>0</resultado> <msgerr>No hay mas llamadas en esta campanya</msgerr> </campanyas>
Guardar resultado de una llamada (accion=guardar)
Guarda el resultado de una llamada iniciada con 'siguiente'. Debe llamarse después de que el agente haya completado la llamada.
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=guardar&campanya=...&oid=...&resultado=...&comentario=...
donde:
- 'campanya' es el identificador de la campaña.
- 'oid' es el identificador del número devuelto por 'siguiente'.
- 'resultado' es el resultado de la llamada: 0=Sin resultado, 1=No contestada, 2=Comunicando, 3=Buzón, 4=Contestada.
- 'comentario' (opcional): comentario libre sobre la llamada.
- 'llamante' (opcional): llamante usado en la llamada.
- 'mascara' (opcional): máscara usada en la llamada.
- 'dejar_para_despues' (opcional): si se incluye, el número vuelve a la cola para ser llamado de nuevo.
- 'recordar' (opcional, requiere 'dejar_para_despues'): si se incluye, se crea un recordatorio.
- 'fechayhora' (opcional, requiere 'recordar'): fecha y hora del recordatorio en formato DD/MM/AAAA HH:MM.
Ejemplo de respuesta:
<?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>0</error> </campanyas>
Eliminar una campaña (accion=eliminar)
Elimina permanentemente una campaña y todos sus datos. Esta operación no se puede deshacer.
https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas?principal=xxxxxxxxx&pass=xxxxxxxx&accion=eliminar&campanya=...
donde:
- 'campanya' es el identificador de la campaña.
Ejemplo de respuesta:
<?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>0</error> </campanyas>
Respuesta del servicio
El servicio web retorna todas las respuestas en formato XML. Todas las respuestas están encerradas en la raíz 'campanyas', y contienen siempre un campo 'error' que será 0 si el comando o petición enviado al servidor se ejecutó con éxito, o 1 si hubo algún error, en cuyo caso habrá también un campo 'msgerr' que explica dicho error.
Una respuesta de error sería:
HTTP/1.1 200 OK Content-Type: text/xml <?xml version="1.0" encoding="UTF-8" ?> <campanyas> <error>1</error> <msgerr>Registro incorrecto. Compruebe que el usuario y la clave sean validos (1).</msgerr> </campanyas>
Ejemplos API de campañas
Ejemplo de flujo completo en PHP + CURL
Tenga presente que, aunque la aplicación web es accesible mediante una URL, no debe poner nunca enlaces a esta aplicación directamente en el código fuente de sus páginas web, ya que sus visitantes podrían descubrir datos sensibles como su número de usuario y su contraseña simplemente mirando el código HTML.
La aplicación web debe ser llamada siempre desde el servidor, usando para ello alguna de las librerías que permite llamadas a servicios HTTPS.
He aquí un ejemplo en PHP usando cURL que crea una campaña, inicia una llamada y guarda el resultado:
<?php
$principal = '912345678';
$pass = 'MiPass123';
$base_url = 'https://scgi.duocom.es/cgi-bin/telefacil2/apicampanyas';
function api_campanyas($base_url, $params) {
$url = $base_url . '?' . http_build_query($params);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
$output = curl_exec($curl);
curl_close($curl);
return simplexml_load_string($output);
}
// 1. Crear una campaña
$xml = api_campanyas($base_url, [
'principal' => $principal,
'pass' => $pass,
'accion' => 'nueva',
'nombre' => 'Campaña de prueba',
'llamante' => '912345678',
'mascara' => '900123456',
'numeros' => "666111222,Juan García\n666333444,María López\n",
'repes' => '1',
]);
if ((int)$xml->error !== 0) die('Error: ' . $xml->msgerr);
$campanya_id = (string)$xml->id;
echo "Campaña creada: $campanya_id con {$xml->telefonos} teléfonos\n";
// 2. Iniciar la siguiente llamada
$xml = api_campanyas($base_url, [
'principal' => $principal,
'pass' => $pass,
'accion' => 'siguiente',
'campanya' => $campanya_id,
]);
if ((int)$xml->error !== 0) die('Error: ' . $xml->msgerr);
if ((int)$xml->resultado === 0) die("No hay más llamadas pendientes\n");
$oid = (int)$xml->oid;
$numero = (string)$xml->numero;
echo "Llamando a $numero (oid=$oid)...\n";
// 3. Guardar el resultado (tras que el agente complete la llamada)
$xml = api_campanyas($base_url, [
'principal' => $principal,
'pass' => $pass,
'accion' => 'guardar',
'campanya' => $campanya_id,
'oid' => $oid,
'resultado' => 4, // 4 = Contestada
'comentario' => 'Cliente interesado, enviar oferta',
]);
if ((int)$xml->error !== 0) die('Error: ' . $xml->msgerr);
echo "Resultado guardado correctamente\n";
?>
Ejemplo de listado de campañas en XML
<?xml version="1.0" encoding="UTF-8" ?>
<campanyas>
<error>0</error>
<campanya>
<id>2024-03-15_10-30-00_p12345.sqlite</id>
<nombre>Clientes marzo</nombre>
<llamante>912345678</llamante>
<mascara>900123456</mascara>
<estado>0</estado>
<grabamos>0</grabamos>
<total>150</total>
<pendientes>87</pendientes>
<acabadas>63</acabadas>
</campanya>
</campanyas>
Indice
Página principal >> Desarrolladores >> API de campañas.