API SOAP – Conversation Webservice API

Web service SOAP que permite enviar conversaciones inteligentes a un contacto o un segmento de contactos predeterminado. Una conversación inteligente es un proceso automatizado de envío mensajes por diversos canales.

Acceso

Protocolo: HTTP

URL

Web Service https://appserv.danaconnect.com/api/ConversationWS
Definición del Web Service https://appserv.danaconnect.com/api/ConversationWS?wsdl

¿Cómo empezar a utilizar el Web Service?

La compañía que va a utilizar el Web Service debe contar con un usuario y contraseña válidos.
Por motivos de seguridad, el usuario que va a utilizar el Web Service debe contar con un permiso especial para el uso de las APIs de DANA.
La conversación que se va a enviar debe estar creada y activada en el sistema (con estatus “Activa”).
Es requisito indispensable que se haya predeterminado el segmento de contactos sobre el cuál actuará la conversación, y que se haya establecido la equivalencia de etiquetas con los campos correspondientes del segmento.

Autenticación

Para poder acceder a los métodos de este API es necesario tener credenciales válidas. Se utiliza un método de autenticación BASIC para el acceso a los WebServices basado en un login y password.

Login: El login consiste en el nombre de usuario concatenado con un @ y seguido del código de la compañía.

Ejemplo de autenticación desde PHP:

Nombre de usuario: administrador
Código de compañía: dana
Login => administrador@dana

$client = new SoapClient(“https://appserv.danaconnect.com/api/ConversationWS?wsdl”,
array( ‘login’ => ‘administrador@dana’,
‘password’ => ‘mipassword’,
‘authentication’ =>SOAP_AUTHENTICATION_BASIC));

Resumen de los métodos

startConversation

Activa una conversación a toda la lista o segmento pre-configurado.

Este método es utilizado generalmente luego de realizar una carga masiva de contactos, con el fin de activar la conversación hacia toda la lista.

String startConversation(Long idConversation)

startConversationWithData

Inserta la información de un contacto en una base de datos específica y envía una conversación inteligente a ese contacto.

String startConversationWithData(Long idConversation,
String tableCode,
StringMap values)

startConversationByIdRow

Activa una conversación de forma directa a un contacto previamente registrado en una lista.

String startConversationByIdRow(Long idConversation,
Long idContact)

startConversationWithDataId

Inserta la información de un contacto en una base de datos específica y envía una conversación inteligente a ese contacto. A diferencia de startConversationWithData, este retorna el Id del registro ingresado en la lista de contactos. También, este método no requiere que se especifique el código de la lista de contactos, ya que el mismo está implícito en la activación de la conversación.

Int startConversationWithDataId(Long idConversation,
StringMap values) values)

Pasos para agregar y enlazar una Base de Datos con una conversación para ser utilizada vía Webservice

Ya sea del modo startConversation o startConversationWithData es necesario realizar los siguientes pasos en la herramienta para poder enlazarla con un Web service SOAP:

1.- Agregue una nueva Base de Datos.

2.- Asigne el nombre a la Base de Datos.




3.- Agregue los campos necesarios para ser mapeados posteriormente en la conversación. Si la conversación contiene un nodo de Email, es necesario que la base de datos tenga un campo de email; de igual forma si tiene un nodo de llamada o SMS, es necesario un campo con el número telefónico.




Ejemplo en el caso de envíos de Mensajes de Texto:




4.- Incluya al usuario Webservice proporcionado por DANA en el equipo de trabajo.




5.- Asigne la permisología tal como se ve en la imagen.




6.- Cree la nueva conversación en el manejador de conversaciones de la herramienta.

7.- Incluya las etiquetas necesarias para hacer la correspondencia con los campos de base de datos creados.




8.- Incluya al usuario de Webservice proporcionado por DANA en el equipo de trabajo.




9.- Active la conversación, mapee los campos y en fecha y hora de envío, coloque la opción Webservice.




10.- Confirme los datos luego de mapear los campos y active la conversación.




11.- Ubique el ID de la conversación para colocarlo como parámetro en la llamada del método del Webservice.




12.- Finalmente, podemos invocar el web service con el método deseado.

Lo parámetros a enviar son los siguientes:

idCompany = demo;
login = gateway;
password = abcd1234;
idConversation = 22140;
tableCode = PRUEBAWS;

Nota: ¿cómo se visualiza el código de una tabla?

Para startConversationWithData, se deben pasar los códigos de los campos creados y el valor correspondiente a cada uno

values [0] = array ( ‘key’ => ‘PRUEBAWS_TELEFONOCELULAR’,
‘value’ => ‘04141234567’);
values [1] = array ( ‘key’ => ‘PRUEBAWS_MENSAJE’,
‘value’ => ‘04141234567’);
valuesMap[‘values’][‘entry’] = values;
dana = new SoapClient(‘http://appserv.danacrm.net:80/dana/conversation/ConversationWebServiceNoSSL?wsdl’);
args = array(‘idCompany’ => $idCompany,
‘login’ => $login,
‘password’ => $password,
‘idConversation’ => $idConversation,
‘tableCode’ => $tableCode,
‘values’ => $valuesMap);
result = dana->startConversationWithData(args)->return;

Nota: ¿Cómo se visualiza el Código de un Campo de una Lista de Contactos?

* Detalle de los métodos

*startConversation

Envía una conversación inteligente a un segmento o toda una lista de contactos.

*Sintaxis

public String startConversation(${color}[#000080](Long) idConversation)
throws InternalDanaException,
InvalidUserException,
InvalidAccessException,
InvalidCompanyException,
InvalidConversationException,
InvalidContactIdException,
InsufficientBalanceException,
RuntimeException)

*Parámetros

idConversation:	Identificador de la conversación inteligente que se desea enviar, la cual ha sido activada previamente en el sistema. El identificador de la conversación puede obtenerse de la aplicación Envío de Comunicaciones, accediendo al detalle de una conversación activa, y buscando el botón “i” de información ubicado a la derecha del nombre de la conversación.

*Valor devuelto

Retorna un string con los siguientes errores.

“OK”;
“ERROR – Internal error”;
“ERROR – Invalid login or password”;
“ERROR – Access denied”;
“ERROR – Invalid company”;
“ERROR – Invalid id contact”;
“ERROR – Invalid id conversation”;
“ERROR – Insufficient balance”;
“ERROR – Runtime error”;

*Excepciones

InternalDanaException – Si ocurrió un error interno.
InvalidUserException – Si el usuario o la clave son inválidos.
InvalidAccessException – Si el usuario no posee el permiso para ejecutar APIs de DANA.
InvalidCompanyException – Si no existe una compañía registrada con el identificador suministrado.
InvalidConversationException – Si no existe la conversación o no se encuentra activa en el sistema.
InvalidContactIdException – Si el contacto suministrado no existe en el segmento de contactos predeterminado para la conversación.
InsufficientBalanceException – Si la empresa no cuenta con el saldo suficiente para ejecutar la conversación.
RuntimeException – Si la petición no puede realizarse por falta de disponibilidad de la plataforma.

*startConversationWithData

Inserta la información de un contacto, contenida en un arreglo de valores, en una base de datos existente y envía una conversación inteligente a ese contacto.

Sintaxis


public String startConversationWithData (Long idConversation,
String tableCode,
StringMap values)
throws InternalDanaException,
InvalidUserException,
InvalidAccessException,
InvalidCompanyException,
InvalidConversationException,
InvalidTableOrColumnException,
InsufficientBalanceException,
RuntimeException)


Parámetros

idConversation:	Identificador de la conversación inteligente que se desea enviar, la cual ha sido activada previamente en el sistema. El identificador de la conversación puede obtenerse de la aplicación Envío de Comunicaciones, accediendo al detalle de una conversación activa, y buscando el botón “i” de información ubicado a la derecha del nombre de la conversación.

Valor devuelto

Retorna un string con los siguientes errores.

“OK”;
“ERROR – Internal error”;
“ERROR – Invalid login or password”;
“ERROR – Access denied”;
“ERROR – Invalid company”;
“ERROR – Invalid id contact”;
“ERROR – Invalid id conversation”;
“ERROR – Insufficient balance”;
“ERROR – Runtime error”;[/code]

Excepciones

_InternalDanaException_ – Si ocurrió un error interno.
_InvalidUserException_ – Si el usuario o la clave son inválidos.
_InvalidAccessException_ – Si el usuario no posee el permiso para ejecutar APIs de DANA.
_InvalidCompanyException_ – Si no existe una compañía registrada con el identificador suministrado.
_InvalidConversationException_ – Si no existe la conversación o no se encuentra activa en el sistema.
_InvalidContactIdException_ – Si el contacto suministrado no existe en el segmento de contactos predeterminado para la conversación.
_InsufficientBalanceException_ – Si la empresa no cuenta con el saldo suficiente para ejecutar la conversación.
_RuntimeException_ – Si la petición no puede realizarse por falta de disponibilidad de la plataforma.

Actualizado el: 24/11/2021