Documentación para Desarrolladores

Integración ITBX versión 1.0

Introducción

Para usar la integración debe solicitar unas credenciales ya que todos los métodos utilizan un token. Ese token se consigue logueándose con las credenciales y se explica en este documento.

1. Crear TOKEN mediante Login

Descripción: Crea nuestro Token de seguridad para API, por medio del servicio de login

Tipo de salida: JSON con parámetros (access_token, token_type, expires_in)

Ruta: https://api.itbx.co/api/v1/login

Método: POST

Parámetros de entrada:

  • email => Requerido, String (ejemplo: prueba1@gmail.com)
  • password => Requerido, String (ejemplo: 123)

Ejemplo de salida:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvbWFuYWdlci5pdGJ4LmNvXC9hcGlJdGJ4XC9pbmRleC5waHBcL2FwaVwvdjFcL2xvZ2luIiwiaWF0IjoxNTk0Mzk5MTE3LCJ",
    "token_type": "bearer",
    "expires_in": 31536000
}

2. Borrar TOKEN activo

Descripción: Borra un token previamente activo desde ITBX

Tipo de salida: JSON

Ruta: https://api.itbx.co/api/v1/eliminarToken

Método: POST

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)

Ejemplo de salida:

{
    "error": false,
    "data": "Token revocado"
}

3. Envíar de un mensaje SMS hacia uno o varios destinos

Descripción: Envía de un mensaje específico de SMS a un destino o a un lote de varios destinos (lotes de máximo 100 números)

Tipo de salida: JSON array con parámetros para cada teléfono (tel, msg, error, code). Cada teléfono tiene una respuesta: "error" = false si se lleva a cabo correctamente, de lo contrario, se considera error al enviar y "msg" contiene el mensaje del error correspondiente.

Ruta: https://api.itbx.co/api/v1/usuario/enviarSMS

Método: POST

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • numeros => Requerido, String (ejemplo: 3178516770,3158536149,3145645677)
  • mensaje => Requerido, String (ejemplo: Hola mundo)

Ejemplo de salida:

[
    {
        "tel": "123456",
        "msg": "Ok",
        "error": false,
        "code": 1
    },
    {
        "tel": "123456",
        "msg": "Ok",
        "error": false,
        "code": 1
    }
]

4. Crear campaña masiva SMS de una vía o doble vía

Descripción: Crea una campaña de envío masivo de mensajes SMS a múltiples destinos con mensajes generales o individuales, con opción de mensaje en una vía y doble vía (Ejemplo: La respuesta del destinatario).

Tipo de salida: JSON con id de campaña

Ruta: https://api.itbx.co/api/v1/usuario/newCampaignSMS

Método: POST

Parámetros de entrada: Objeto JSON con los siguientes parámetros:

  • token => Requerido, String (ir a API Login)
  • arrayphones => Requerido, Array asociativo (ejemplo: [{"phone": 1234, "message":"mensaje de prueba 1"}, {"phone": 123456, "message":"mensaje de prueba 2"}])
  • namecampaign => Requerido, String (ejemplo: Campaña de prueba)
  • startdate => Requerido, Fecha (ejemplo: 2020-09-08)
  • starthour => Requerido, Hora formato 24H (ejemplo: 09:00:00)
  • endhour => Requerido, Hora formato 24H (ejemplo: 16:05:00)
  • message => Requerido, String (ejemplo: Mensaje de prueba)
  • callid => Requerido, String (ejemplo: 317676789897)
  • paused => Opcional, Integer (1 para indicar que la campaña se genera en pausa)
  • duplex => Opcional, Integer (1 para indicar que la campaña es duplex)

Ejemplo de entrada:

    {"arrayphones": [{"phone": 1234, "message":"mensaje 1"},{"phone": 89789789, "message":"mensaje 2"}],"namecampaign": "Campaña auto 1","startdate": "2020-09-08","starthour": "09:00:00","endhour": "18:10:00","message": "Hola mundo","callid": 315678989899}

Ejemplo de salida sin errores:

{ "error": false, "data": 26 }

Ejemplo de salida con errores:

{ "error": true, "msg": "Error en el formato de las fechas" }

5. Editar parámetros de campaña masiva SMS

Descripción: Edita los parámetros e inicia o pausa el envío de una campaña masiva SMS activa

Tipo de salida: JSON con id de campaña

Ruta: https://api.itbx.co/api/v1/usuario/editCampaignSMS

Método: POST

Parámetros de entrada: Objeto JSON con los siguientes parámetros:

  • token => Requerido, String (ir a API Login)
  • idcampaign => Requerido, Integer (ejemplo: 26)
  • startdate => Opcional, Fecha (ejemplo: 2020-09-08)
  • starthour => Opcional, Hora formato 24H (ejemplo: 09:00:00)
  • endhour => Opcional, Hora formato 24H (ejemplo: 16:05:00)
  • callid => Opcional, String (ejemplo: 317676789897)
  • paused => Opcional, Boolean (true o false, para indicar que la campaña se detiene o inicia)

Ejemplo de entrada:

{"idcampaign": 26,"startdate": "2020-09-08","starthour": "09:00:00","endhour": "18:10:00","callid": 315678989899,"paused":true}

Ejemplo de salida sin errores:

{ "error": false, "data": 26 }

Ejemplo de salida con errores:

{ "error": true, "msg": "Error en el formato de las fechas" }

6. Borrar campaña masiva SMS de una vía o doble vía

Descripción: Borrar una campaña masiva SMS activa

Tipo de salida: JSON

Ruta: https://api.itbx.co/api/v1/usuario/deleteCampaignSMS

Método: POST

Parámetros de entrada: Objeto JSON con los siguientes parámetros:

  • token => Requerido, String (ir a API Login)
  • idcampaign => Requerido, Integer (ejemplo: 26)

Ejemplo de salida sin errores:

{ "error": false, "data": "Ok" }

Ejemplo de salida con errores:

{ "error": true, "msg": "Error: No existe la campaña" }

7. Agregar registros de contacto a campaña masiva SMS

Descripción: Agrega registros invididuales o por lote, con mensaje general o individuales a una campaña masiva SMS activa.

Tipo de salida: JSON con id de campaña

Ruta: https://api.itbx.co/api/v1/usuario/addCampaignNumbersSMS

Método: POST

Parámetros de entrada: Objeto JSON con los siguientes parámetros:

  • token => Requerido, String (ir a API Login)
  • idcampaign => Requerido, Integer (ejemplo: 26)
  • arrayphones => Requerido, Array asociativo (ejemplo: [{"phone": 1234, "message":"mensaje de prueba 1"}, {"phone": 123456, "message":"mensaje de prueba 2"}])

Ejemplo de entrada:

{"arrayphones": [{"phone": 1234,"message":"mensaje 1"},{"phone": 89789789,"message":"mensaje 2"}],"idcampaign": 26}

Ejemplo de salida sin errores:

{ "error": false, "data": 26 }

Ejemplo de salida con errores:

{ "error": true, "msg": "Error: No existe la campaña" }

8. Consultar HISTÓRICO detallado de campaña masiva SMS de una vía o doble vía

Descripción: Consulta todos los datos del reporte detallado con resultados de envío de una campaña masiva SMS (por rango de tiempo y con limite de registros)

Tipo de salida: JSON

Ruta: https://api.itbx.co/api/v1/usuario/getHistoricoMensajesSMS

Método: GET

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • startdate => Requerido, Fecha inicial (ejemplo: 2020-07-16 17:13:55)
  • enddate => Requerido, Fecha final (ejemplo: 2020-07-24 16:57:40)
  • offset => Opcional, Integer
  • limit => Opcional, Integer

Ejemplo de salida:

{
"total": 2,
"mensajes": [
{
    "mensaje": "Hola mundo",
    "fecha_envio": "2022-06-17 17:33:25",
    "enviado": true,
    "codigo_respuesta": 1,
    "mensaje_respuesta": "Mensaje Enviado",
    "telefono_destino": "57317xxxxx",
    "origen": "web",
    "tipo": "1via",
    "created_at": "2022-06-17 17:33:25",
    "updated_at": "2022-06-17 17:33:25"
},
{
    "mensaje": "Mensaje de prueba",
    "fecha_envio": "2022-06-21 15:54:46",
    "enviado": true,
    "codigo_respuesta": 1,
    "mensaje_respuesta": "Mensaje Enviado",
    "telefono_destino": "57317xxxxx",
    "origen": "campaign",
    "tipo": "1via",
    "created_at": "2022-06-21 15:54:46",
    "updated_at": "2022-06-21 15:54:46"
}
]
}

9. Agregar lista de contactos a campaña AUTOMÁTICA

Descripción: Agrega lista de registros a una campaña automática activa (Predictiva y/o Progresiva).

Tipo de salida: 1 si es correcto o mensaje si hay un error

Ruta: https://api.itbx.co/api/v1/usuario/setCallbackCampaign

Método: POST

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • campaign_name => Requerido, String (ejemplo: Auto 1)
  • numbers => Requerido, Array asociativo

Ejemplo de entrada:

{ "numbers": { "John": "123456", "Daniel": "654321" }, "campaign_name": "Auto 1" }

10. Agregar un contacto a campaña AUTOMÁTICA

Descripción: Agrega un registro a una campaña automática activa (Predictiva y/o Progresiva).

Tipo de salida: 1 si es correcto o mensaje si hay un error

Ruta: https://api.itbx.co/api/v1/usuario/setNewContactAuto

Método: POST

Parámetros de entrada: Objeto JSON con los siguientes parámetros:

  • token => Requerido, String (ir a API Login)
  • phone => Requerido, String (ejemplo: 3156745677)
  • name => Requerido, String (ejemplo: Diego Erley)
  • campaign_name => Requerido, String (ejemplo: Campaña de prueba)
  • extra_params => Opcional, Array asociativo

Ejemplo de entrada:

{ "phone":"123456", "name":"Manuel Diaz", "campaign_name":"Auto 3", "extra_params": { "empresa":"ITBX", "profesion":"Desarrollador" } }

11. Borrar todos los registros de una campaña AUTOMÁTICA

Descripción: Borra los registros disponibles y/o sin gestionar de una campaña automática (Predictiva y/o Progresiva).activa o inactiva,

Tipo de salida: 1 si es correcto o mensaje si hay un error

Ruta: https://api.itbx.co/api/v1/usuario/delContactsAuto

Método: POST

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • campaign_name => Requerido, String (ejemplo: Campaña automática)

12. Agregar contactos a campaña AUTOMÁTICA por archivo

Descripción: Agrega registros de contactos a una campaña automática activa (Predictiva y/o Progresiva) desde un archivo plano y/o hoja de calculo

Tipo de salida: JSON

Ruta: https://api.itbx.co/api/v1/usuario/uploadMassiveCampaign

Método: POST

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • campaign_name => Requerido, String (ejemplo: Auto 12)
  • file => Requerido, Archivo de excel (ods, xls, xlsx, csv) con el formato correcto (descargar aquí)

Ejemplo de salida sin errores:

{ "error": false, "msg": "Ok" }

Ejemplo de salida con errores:

{ "error": true, "msg": "Error: No existe la campaña" }

13. Consultar HISTÓRICO detallado del tráfico telefónico general

Descripción: Consulta todos los datos del reporte detallado o CDR del tráfico telefónico general (entrante y saliente), (por rango de tiempo y con limite de registros)

Tipo de salida: JSON

Ruta: https://api.itbx.co/api/v1/usuario/listCDR

Método: GET

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • startdate => Requerido, Fecha inicial (ejemplo: 2020-07-16 17:13:55)
  • enddate => Requerido, Fecha final (ejemplo: 2020-07-24 16:57:40)
  • offset => Opcional, Integer
  • limit => Opcional, Integer

Ejemplo de salida:

{
"totalcdrcount": 14462,
"cdrs": [
{
    "calldate": "2024-07-16T17:18:30-05:00",
    "src": "",
    "dst": "573142192812",
    "channel": "",
    "dstchannel": "SMS",
    "disposition": "ANSWERED",
    "uniqueid": "",
    "duration": 0,
    "billsec": 0,
    "accountcode": ""
}
]
}

14. Consultar HISTÓRICO detallado del tráfico telefónico entrante en colas inteligentes

Descripción: Consulta todos los datos del reporte detallado del tráfico telefónico entrante en colas inteligentes (por rango de tiempo)

Tipo de salida: Array asociativo

Ruta: https://api.itbx.co/api/v1/usuario/queueLog

Método: GET

Parámetros de entrada:

  • token => Requerido, String
  • startdate => Requerido, Fecha (ejemplo: 2020-07-16 17:13:55)
  • enddate => Requerido, Fecha (ejemplo: 2020-07-16 20:00:10)
  • queue => Opcional, Integer (ejemplo: 502)
  • event => Opcional, String ("COMPLETECALLER" o "EXITWITHTIMEOUT" o "ABANDON")
  • src => Opcional, String (ejemplo: 7777777)
  • agent => Opcional, String (ejemplo: Usuario 01)
  • nit => Opcional, String (ejemplo: 11106)
  • minWaittime => Opcional, Integer (ejemplo: 4)
  • minDuration => Opcional, Integer (ejemplo: 4)
  • minAbandon => Opcional, Integer (ejemplo: 4)

15. Crear campaña masiva de Whatsapp con mensajes HSM

Descripción: Crea una campaña de envío masivo de mensajes HSM de Whatsapp a múltiples destinos por medio de un (template) aprobado previamente en ITBX, (Previa aprobación Meta). Solo desde cuentas de Whatsapp oficiales.

Tipo de salida: JSON array con parámetros para cada teléfono (tel, msg, error, code). Cada teléfono tiene una respuesta: "error" = false si se lleva a cabo correctamente, de lo contrario, se considera error al enviar y "msg" contiene el mensaje del error correspondiente.

Ruta: https://api.itbx.co/api/v1/usuario/sendCampaignWA

Método: POST

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • telefonos => Requerido, String (ejemplo: 3178516770,3158536149,3145645677)
  • id_template => Requerido, Integer (ID de la plantilla a enviar)
  • usuario_proveedor => Requerido, String (Un nombre de usuario proporcionado por ITBX para la empresa)
  • token_proveedor => Requerido, String (Un token proporcionado por ITBX para la empresa)
  • template_variables => Requerido, String (Cadena con variables de la plantilla en orden de la forma:[variable1][variable2][variable3])
  • media => Requerido, String (Un enlace url. Ejemplo: https://contacto-virtual.com/multiagente/public/storage/whatsapptemplate/197_567_2023-11-297a543ddf02418e2ec5c04c125cdf3f43.png)

Ejemplo de salida:

[
{
"telefono": "123456",
"mensaje": "¿Aún necesitas ayuda?",
"codigo_respuesta": 1,
"mensaje_respuesta": "mensaje enviado",
"enviado": true
},
{
"telefono": "123456",
"mensaje": "Hola",
"codigo_respuesta": 1050,
"mensaje_respuesta": "El mensaje no coincide con la plantilla establecida",
"enviado": false
}
]

16. Consultar HISTÓRICO detallado de campaña masiva de Whatsapp con mensajes HSM

Descripción: Consulta todos los datos del reporte detallado con resultados de envío de una campaña masiva de Whatsapp con mensajes HSM (por rango de tiempo y con limite de registros)

Tipo de salida: JSON

Ruta: https://api.itbx.co/api/v1/usuario/getHistoricoMensajesWA

Método: GET

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • startdate => Requerido, Fecha inicial (ejemplo: 2020-07-16 17:13:55)
  • enddate => Requerido, Fecha final (ejemplo: 2020-07-24 16:57:40)
  • offset => Opcional, Integer
  • limit => Opcional, Integer

Ejemplo de salida:

{
"total": 2,
"mensajes": [
{
    "mensaje": "¿Aún necesitas ayuda?",
    "fecha_envio": "2022-05-02 18:21:54",
    "enviado": true,
    "codigo_respuesta": 4,
    "mensaje_respuesta": "error en el número de celular a enviar",
    "message_id_proveedor": null,
    "telefono_destino": "5731XXXXX"
},
{
    "mensaje": "Bienvenido",
    "fecha_envio": "2022-05-02 18:35:07",
    "enviado": true,
    "codigo_respuesta": 1,
    "mensaje_respuesta": "mensaje enviado",
    "message_id_proveedor": "743d402f-481d-42ca-82ca-e21aedfc860c",
    "telefono_destino": "573XXXXX"
}
]
}

17. Agregar contactos a campaña PREVIEW

Descripción: Agrega los datos de un nuevo contacto o registro a una campaña (Preview) activa.

Tipo de salida: 1 si es correcto o mensaje si hay un error

Ruta: https://api.itbx.co/api/v1/usuario/setNewContactPreview

Método: POST

Parámetros de entrada: Objeto JSON con los siguientes parámetros:

  • token => Requerido, String (ir a API Login)
  • phone => Requerido, String (ejemplo: 123456)
  • name => Requerido, String (ejemplo: John Doe)
  • id_campaign => Opcional, Integer (ejemplo: 1)
  • phone_office => Opcional, String (ejemplo: 123456)
  • cellphone => Opcional, String (ejemplo: 123456)
  • description => Opcional, String (ejemplo: Prueba de nuevo contacto)
  • schedule => Opcional, String
  • phone_list => Opcional, Array Asociativo
  • params => Opcional, Array Asociativo
  • id_subject => Opcional, Integer (ejemplo: 100)
  • id_relative => Opcional, Integer (ejemplo: 100)
  • campaign_name => Opcional, String (ejemplo: Campaña de prueba)

Ejemplo de entrada:

{ "phone":"123456", "name":"John Doe", "id_campaign":"", "phone_office":"123456", "cellphone":"", "description":"prueba", "schedule":"", "phone_list": { "Casa": 123456, "Empresa": 987456 }, "params": { "frecuencia" : "semanal", "dia": "lunes" }, "id_subject":"", "id_relative":"", "campaign_name":"Auto 3" }

18. Consultar los contactos de una campaña PREVIEW

Descripción: Consulta y trae todos los datos de los registros de una campaña (Preview) activa o inactiva

Tipo de salida: Array asociativo

Ruta: https://api.itbx.co/api/v1/usuario/getPreviewData

Método: GET

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • limit => Opcional, Integer (ejemplo: 10)

19. Borrar todos los registros de las campañas PREVIEW

Descripción: Borra los registros disponibles y/o sin gestionar de todas las campañas (Preview) activas o inactivas, (por rango de tiempo)

Tipo de salida: String (número de registros eliminados)

Ruta: https://api.itbx.co/api/v1/usuario/delPreviewRegs

Método: POST

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • date1 => Requerido, Fecha (ejemplo: 2020-01-01 10:00:05)
  • date2 => Requerido, Fecha (ejemplo: 2020-01-01 10:00:05)

Ejemplo de salida:

Deleted regs: 2

20. Consultar histórico de gestión de registros en una campaña PREVIEW

Descripción: Consulta reporte detallado de la gestión de registros en una campaña (Preview) activa o inactiva. (por rango de tiempo)

Tipo de salida: Array asociativo

Ruta: https://api.itbx.co/api/v1/usuario/getHistoryReport

Método: GET

Parámetros de entrada:

  • token => Requerido, String (ir a API Login)
  • date1 => Requerido, Fecha (ejemplo: 2020-01-01 10:00:05)
  • date2 => Requerido, Fecha (ejemplo: 2020-01-01 10:00:05)
  • campaign_name => Opcional, String
  • id_subject => Opcional, Integer
  • name => Opcional, String
  • phone_last_dialed => Opcional, String
  • agent_number => Opcional, String
  • agent_name => Opcional, String
  • status => Opcional, String
  • uniqueid => Opcional, Integer
Developed by itbx.co.