Saltar al contenido principal

Artículo actualizado: 4 de febrero de 2022

API de Sparkcentral CRM

La integración de Sparkcentral CRM le permite extraer los datos de contacto de los clientes de los CRM u otras aplicaciones comerciales internas en Sparkcentral. Para integrar su CRM con Sparkcentral, debe proporcionar un punto de enlace HTTPS para las búsquedas. También puede proporcionar un punto de enlace HTTPS opcional para gestionar las solicitudes de reescritura y un punto de enlace HTTP para que Sparkcentral envíe notificaciones desde nuestra aplicación a su CRM.

Seguridad y autenticación

Al enviar o recibir datos de Sparkcentral, proporcionamos dos opciones de autenticación. Ambos mecanismos están implementados para que pueda asegurarse de que la solicitud se origina en Sparkcentral.

Secreto compartido

Cuando eliges el mecanismo de secreto compartido y configuras una URL, se te da un secreto. Con el secreto dado, puede calcular la firma que le permite verificar que la llamada se originó en Sparkcentral. Con este mecanismo, cada solicitud de Sparkcentral contiene el encabezado X-Sparkcentral-Signature. A continuación, se muestra un ejemplo de solicitud:

Dupdo

curl -X POST https://sparkcentral-lookup -H 'tipo de contenido: aplicación/json' -H 'aceptar: aplicación/json' -H 'X-Sparkcentral-Signature: e6f93239a06e46ae9654fc9ad2fb4e1cc4eb213830a0d94e711570c047e43c57' -d '{"email":"fj@example.com"}'

La firma se genera utilizando el algoritmo HMAC-SHA256 con el secreto compartido y el cuerpo de la solicitud. Utilice su secreto para calcular la firma y comparar con la firma dada. Tanto la clave secreta que recibió como la firma están codificadas como cadenas hexadecimales. Asegúrese de convertir el secreto compartido de su representación hexadecimal a su formato binario antes de usarlo. La mayoría de los idiomas vienen con bibliotecas listas para usar para verificar esta firma. Por ejemplo, así es como se ve en JavaScript:

Dupdo


const crypto = requerir ("criptografía");
const sparkCentralSecret ="... ";//¡no compartas!
const expectedSignature = request.headers ["X-Sparkcentral-Signature"];
const actualSignature = crypto
.createHMAC ("sha256 ", buffer.from (SparkCentralSecret," hexadecimal"))
.update (request.body," utf-8")
.digest ("hexadecimal");
if (ActualSignature! == Firma esperada){
                throw new createError.Unauthorized("X-Sparkcentral-Signature wrong");
                }
console.log (JSON.parse (solicitud.cuerpo) .correo electrónico);

OAuth

Si sus puntos finales admiten OAuth2, puede configurar las credenciales de su cliente, una URL de token y, opcionalmente, un alcance en Sparkcentral.

Usamos el flujo de credenciales de cliente de OAuth2 para autenticarnos en su CRM. La URL del token es el punto final en el que podemos autenticarnos con estas credenciales y recuperar un token de acceso. Para realizar las solicitudes de búsqueda, escritura o notificación reales, utilizamos el token en el encabezado de autorización para autenticar.

Buscar

Crear atributos de contacto

  1. En Sparkcentral, vaya a Configuración de administración, expanda Espacio de trabajo del agente, seleccione Atributos de contacto y, a continuación, seleccione Agregar atributo.
  2. En el cuadro Editar atributo, seleccione Administrado por CRM. El CRM es la fuente de la verdad de estos atributos. Una vez importados a Sparkcentral, solo cambian cuando el valor cambia en el CRM.
  3. Identifique los atributos de búsqueda seleccionando Usar como atributo de búsqueda. El CRM los utiliza para encontrar los datos de un cliente. Por ejemplo, si desea buscar un cliente por dirección de correo electrónico, cree un atributo llamado «Correo electrónico» y designarlo como una búsqueda. Cuando la solicitud se realiza desde Sparkcentral a su CRM, los campos de búsqueda se incluyen en el cuerpo de la solicitud.
  4. Crea un alias para el atributo. En el cuadro Identificador único, introduzca un alias para el atributo de búsqueda. Se usa para asignar la respuesta de su sistema al atributo.

Configurar la URL de integración

Para extraer datos de su CRM en Sparkcentral, debe implementar un punto de enlace POST que acepte una solicitud JSON y devuelva una respuesta JSON. La solicitud contiene los atributos de búsqueda y la respuesta debe contener los datos de contacto de su CRM

Después de implementar ese punto final, configúrelo como la URL de búsqueda:

  1. Ve a Configuración de administración.

  2. Expanda la integración y las API.

  3. Selecciona CRM.

Manejar la solicitud

Cuando el punto final de su sistema esté listo y configurado en Sparkcentral, y se hayan identificado uno o más atributos de búsqueda, puede realizar una solicitud a través del botón Buscar en la vista de conversación.

Después de realizar la búsqueda en el sistema, devuelva los atributos a Sparkcentral como respuesta JSON. Las claves del objeto attributes corresponden a los alias que se agregaron anteriormente en Sparkcentral. Si falta un atributo administrado por CRM en el objeto o la clave tiene un valor nulo, su valor se elimina en Sparkcentral. Sparkcentral espera la respuesta en este formato:

Respuesta 200 (aplicación / json)

Dupdo
{
"autoConfirm": falso,
"atributos": {
"email": "fj@example.com",
"id": "98765432",
"first_name": "Fred",
"last_name": "Jones",
"last_order_number": null
}
}

Confirma tus atributos

Los atributos de CRM devueltos en la respuesta deben confirmarse antes de que se guarden en Sparkcentral. Hay dos maneras de hacerlo:

  • Seleccione el botón Confirmar cuando vea los atributos de CRM que se muestran en Sparkcentral después de la solicitud de búsqueda.
  • Añada un campo AutoConfirm a la respuesta:

Respuesta 200 (aplicación / json)

Dupdo
{
"autoConfirm": verdadero,
"atributos": {
"email": "fj@example.com",
"id": "98765432",
"first_name": "Fred",
"last_name": "Jones"
}
}

El autoConfirm le dice a Sparkcentral que guarde automáticamente los atributos sin tener que usar el botón Confirmar.

Respóndeme

Puede recibir una notificación cada vez que haya tenido lugar una conversación en Sparkcentral o un agente establezca una conversación actual en estado pendiente. Esto le permite guardar los detalles de la conversación en su sistema CRM existente. Otros casos de uso incluyen la activación de encuestas CSAT, la creación de casos y la información ampliada del cliente a partir de perfiles de redes sociales.

Configurar la URL de reescritura

Para insertar datos de Sparkcentral en su CRM, debe implementar un punto de enlace POST que acepte una solicitud JSON y devuelva una respuesta JSON. La solicitud contiene carga útil de escritura, y el código de estado de la respuesta representa su capacidad para analizar la carga útil y la capacidad del CRM para ingerir los datos

Configure el punto final como la URL de reescritura:

  1. Ve a Configuración de administración.

  2. Expanda la integración y las API.

  3. Selecciona CRM.

Manejar la solicitud

Cuando el punto final de su sistema está listo y configurado en Sparkcentral, y se producen eventos relevantes dentro de Sparkcentral, las solicitudes se envían al punto final configurado. Todas las cargas útiles de reescritura descodificadas tienen los siguientes campos:

  • type: cadena que define qué tipo de solicitud de reescritura se está procesando. Se utiliza para sugerir la estructura del campo de datos.
  • versión: Un número que designa la versión del type de solicitud. Se utiliza para marcar cambios en la estructura del campo de data
  • idempotencyKey: una cadena que identifica de forma única cada evento para volver a escribir. Se utiliza para ayudar a garantizar que cada solicitud se procese solo una vez.
  • data: un objeto que contiene datos estructurados para el tipo específico de reescritura. Por ejemplo, un evento de tipo CONVERSATION_RESOLVED tiene campos como medio, canal, mensajes*, notas, temas, contactProfile*, atributos* y agente, entre otros.

* Se aplica a todos los medios excepto Twitter. El identificador de Twitter, los tweets y las transcripciones de mensajes directos, y los atributos de contacto del medio de Twitter (nombre de Twitter, número de seguidores, etc.) no se envían en la carga útil, para cumplir con las políticas de uso de datos de Twitter.

Eventos CONVERSATION_RESOLVED y CONVERSATION_SET_TO_PENDING

Los eventos con un tipo de "CONVERSATION_RESOLVED" o "CONVERSATION_SET_TO_PENDING" tienen la siguiente estructura de data

Dupdo
{
"marca de tiempo": "2021-04-28T09: 43: 26.635984618Z",
"idempotencyKey": "6ebc6a78-d9e9-48be-b172-51eda40b7af8",
"versión 1,
"tipo": "CONVERSATION_RESOLVED",
"datos": {
"conversación": {
      "id": "0ad42eef-a806-11eb-9642-f1ceb2f21def",
      "createdAt": "2021-04-28T09:42:27.004817183Z",
      "previousStatus": "new",
      "currentStatus": "resolved"
    } ,
"medio": {
      "id": "smooch-whatsapp"
    } ,
"canal": {
      "id": "0-02534c5ac04-000-261ad914",
      "name": "channelname"
    } ,
"agente": {
      "id": "11599",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@Hootsuite.com"
    } ,
"contactProfile": {
      "id": "693ed54b-a426-11eb-9363-cffd945b4b2f",
      "mediumContactProfileId": "bb7b0f8f00cc989b97f0725b",
      "primaryIdentifier": "John Smith",
      "secondaryIdentifier": "+32439487192",
      "pictureUrl": null
    } ,
"statusUpdatedReason": "5fd023f6-2e66-11eb-be07-092841b0717d - No se requiere respuesta",
"statusUpdatedComment": "no es una pregunta",
"statusUpdatedAt": "2021-04-28T09: 43: 26.532948586Z",
"mensajes": [
{
        "id": "0ad20c0d-a806-11eb-9642-f799d0e531de",
        "direction": "INBOUND",
        "text": "Figuur"
      } ,
{
        "id": "10664516-a806-11eb-9642-fbd9d431bd78",
        "direction": "OUTBOUND",
        "text": "dsghkjsdgmhlknsdmglhkjmsdlgkhjmsdgkljhlmdkgjh"
      }
],
"contactAttributes": [
{
        "attribute": "smooch-whatsapp-profile-name",
        "value": "John Smith",
        "source": "MEDIUM"
      } ,
{
        "attribute": "smooch-whatsapp-phone-number",
        "value": "+32471263345",
        "source": "MEDIUM"
      } ,
{
        "attribute": "email",
        "value": "john.smith@Hootsuite.com",
        "source": "CRM_CONFIRMED"
      } ,
{
        "attribute": "first_name",
        "value": "John",
        "source": "CRM_CONFIRMED"
      } ,
{
        "attribute": "last_name",
        "value": "Smith",
        "source": "CRM_CONFIRMED"
      } ,
{
        "attribute": "company",
        "value": "Hootsuite",
        "source": "CRM_CONFIRMED"
      } ,
{
        "attribute": "spark-language",
        "value": "nl",
        "source": "CRM_CONFIRMED"
      }
],
"notas": [],
"temas": []
}
}

Volver a escribir reintentar

Si se agota el tiempo de espera de la solicitud de reescritura o el punto final devuelve un código de estado sin éxito (2XX), Sparkcentral vuelve a intentarlo con retrocesos exponenciales. Las solicitudes se vuelven a enviar con un retraso de 1, 2, 4, 8, 16 y 32 horas después de cada reintento (un total de 6 solicitudes), siempre y cuando la solicitud no se realice correctamente. Si la solicitud sigue sin tener éxito después de 6 solicitudes, almacenamos los detalles de la solicitud fallida para referencia futura. Le recomendamos que inspeccione los registros del punto final con regularidad para asegurarse de que las solicitudes de reescritura se procesen correctamente la primera vez. Para distinguir entre eventos únicos, a cada solicitud se le da una clave de idempotencia.

Clave de idempotencia

Las solicitudes de reescritura de Sparkcentral utilizan una clave de idempotencia, que permite que el punto final de reescritura se asegure de que procesa cada solicitud una vez. Esta clave ayuda cuando las solicitudes se envían varias veces durante el programa de reintentos, por lo que el punto final puede manejar las solicitudes de una manera idempotente. La clave es única por solicitud.

Notificación

Configurar URL de notificación

Cuando envía sus atributos de contacto administrados de CRM, Sparkcentral valida la respuesta. Para ver los errores de validación, hemos proporcionado una forma de enviar notificaciones de Sparkcentral a su sistema. Debe proporcionar un punto de enlace POST que acepte un cuerpo de solicitud JSON. Configure una URL de notificación en la misma pantalla en la que configuró una URL de búsqueda:

  1. Ve a Configuración de administración.

  2. Expanda la integración y las API.

  3. Selecciona CRM.

Manejar la solicitud

Cuando se producen errores de validación, Sparkcentral envía una solicitud a la URL de notificación configurada. Una solicitud tiene este aspecto:

Dupdo
{
"timestamp": "2019-01-30T15:49:10.630397Z",
"version": 1,
"eventType": "DATA_IMPORT_ERROR",
"messages": [
"testMessage1 key:testKey1 value:testValue1",
"testMessage2 key:testKey2 value:testValue2"
]
}

La solicitud contiene estos dos campos:

  • tipo de evento
  • mensajes : una serie de mensajes de error explícitos

Los siguientes son los tipos de eventos que Sparkcentral puede enviar.

tipos de eventos
Tipo de evento Descripción
DATA_IMPORT_ERROR Se ha producido un error al extraer datos del CRM a Sparkcentral.

La respuesta a esta solicitud puede ser 204. Sparkcentral no espera nada en el cuerpo de respuesta.

Otras acciones

Actualizar

El botón Actualizar en la Vista de conversación recupera los atributos administrados del CRM. Debido a que estos atributos se confirmaron previamente, el paso de confirmación no es necesario.

Desconectar

El botón Desvincular en la Vista de conversación elimina los atributos administrados de CRM de Sparkcentral.

Confirmar

El botón Confirmar almacena la información validada asociada del CRM a la base de datos de Sparkcentral.

Claro

El botón Borrar restablece los datos extraídos por el punto final de búsqueda.

 

¿No encuentras lo que buscas? Estamos aquí para ayudar