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:
- token => String (ir a API Login)
Tipo de salida: JSON
Ejemplo de salida:
{ "error": false, "data": "Token revocado" }
Uso: Elimina el token proporcionado.