Communicator

ReferenciaS API

Aproveche todas las ventajas de nuestra plataforma, con los productos relacionados se puede obtener el máximo provecho y así conseguir de mejor manera cumplir con su tarea del día.

Las funciones disponibles son

Operación Donde Función Descripción
Contactos acl.asmx SetContact Permite crear contactos
Subir archivo a la base de datos del dominio communicator.asmx SetUploadFiletoDB Permite subir archivos directamente a la base de datos, se usa cuando se agregan los archivos como adjuntos.
Subir archivo físico communicator.asmx SetUploadFiletoPath Permite subir archivos al servidor dentro del dominio, usualmente para referenciarlos dentro de los mensajes como un vínculo que permita la descarga del archivo.
Mensajes communicator.asmx SetMessage Permite crear los mensajes

La relación entre funciones

La relación que existe entre las funciones es importante, debido a que se han estructurado para lograr el mejor rendimiento en la carga de los datos a la plataforma, por ejemplo, si en determinado escenario debe de enviarse un mismo archivo a todos los destinatarios, con las funciones de carga de archivos el proceso se hace una única vez, luego cuando se genera el envío, solamente debe de referenciarse aquellos archivos que se desea que vayan adjuntos o referenciados como vínculos en los mensajes.

Desde que la plataforma es capaz de enviar no solamente mensajes de correo electrónico, sino también SMS, es importante considerar el uso adecuado de la carga de datos a la plataforma, sabiendo el impacto en la utilización de recursos que conlleva una decisión acertada, por ejemplo, si se desea enviar el mismo archivo a todos los contactos, la mejor de las practicas implicaría, hacer la subida del mismo una única vez y luego solamente referenciarlo en la función de envío.

Descripción de las funciones

setContact
Campo Descripción Adicionales Obligatoria
strApiKey Llave de identificación del dominio Única por cada dominio Obligatoria
strApiUser Usuario Creado en la plataforma Obligatoria
strApiPassword Contraseña Obligatoria
strContactID Identificación del contacto
strName Nombre
strEmail Correo
strPhone Teléfono
strAddress Dirección
intBirthdayDay Día de cumpleaños
intBirthdayMonth Mes de cumpleaños
intBirthdayYear Año de cumpleaños
intInactive Indicador de Inactivo
strCategoryID Identificador de la categoría a la cual pertenece el contacto Estas pueden ser ninguna, una o más, separando por comas cada identificador
setUploadFileToDB
Campo Descripción Adicionales Obligatoria
strApiKey Llave de identificación del dominio Obligatoria
strApiUser Usuario Obligatoria
strApiPassword Contraseña Obligatoria
strFileName Nombre del archivo
bBuffer
lngOffset
intOverwrite
setUploadFileToPath
Campo Descripción Adicionales Obligatoria
strApiKey Llave de identificación del dominio Obligatoria
strApiUser Usuario Obligatoria
strApiPassword Contraseña Obligatoria
strToVirtualFolder

En caso de que se deje en blanco, el file queda en la carpeta default del dominio.

El valor se puede pasar como:“/Imágenes/Mercadeo”

strFileName
bBuffer
lngOffset
intOverwrite
setMessage
Campo Descripción Adicionales Obligatoria
strApiKey Llave de identificación del dominio Obligatoria
strApiUser Usuario Obligatoria
strApiPassword Contraseña Obligatoria
strType

Los valores posibles son:

  • SMS
  • EMAIL
strSubType

Cuando se usa strType EMAIL:

  • NONE

Cuando se usa strType SMS:

  • NONE
  • ALERT
strDatetime

Esta fecha debe dársele en formato de texto universal para fechas, que se construye como

YYYYMMDD HHmmss

  • 4 Dígitos para el año
  • 2 Dígitos para el mes
  • 2 Dígitos para el día
  • 1 Espacio en blanco
  • 2 Dígitos para la hora usando formato de 24 horas, por ejemplo 17 para las 5:00 PM
  • 2 Dígitos para los minutos
  • 2 Dígitos para los segundos
strTo

Este valor corresponde a la cuenta de correo o el número de teléfono celular según sea el caso indicado en strType.

Para el caso de envíos de correos electrónicos, este valor debe corresponder a los estándares relacionados a la estructura correcta en las cuentas de correo, para el caso de los números de teléfono, este debe corresponder a la estructura de país y numero, por ejemplo, 50660591516, es decir, Costa Rica, al número 60591516

strSubject
strMessage
intPriority La prioridad se define únicamente con 2 valores, 0 para prioridad normal 1 para alta prioridad.
strContactID
strAttachFilesIDs Estos son los valores generados en la función SetUploadFiletoDB, solo los valores generados de esta función son válidos.
strCampaignID Este valor es el identificador relacionado a la campana, es decir, al conjunto de mensajes que deseen agruparse, este valor se obtiene desde la interface de la plataforma, corresponde a un GUID.
strSMTPAccountID Este valor es la llave de identificación de la cuenta que desea usarse para hacer el envío, estas cuentas se crean en el panel de control de la PSI.
strFromAppID Este valor sirve para indicar el aplicativo que está haciendo el registro del mensaje, es de libre asignación y no debe superar los 36 caracteres de longitud.
strTableRef
strRefID

La descripción de escenarios sirve para ejemplificar diferentes situaciones a las que pueden estar expuestos los programadores al momento de hacer la integración con la PSI.

Ejemplo de integración de las funciones del ACL:

  • Escenario de Envío de SMS 
  • Escenario de Envío de Correo Electrónico

Escenario de Envío de SMS

En este primer escenario de envío, que es probablemente el escenario más simple de todos, el ejemplo se centra en hacer un envío sencillo de un SMS a un usuario.

Lo primero que hay que definir es si se desea registro de envíos relacionados al contacto, que puede ser consultado dentro de la plataforma, es decir, todos los envíos que se hagan asociándolos a contactos específicos, pueden ser consultados posteriormente en asociación con la información del contacto, también es posible hacer los envíos sin que tengan ninguna asociación a ningún contacto, esto por supuesto, dependerá del objetivo de los envíos que tenga la organización.

En caso de que se desee hacer envíos sin hacer la asociación con el contacto, por favor pase al siguiente paso de este escenario.

Paso 1:

Agregar o actualizar el contacto, al que se le va a hacer el envío, este paso es previo a hacer el envío propiamente, ya que la plataforma permite llevar registro de los contactos con gran detalle y además todos los envíos quedan asociados a estos contactos siempre que así se establezca por parte del programador.

Para agregar un contacto lo primero que se hace es usar la función SetContact descrita más arriba.

SetContact (‘Llave’,’User1’,’Pass123’,’1893682’,Percival Wallace’,’email@corporacion.com’,’50660591516’,’WA, 123 Well Street’,23,9,0,0,’’)

Con este ejemplo agregaremos a la base de datos DEMO, la cual tiene la llave de identificación única: ‘Llave’, usando el usuario ‘User1’ que tiene una contraseña ‘Pass123’, al contacto, cuyo Id seria ‘1893682’, su nombre seria ‘Percival Wallace’ el cual tiene el correo ‘email@corporacion.com’ y vive en WA, 123 Well Street, cuya fecha de nacimiento es el 23 de septiembre, pero del cual no conocemos el año; además 0 o 1 para indicar si debe quedar inactivo=1 y por último el ID de la categoría, si se desea, la cual se agrega el contacto, de lo contrario vacío.

Se hace esto con todos los contactos que deseemos agregar o actualizar en la base de datos, este paso es totalmente opcional y corresponde al criterio que cada organización tenga.

Una vez que el contacto está en la base de datos, procedemos a agregar por medio de la instrucción de envío el mensaje que deseamos.

Paso 2:

Procedemos entonces a usar la instrucción SetMessage.

SetMessage (‘Llave’,’User1’,’Pass123’,’SMS’,’NONE’,’20150923 140000’,’50660561516’,’’,’En este día tan especial deseamos darle nuestras felicitaciones por su cumpleaños’,0,’1893682’,’’,’’,’’,’AppMercadeo’)

Para los propósitos del ejemplo, estamos agregando un mensaje en la base de datos DEMO, la cual tiene la llave de identificación única para tal base de datos, ‘Llave’, usando el usuario ‘User1’ con contraseña ‘Pass123’, indicando que se trata de un mensaje de texto normal, ya que se indicó en strType el valor ‘SMS’ y en strSubType ‘NONE’, el mensaje se enviara el 23 de setiembre del 2015 a las 2:00PM, el mensaje se enviara al 506 60591516, con el texto “En este día tan especial deseamos darle nuestras felicitaciones por su cumpleaños”, para el caso de los envíos de SMS el texto que va en el campo strSubject se usa para seguimiento y reportería (puede ser igual al mensaje pero no debe exceder los 255 caracteres a diferencia del mensaje), la prioridad se establece como normal al usar el valor 0 y se va a asociar el mensaje al contacto de la base de datos que tenga el Id. 1893682 (opcional), los siguientes campos en el ejemplo se dejan en blanco, ya que no lleva files adjuntos, no se está asociando a una campana en específico, no se está usando una cuenta SMTP por ser mensajes de texto, el ultimo valor sirve como información de referencia para saber que aplicativo ejecuto esta instrucción, lo que resulta útil para casos donde hay diversas aplicaciones como, por ejemplo, el sistema de cobros, los sistemas de operaciones, transporte y otros.

Ejemplo PHP

http://php.greyphillips.com/GPWebServiceSample/