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.