Documentación para Desarrolladores

Integración ITBX version 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 logueandose con las credenciales y se explica en este documento.

1. Loguear y obtener el token

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

Método: POST

Parámetros de entrada:

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

Tipo de salida: Json con Parámetros (access_token,token_type,expires_in)

Ejemplo de salida:

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

Uso: Se debe tener un token valido para realizar cualquier operación en el API. Se utiliza el access_token como parametro en cada consulta que se vaya a realizar. Este token actua como un api key que no tiene fecha de caducidad, y si se quiere desactivar un token debe usarse la funcion de eliminarlo.

2. Envio de SMS masivo

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

Método: POST

Parámetros de entrada:

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

Tipo de salida: Json array con Parámetros para cada telefono (tel,msg,error,code). Cada telefono 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.

Ejemplo de salida:

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

Uso: Se utiliza para enviar mensajes de texto masivo. En cada consulta solo se pueden enviar un lote de 100 mensajes.

3. setCallbackCampaign

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

Método: POST

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

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

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

Ejemplo de entrada:

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

Uso: Genera llamadas salientes a partir de una Campaña existente.

4. setNewContactPreview

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

Método: POST

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

  • token => String (ir a API Login)
  • phone => String (ejemplo: 123456)
  • name => String (ejemplo: John Doe)

Parámetros opcionales:

  • id_campaign => Integer (ejemplo: 1)
  • phone_office => String (ejemplo: 123456)
  • cellphone => String (ejemplo: 123456)
  • description => String (ejemplo: Prueba de nuevo contacto)
  • schedule => String
  • phone_list => Array Asociativo
  • params => Array Asociativo
  • id_subject => Integer (ejemplo: 100)
  • id_relative => Integer (ejemplo: 100)
  • campaign_name => String (ejemplo: Campaña de prueba)

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

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

Uso: Agrega un nuevo contacto a la lista de marcación, a campañas Preview.

5. getPreviewData

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

Método: GET

Parámetros de entrada:

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

Tipo de salida: Array asociativo

Uso: Muestra los registros ingresados con la función: setNewContactPreview.

6. getPreviewPhones

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

Método: GET

Parámetros de entrada:

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

Tipo de salida: Array asociativo

Ejemplo de salida:

array ( 0 => array ( 'id' => '11', 'id_calls' => '3', 'name' => 'Daniel', 'phone' => '654321', 'sincronizado' => '1', 'idg' => '10', ), 1 => array ( 'id' => '10', 'id_calls' => '3', 'name' => 'John Doe', 'phone' => '123456', 'sincronizado' => '1', 'idg' => '9', ), )

Uso: Muestra el listado de números telefónicos ingresados con la función: setNewContactPreview.

7. getPreviewParams

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

Método: GET

Parámetros de entrada:

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

Tipo de salida: Array asociativo

Ejemplo de salida:

array ( 0 => array ( 'id' => '11', 'id_calls' => '3', 'name' => 'dia', 'param' => 'lunes', 'flag_show' => '0', 'sincronizado' => '1', 'idg' => '11', ), 1 => array ( 'id' => '10', 'id_calls' => '3', 'name' => 'frecuencia', 'param' => 'semanal', 'flag_show' => '0', 'sincronizado' => '1', 'idg' => '10', ), 2 => array ( 'id' => '5', 'id_calls' => '2', 'name' => '', 'param' => '', 'flag_show' => '0', 'sincronizado' => '1', 'idg' => '5', ), 3 => array ( 'id' => '4', 'id_calls' => '1', 'name' => '', 'param' => '', 'flag_show' => '0', 'sincronizado' => '1', 'idg' => '4', ), )

Uso: Muestra los parámetros de la llamada preview ingresados con la función: setNewContactPreview.

8. delPreviewRegs

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

Método: POST

Parámetros de entrada:

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

Tipo de salida: String (numero de registros eliminados)

Ejemplo de salida:

Deleted regs: 2

Uso: Elimina registros de la tabla temporal (itbx_calls) de las campañas preview y devuelve la cantidad de registros eliminados.

9. getHistoryReport

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

Método: GET

Parámetros de entrada:

  • token => String (ir a API Login)
  • date1 => Fecha(ejemplo: 2020-01-01 10:00:05)
  • date2 => Fecha(ejemplo: 2020-01-01 10:00:05)
  • campaign_name => String
  • id_subject => Integer
  • name => String
  • phone_last_dialed => String
  • agent_number => String
  • agent_name => String
  • status => String
  • uniqueid => Integer

Tipo de salida: Array asociativo

Uso: Devuelve el reporte histórico de Campañas Preview.

10. delContactsAutos

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

Método: POST

Parámetros de entrada:

  • token => String (ir a API Login)
  • campaign_name => String (ejemplo: Campaña automatica)

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

Uso: Borra todos los contactos de una Campaña Automática.

11. setNewContactAuto

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

Método: POST

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

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

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

Ejemplo de entrada:

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

Uso: Agrega un nuevo número de contacto a una Campaña Automática.

12. getWebformIntegrationInfo

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

Método: GET

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

  • token => String (ir a API Login)
  • mail => String
  • subject => String

Tipo de salida: Array asociativo

Uso: Devuelve la información correspondiente a la integración Campañas ITBX con Formularios WEB (Gmail).

13. listCDR

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

Método: GET

Parámetros de entrada:

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

Parámetros opcionales:

  • offset => Integer
  • limit => Integer

Tipo de salida: JSON

Ejemplo de salida:

{ "totalcdrcount": 3, "cdrs": [ { "calldate": "2020-07-24T16:57:40-05:00", "src": "", "dst": "123456", "channel": "", "dstchannel": "SMS", "disposition": "ANSWERED", "uniqueid": "", "duration": 0, "billsec": 0, "accountcode": "" }, { "calldate": "2020-07-24T16:57:39-05:00", "src": "", "dst": "789456", "channel": "", "dstchannel": "SMS", "disposition": "ANSWERED", "uniqueid": "", "duration": 0, "billsec": 0, "accountcode": "" }, { "calldate": "2020-07-16T17:13:55-05:00", "src": "", "dst": "321654", "channel": "", "dstchannel": "SMS", "disposition": "ANSWERED", "uniqueid": "", "duration": 0, "billsec": 0, "accountcode": "" } ] }

Uso: Devuelve el reporte CDR (Call Detail Report) en formato JSON según el rango de fechas seleccionado.

14. queueLog

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

Método: GET

Parámetros de entrada:

  • token => String
  • startdate => Fecha (ejemplo: 2020-07-16 17:13:55)
  • enddate => Fecha (ejemplo: 2020-07-16 20:00:10)

Parámetros opcionales:

  • queue => Integer (Ejemplo: 502)
  • event => String ("COMPLETECALLER" o "EXITWITHTIMEOUT" o "ABANDON")
  • src => String(Ejemplo: 7777777)
  • agent => String(Ejemplo: Usuario 01)
  • nit => String(Ejemplo: 11106)
  • minWaittime => Integer(Ejemplo: 4)
  • minDuration => Integer(Ejemplo: 4)
  • minAbandon => Integer(Ejemplo: 4)

Tipo de salida: Array asociativa

Uso: Devuelve reporte de colas filtrado por fechas.

15. newCampaignSMS

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

Método: POST

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

  • token => String (ir a API Login)
  • arrayphones => Array asociativo(ejemplo: [ {"phone": 1234,"message":"mensaje de prueba 1"},{"phone": 123456,"message":"mensaje de prueba 2"}])
  • namecampaign => String(ejemplo: Campaña de prueba)
  • startdate => Fecha(ejemplo: 2020-09-08)
  • starthour => Hora formato 24H(ejemplo: 09:00:00)
  • endhour => Hora formato 24H(ejemplo: 16:05:00)
  • message => String(ejemplo: Mensaje de prueba)
  • callid => String(ejemplo: 317676789897)

Parámetros opcionales:

  • paused => Integer(1 para indicar que la campaña se genera en pausa)
  • duplex => Integer(1 para indicar que la campaña es duplex)

Tipo de salida: JSON con id de campaña

Ejemplo de salida sin errores:

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

Ejemplo de salida con errores:

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

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}

Uso: Crear una campaña de SMS normal o duplex.

16. editCampaignSMS

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

Método: POST

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

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

Parámetros opcionales:

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

Tipo de salida: JSON con id de campaña

Ejemplo de salida sin errores:

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

Ejemplo de salida con errores:

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

Ejemplo de entrada:

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

Uso: Editar una campaña de SMS.

17. deleteCampaignSMS

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

Método: POST

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

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

Tipo de salida: JSON

Ejemplo de salida sin errores:

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

Ejemplo de salida con errores:

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

Uso: Eliminar una campaña de SMS.

18. addCampaignNumbersSMS

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

Método: POST

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

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

Tipo de salida: JSON con id de campaña

Ejemplo de salida sin errores:

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

Ejemplo de salida con errores:

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

Ejemplo de entrada:

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

Uso: Crear una campaña de SMS normal o duplex.

19. uploadMassiveCampaign

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

Método: POST

Parámetros de entrada:

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

Ejemplo de salida sin errores:

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

Ejemplo de salida con errores:

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

Uso: Añadir uno o varios usuarios a una campaña automatica.

20. sendCampaignWA

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

Método: POST

Parámetros de entrada:

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

Tipo de salida: Json array con Parámetros para cada telefono (tel,msg,error,code). Cada telefono 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.

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

Uso: Se utiliza para enviar mensajes de Whatsapp masivos, solamente los mensajes de plantillas permitidos y aprobados por ITBX.

21. getHistoricoMensajesWA

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

Método: GET

Parámetros de entrada:

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

Parámetros opcionales:

  • offset => Integer
  • limit => Integer

Tipo de salida: JSON

Ejemplo de salida:

{"total":2,
"mensajes":[{"mensaje":"¿Aun necesitas ayuda?","fecha_envio":"2022-05-02 18:21:54","enviado":true,"codigo_respuesta":4,"mensaje_respuesta":"error en el numero 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"},
]}

Uso: Devuelve el historico de mensajes de WA enviados.

22. getHistoricoMensajesSMS

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

Método: GET

Parámetros de entrada:

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

Parámetros opcionales:

  • offset => Integer
  • limit => Integer

Tipo de salida: JSON

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"}]}

Uso: Devuelve el historico de mensajes de WA enviados.

23. eliminarToken

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

Método: POST

Parámetros de entrada:

Tipo de salida: JSON

Ejemplo de salida:

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

Uso: Elimina el token proporcionado.

Developed by itbx.co.
Copyright © 2008 - 2023 ITBX UC Series | (Self Hosted & Cloud Solutions) All Rights Reserved.