logo
Desarrollo
ResumenEspacioDesarrolloEspacioTrabajoReferenciaAPIMejoresPrácticasRegistroCambios
Buscar
Español
EspacioDesarrollo / Agente / Integración / ZohoSalesIQ
Zoho Sales IQ
Última actualización：en alrededor de 8 horas

Zoho Sales IQ

Se puede integrar el servicio del agente en Zoho Sales IQ, lo que permite a los usuarios de Zoho Sales IQ comunicarse con el agente desde Zoho Sales IQ.

Preparación

Antes de la integración, se deben configurar algunos parámetros en Zoho, que se utilizarán durante el proceso de integración con GPTBots.

Crear ID de cliente (Client ID)

  1. Iniciar sesión en la Zoho API Console

    Nota: Si la cuenta no está basada en la región US, debe cambiarse el dominio. Para obtener más información, consultar:

    Data Center Developer Console
    US (Estados Unidos) https://api-console.zoho.com/add
    EU (Europa) https://api-console.zoho.eu/add
    IN (India) http://api-console.zoho.in/add
    AU (Australia) http://api-console.zoho.com.au/add
    CN (China) http://api-console.zoho.com.cn/add
    JP (Japón) http://api-console.zoho.jp/add

  2. Si ya se dispone de una aplicación (Application) disponible, acceder a la aplicación correspondiente, hacer clic en Client Secret y copiar el Client ID y el Client Secret correspondientes. Se utilizarán en la configuración de integración de GPTBots.

    image-20250507153254209

  3. Si no se dispone de una aplicación (Application) disponible, hacer clic en ADD CLIENT en la esquina superior derecha y crear un cliente (Client) adecuado según el tipo de aplicación.

    image-20250507153127149

    image-20250507153459912

  4. Si se crea una aplicación (Application) nueva, completar el nombre de dominio del servicio actual en la Homepage URL y, en Authorized Redirect URIs, completar el nombre de dominio del servicio actual + /api/console/bot/zoho/salesiq/redirect. Hacer clic en CREATE. Tras crearse correctamente, el sistema generará un Client ID y un Client Secret. Copiar el Client ID y el Client Secret correspondientes, que se utilizarán en la configuración de integración de GPTBots.

    image-20250507160039517

Nota: Un Client ID puede autorizarse correctamente hasta 20 veces de forma simultánea. Si se supera este límite de 20, la autorización de Zoho del primer agente autorizado dejará de ser válida.

Configuración de la integración

  1. Iniciar sesión en GPTBots.

  2. Acceder a la organización, seleccionar el agente correspondiente, guardar la versión y hacer clic en Publish. Tras publicarse correctamente, hacer clic en Integrations.

    image-20250225121541516

  3. Seleccionar Zoho Sales IQ como método de integración.

    image-20250507163753173

  4. Completar los siguientes parámetros:

    • Client ID y Client Secret: obligatorios; se obtienen durante la fase de preparación;
    • Screen Name: obligatorio; se obtiene de la página de la cuenta con la sesión iniciada. Se toma la primera cadena de la ruta después del nombre de dominio. Por ejemplo, en la dirección https://salesiq.zoho.com/gptbos/mychats/000000000000003, el Screen Name es gptbots;
    • Email: obligatorio; el correo electrónico vinculado al perfil de la cuenta de Zoho;
    • Server Region: seleccionar la región de la cuenta de Zoho;
    • Public Key: opcional; si se habilita Secure your webhook en la configuración posterior del webhook, primero hacer clic en Integration y luego volver para completarlo. Si no se habilita, no es necesario.

    image-20250507164140213

  5. Tras hacer clic en Integration, aparecerá una ventana emergente con el estado de autorización. Hacer clic en Accept.

    image-20250507165858728

  6. Tras autorizarse correctamente, GPTBots generará una dirección URL de webhook. En este punto, se debe acceder a la página Setting.

    image-20250507172323517

  7. Acceder sucesivamente a Workflows - Data Workflows y hacer clic en Add (View) en la esquina superior derecha.

    Nota: En algunas versiones de cuenta esta entrada se muestra como Webhooks - Data modifications; ambas cumplen la misma función.

    alt text

    alt text

    alt text

  8. Completar el contenido del webhook:

    • Brand: seleccionar la marca que recibirá los Workflows (Webhook). Debe coincidir con la marca que utilizan realmente los visitantes, es decir, la marca a la que pertenece el código de instalación del widget insertado en el sitio web. Si aquí se selecciona una marca incorrecta, los eventos generados por esas conversaciones no activarán este Workflow y GPTBots no recibirá ningún mensaje.

    • Module: seleccionar Conversation

    • URL to be invoked: completar la URL del webhook obtenida en la configuración de integración de GPTBots. Copiarla directamente desde la página de configuración de integración; no copiar la dirección de otro entorno, ya que de lo contrario los mensajes se enviarán a otro entorno.

    • Events: es imprescindible marcar simultáneamente conversation.created y conversation.visitor.replied; ninguno de los dos puede faltar:

      • conversation.created: notifica a GPTBots cuando se crea una nueva conversación, y GPTBots la toma (pick up) a partir de esta notificación;
      • conversation.visitor.replied: notificación de cada mensaje posterior del visitante. Al procesar este evento, GPTBots verifica la pertenencia de la conversación; si la toma de la conversación no se completó por faltar conversation.created, todos los mensajes posteriores del visitante se descartarán.

      GPTBots no procesa el resto de tipos de eventos; marcarlos no tendrá ningún efecto.

    • Action: seleccionar Webhook

    Tras completar, hacer clic en Create webhook.

    alt text

    ⚠️ Nota: Aquí, en Webhook URL, debe completarse la Webhook URL generada en la página de configuración de integración. No es la misma dirección que la dirección de callback utilizada en el escenario «Servicio humano - Other to Zoho Sales IQ» (/api/console/human/callback/zoho/salesiq/event); tienen usos distintos y mezclarlas provocará que los mensajes se descarten. Si se van a utilizar ambos escenarios, crear una Data Workflow independiente para cada uno.

  9. Secure your webhook: paso opcional. Se puede elegir si se verifica la seguridad del webhook (si procede de la fuente oficial y no es una solicitud falsificada). Después de habilitarlo, hacer clic para generar una clave pública, copiar la clave pública marcada como In Use y completarla en la página de configuración de integración de GPTBots.

    image-20250507173308438

Comunicarse con el agente en Zoho Sales IQ

Tras configurarse correctamente la integración, se puede conversar con el agente en el servicio de Zoho.
image-20250507182819135

Preguntas frecuentes

1. No se puede crear la conversación y aparece el mensaje Live chat has been disabled

Cuando la función de chat en vivo de la marca correspondiente está desactivada en el lado de Zoho, Zoho rechaza la creación de la conversación y devuelve este error. Comprobar lo siguiente:

  1. Acceder a Settings - Brands y confirmar que el estado de la marca objetivo es Active (el interruptor situado en el extremo derecho de la lista está activado); si la marca está desactivada, no se podrá crear ninguna conversación bajo ella;
  2. Acceder a Configurations - Channels de esa marca y confirmar que el interruptor de Live chat está activado;
  3. Confirmar que el departamento (Department) seleccionado no está desactivado.

Si no se encuentra el interruptor de Live chat en Configurations, normalmente se debe a que esta capacidad está desactivada a nivel del plan de la cuenta de Zoho; en ese caso, contactar con el soporte oficial de Zoho.

2. Al enviar mensajes desde el widget de Zoho, el escritorio de soporte de Zoho los recibe, pero el agente no responde en absoluto

Primero, entender una premisa: tras recibir el webhook de Zoho, GPTBots devuelve éxito inmediatamente y luego lo procesa de forma asíncrona. Por lo tanto, incluso si el mensaje se descarta en el lado de GPTBots, la columna Failures sigue siendo 0 en la lista de Data Workflows de Zoho, por lo que Failures no sirve para determinar si hay un problema. El único criterio válido es la columna Last Triggered.

Paso 1: usar Last Triggered para distinguir en qué lado está el problema

Acceder a Settings - Workflows - Data Workflows, localizar la entrada que apunta a la Webhook URL de la integración y consultar Last Triggered. Tener en cuenta que esta columna muestra la hora de la zona horaria de la cuenta de Zoho, que puede diferir varias horas de la hora local; convertirla antes de comparar.

  • Está vacía o no corresponde a la hora en que se acaba de enviar el mensaje → Zoho no llegó a enviar la solicitud; el problema está en el lado de Zoho (ver A más abajo);
  • Corresponde exactamente a la hora en que se acaba de enviar el mensaje → la solicitud se envió; el problema está en las condiciones de procesamiento del lado de GPTBots (ver B más abajo).

A. Lado de Zoho: el Workflow no se activó

  1. El interruptor situado en el extremo derecho de ese Workflow está en estado ENABLED (verde);

  2. Brands incluye la marca que utilizan realmente los visitantes: abrir esa conversación y, en la parte superior de la página de detalles de la conversación, se puede ver el nombre de la marca a la que pertenece; usarlo para comparar. Esta es la causa más frecuente: el widget instalado corresponde a la marca A, mientras que el Workflow está vinculado a la marca B, por lo que el evento nunca se activará;

  3. Module es Conversation;

  4. Events incluye simultáneamente conversation.created y conversation.visitor.replied.

    Nota: El Workflow del escenario «Servicio humano - Other to Zoho Sales IQ» marca conversation.operator.replied / conversation.completed, y los mensajes de los visitantes no lo activan. Tener ese Workflow no significa que el escenario de integración funcione; cada escenario necesita su propio Workflow.

B. Lado de GPTBots: la solicitud se recibió pero se descartó

  1. La URL corresponde al escenario equivocado: el escenario de integración usa /api/console/bot/integration/chat/zoho/salesiq/{clientId} y el escenario de servicio humano usa /api/console/human/callback/zoho/salesiq/event. Si se intercambian, el mensaje se descartará por no encontrar la configuración correspondiente, y en el lado de Zoho seguirá mostrándose como exitoso;
  2. La URL apunta a otro entorno: confirmar que el dominio coincide con el entorno que se está utilizando actualmente;
  3. Se habilitó Secure your webhook pero no se completó la Public Key: una vez habilitado, Zoho firma cada callback; si la Public Key está vacía en el lado de GPTBots, la verificación fallará inevitablemente y la solicitud se descartará. Durante la depuración se recomienda desactivar primero esta opción;
  4. El agente no está publicado: el canal de integración lee la versión publicada; si el agente nunca ha publicado una versión, los mensajes se descartarán. Guardar primero la versión y hacer clic en Publish;
  5. La conversación fue tomada por otro operador: el escenario de integración exige que la conversación pertenezca a la cuenta de Zoho correspondiente al Email indicado en la configuración de integración. Si otro operador toma manualmente la conversación, los mensajes posteriores del visitante dejarán de reenviarse al agente;
  6. La autorización ha caducado: volver a la página de configuración de integración de GPTBots y confirmar que el estado de autorización es correcto. Cuando un mismo Client ID se autoriza correctamente más de 20 veces, el agente autorizado más antiguo deja de ser válido (ver el aviso anterior) y es necesario volver a autorizar.

3. Zoho recibe los mensajes, pero las respuestas del agente humano no llegan de vuelta

Este es el fenómeno típico de «comunicación unidireccional», causado porque el webhook no está en vigor. Comprobar lo siguiente:

  1. Acceder a Settings - Workflows - Data Workflows y confirmar que el estado del Workflow correspondiente es ENABLED;
  2. Confirmar que las Brands seleccionadas en el Workflow coinciden con la marca utilizada realmente;
  3. Confirmar que en Events se han marcado los eventos necesarios y que la URL completada es la dirección del escenario correspondiente (las direcciones del escenario de integración y del escenario de servicio humano son distintas; ver el aviso del paso 8 anterior);
  4. Consultar la columna Last Triggered de la lista; si siempre está vacía o la hora no coincide con esta conversación, significa que el evento nunca se activó, por lo que hay que revisar la configuración anterior. La columna Failures no sirve como criterio de diagnóstico (el motivo se explica en la pregunta frecuente anterior).

4. Los callbacks fallan tras habilitar Secure your webhook

Tras habilitar esta opción, Zoho adjunta una firma a cada callback. Si en el lado de GPTBots no se ha completado la Public Key correspondiente, la verificación de la firma fallará y la solicitud será rechazada. Copiar la clave pública marcada como In Use en Zoho a la página de configuración de integración de GPTBots; durante la depuración también se puede desactivar primero esta opción para verificar la conectividad del enlace.