Comenzando con el Salesbot

Para comenzar, necesitas conectar la integración con los chats en la columna izquierda del Pipeline digital. Encontrarás instrucciones para cada mensajero en la ventana de configuración. Después de conectar la integración de chat, podrás activar el Salesbot para gestionar los nuevos chats entrantes, así como configurar bots para etapas específicas.

Configurar el Salesbot

Puedes conectar el Salesbot de dos maneras::

Dirígete a la sección Leads ➡️ Automatiza ➡️ selecciona una etapa ➡️ Agregar disparador ➡️ elige Salesbot.

Luego, selecciona Crear un nuevo bot. Cuando se abre la ventana modal, puedes elegir una plantilla estándar o crear un bot nuevo.

Ve a la seccion Ajustes ➡️ pestaña Herramientas de comunicacion ➡️ Salesbots ➡️ Crear o importar un nuevo bot.

Al abrir la ventana modal con los pasos de Salesbot, puedes hacer clic en Ver fuente para ver el código del bot.

Los leads que ingresaron a la etapa antes de que la acción apareciera en el Pipeline digital serán ignorados, a menos que marques la opción Aplicar a todos los leads en esta etapa.

Idioma del Salesbot

El Salesbot utiliza un objeto JSON estructurado con claves específicas. El ejemplo a continuación hará la pregunta, "Por favor, ingresa tu número de teléfono y correo electrónico" y configurará la etiqueta "salesbot". Luego de que el usuario responda, se validarán los datos y se responderá con uno de los mensajes especificados. Para más detalles sobre los presets, por favor dirígete a la siguiente sección.

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "text",
                    "value": "Por favor, ingresa tu número de teléfono y correo electrónico"
                }
            },
            {
                "handler": "action",
                "params": {
                    "name": "set_tag",
                    "params": {
                        "type": 2,
                        "value": "salesbot"
                    }
                }
            }
        ],
        "answer": [
            {
                "handler": "preset",
                "params": {
                    "name": "contacts.validate_base_info",
                    "params": {
                        "empty_email": "Por favor, ingresa tu correo electrónico",
                        "empty_phone": "Por favor, ingresa tu numero de teléfono",
                        "invalid_phone": "Parece que el número de teléfono puede ser incorrecto",
                        "success": "Gracias",
                        "empty_all": "Por favor, ingresa tu número de teléfono y correo electrónico"
                    }
                }
            }
        ]
    }
]

El objeto debe contener las claves "question", "answer", o "finish".

Los datos en el objeto "question" manejan las acciones que ocurrirán cuando se envíe un mensaje al usuario.
Los datos en el objeto "answer" gestionan las acciones que se llevarán a cabo cuando el usuario responda.
Los datos en el objeto "finish" definen las acciones que ocurrirán cuando el bot haya terminado.

📘
Pueden existir múltiples claves. Sin embargo, hay una limitación en el tamaño del JSON, que no puede exceder los 64KB.

En los objetos "question", "answer", y "finish", deberían haber handlers.

Antes de agregar el objeto JSON al bot, asegúrate de validarlo.

Manejador de errores de Salesbot

Si un mensaje del bot no puede ser entregado al cliente, por ejemplo, cuando el cliente ha bloqueado los mensajes de ese chat, el bot puede manejar el error y ejecutar manejadores específicos.

Ejemplo:

{
     "0":{
        "question":[
           ...
        ],
        "answer":[
           ...
        ]
     },
     "error":[
        {
           "handler":"action",
           "params":{
              "name":"change_status",
              "params":{
                 "value":142
              }
           }
        }
     ]
  }

Manejadores de Salesbot

Código	Descripción
show	Envía un mensaje con texto
buttons	Procesamiento de la respuesta recibida desde los botones de los mensajeros instantáneos
action	Acción
meta	Procesamiento de metadatos
condition	Condición
validations	Validación
preset	Procesa datos para un algoritmo específico
goto	Transición del script a un paso determinado
wait_answer	Espera la respuesta
find	Búsqueda
filter	Filtración
send_internal	Envía un mensaje interno
stop	Detiene el bot

show

🚧
Este manejador acepta leads entrantes si está configurado en el Salesbot.

El manejador "show" envía un mensaje o botones al chat del cliente. Cualquier texto enviado actualmente soporta los siguientes placeholders:

Placeholder	Descripción
{{contact.name}}, {{name}}	Nombre de contacto
{{lead.id}}	ID del lead
{{contact.id}}	ID de contacto
{{origin}}	Fuente del lead (Telegram,Viber, Facebook)
{{lead.source_id}}	ID de fuente del lead
{{message_text}}	Mensaje recibido del cliente en el bloque lógico de la respuesta
{{lead.cf.#custom_field_id#}}, {{contact.cf.#custom_field_id#}}, {{company.cf.#custom_field_id#}}	El valor del campo personalizado de un lead/contacto/compañía. Reemplaza #custom_field_id# con el ID del campo adicional.
{{rand}}	Cadena aleatoria
{{short_rand}}	Cadena corta aleatoria
{{short_rand_num}}	Número aleatorio de 1111 a 9999
{{message_text.email}}	Correo electrónico (si está presente en el mensaje del cliente)
{{message_text.phone}}	Número de teléfono (si está presente en el mensaje del cliente)
{{regexp./([1-9]+) things /}}	El valor por expresión regular de la respuesta del usuario. El valor dentro del paréntesis será sustituido. Puede ser utilizado en el bloque de respuesta.
{{lead.price}}	Valor de venta del lead
{{current_date}}	Fecha actual
{{lead.status_id}}	ID de la etapa del lead
{{cf.talk.nps}}	Evaluación de la conversación
{{lead.responsible.id}}, {{contact.responsible.id}}, {{company.responsible.id}}	ID del usuario responsable del lead/contacto/compañía
{{lead.responsible.name}}, {{contact.responsible.name}}, {{company.responsible.name}}	Nombre del usuario responsable del lead/contacto/compañía
{{lead.responsible.email}}, {{contact.responsible.email}}, {{company.responsible.email}}	Correo electrónico del usuario responsable del lead/contacto/compañía

Para los placeholders de contacto, se utiliza el contacto principal del lead o el contacto del chat en el que se está llevando a cabo la conversación con el cliente.

text

Parámetros del manejador para enviar texto.

{
  "handler": "show",
  "params": {
    "type": "text",
    "value": "Por favor, ingresa tu número de teléfono y tu correo electrónico.",
    "quick_replies": [
      "user_phone_number",
      "user_email"
    ]
  }
}

Parámetro	Tipo de dato	Descripción
type	string	Debe ser `"text"`
value	string	Texto a enviar al usuario
quick_replies	array	Un arreglo de elementos (actualmente disponibles: "user_phone_number" y "user_email") envía botones de respuesta rápida. Esta funcionalidad está disponible solo para Facebook y muestra botones que contienen la información de la cuenta de Facebook del usuario (número de teléfono, correo electrónico).

buttons

Parámetros del manejador para enviar botones.

{
  "handler": "show",
  "params": {
    "type": "buttons",
    "value": "Por favor elige el tipo de participación:",
    "buttons": [
      "Presencia personal",
      "En línea"
    ]
  }
}

Parámetro	Tipo de dato	Descripción
type	string	Debe ser `"buttons"`.
value	string	Texto que se enviará al usuario (En Messenger, los textos de más de 80 caracteres se recortarán).
buttons	array	Un arreglo cuyos elementos son los textos de los botones que serán enviados.
accept_unsorted	bool	Se configura en falso si no necesitas analizar los leads entrantes en la primera respuesta.

buttons_url

Parámetros del manejador para enviar botones con enlaces a recursos externos.

{
    "handler": "show",
    "params": {
        "type": "buttons_url",
        "value": "Enlaces a recursos externos",
        "buttons": [
            {
                "text": "Bing",
                "url": "https://www.bing.com"
            },
            {
                "text": "Google",
                "url": "https://google.com"
            }
        ]
    }
}

Parámetro	Tipo de dato	Descripción
type	string	Debe ser `"buttons_url"`. Envía botones con enlaces.
value	string	Texto que se enviará al usuario. (en Messenger, los textos más largos de 80 caracteres serán recortados).
buttons	array	Un arreglo cuyos elementos son el texto de los botones que serán enviados.

Si quieres enviar enlaces a redes sociales y habilitar el autoenlace, los enlaces deben tener el siguiente formato:

Redes sociales	Enlace	Comentarios
Facebook Messenger	https://m.me/123/?ref=VisitorUid_{{visitor_uid}}	En el cual '123' es el ID del grupo
WhatsApp	https://wa.me/7895?text=ID:%20{{session_id}}	En el cual '7895' es el número de teléfono de WhatsApp vinculado a la cuenta
Viber	viber://pa?chatURI=bot&context=VisitorUid_{{visitor_uid}}	En el cual 'bot' es el nombre de la cuenta pública
Telegram	tg://resolve?domain=bot&start=VisitorUid_{{visitor_uid}}	En el cual 'bot' es el nombre del bot

buttons

El manejador de botones está diseñado para insertarse en el bloque de lógica de respuestas y permite procesar las respuestas de los botones enviados o las respuestas de coincidencia exacta.

{
  "handler": "buttons",
  "params": [
    {
      "value": "Presencia personal",
      "params": [
        {
          "handler": "...",
          "params": {...}
        }
      ]
    },
    {
      "value": "En línea",
      "params": [
        {
          "handler": "...",
          "params": {...}
        }
      ]
    }
  ]
}

El manejador "buttons" espera un arreglo de objetos para ingresar en los parámetros, en el cual se puede llamar a cualquiera de los manejadores especificados en esta página.

goto

El manejador goto te permite saltar a un paso específico en el flujo, por ejemplo, si necesitas realizar ciertas acciones de manera repetida.

📘
El contador de pasos comienza desde 0.

{
    "handler": "goto",
    "params": {
        "type": "question",
        "step": 3
    }
}

Parámetro	Tipo de dato	Descripción
type	string	El bloque al que se realizará el salto. Los valores posibles son:`"question"`, `"answer"` y `"finish"`.
step	int	El paso del bot al que se realizará el salto

wait_answer

Se utiliza para esperar una respuesta del usuario a una pregunta determinada. Permite hacer una pregunta al usuario y esperar su respuesta antes de continuar con las acciones siguientes.

{
  "handler": "wait_answer",
  "params": {
    "type": "question",
    "step": 2
  }
}

Parámetro	Tipo de dato	Descripción
type	string	El bloque al que se realizará el salto. Los valores posibles son:`"question"` y `"answer"`.
step	int	El paso del bot al que se realizará el salto

find

El manejador "find" permite ubicar una entidad y utilizar sus datos. Si se encuentra un elemento, puedes utilizar los siguientes placeholders:

{{founded_id}} – si se encuentra un elemento de la lista.
{{contact_double.*}} – si se encuentra un duplicado de contacto, lo que permite acceder a sus campos de manera similar a los placeholders de {{contact.*}}.

{
  "handler": "find",
  "params": {
    "type": "contact_double",
    "params":{
      "type": "name",
      "actions": [
        {
          "handler": "show",
          "params": {
            "type": "buttons",
            "value": "¿Es tu número {{contact_double.cf.3574}}?",
            "buttons": [
              "Si",
              "No"
            ]
          }
        }
      ]
    }
  }
}

{
  "handler": "find",
  "params": {
  "type": "catalog_elements",
    "params": {
      "value": "Salesbot",
      "catalog_id": "15123",
      "actions": [
        {
          "handler": "show",
          "params": {
            "type": "buttons",
            "value": "Se encontró un elemento con ID - {{founded_id}}",
            "buttons": [
                "Si",
                "No"
            ]
          }
        }
      ]
    }
  }
}

Parámetro	Tipo de dato	Descripción
type	string	`contact_double` – buscar un duplicado del contacto actual, `catalog_elements` – buscar un elemento de lista.
params[type]	string	`type` – puede ser `"name"` (búsqueda disponible por nombre; no es requerido para buscar por catálogo.)
params[actions]	array	Acciones que se realizarán si se encuentra una entidad
value	string	La palabra que se busca, se pueden utilizar los placeholders del bloque `"show"`. Para el tipo `catalog_elements` – el nombre del elemento del catálogo.
catalog_id	int	ID de la lista donde estás buscando un elemento

filter

El manejador "filter" te permite encontrar una entidad y utilizar sus datos. Si se encuentra un elemento, puedes usar los placeholders para los campos personalizados external_lead y external_contact.

{
   "handler": "filter",
   "params": {
     "type": 2,
     "value": "{{lead.cf.111}}",
     "custom_fields_id": 222,
     "actions": [
       {
         "handler": "action",
         "params": {
           "name": "set_custom_fields",
           "params": {
             "type": 1,
             "value": "{{external_contact.cf.333}}",
             "custom_fields_id": 444,
             "enum": "WORK"
           }
         }
       }
     ]
   }
 }

Parámetro	Tipo de dato	Descripción
type	int	El tipo de entidad para la cual se realiza el filtrado: 1 – contacto, 2 – lead.
value	string	La palabra por la cual filtramos puede incluir placeholders del bloque`"show"`.
custom_fields_id	int	El ID del campo personalizado en el cual se aplicará el filtro.

action

El manejador "action" te permite realizar una de las acciones posibles:

Acción	Descripción
unsorted	Acciones con los Leads Entrantes
change_status	Cambiar de etapa
set_tag	Establecer la etiqueta
unset_tag	Eliminar la etiqueta
set_custom_fields	Establecer los valores de los campos del lead/contacto
subscribe	Suscripción del usuario al chat en la entidad
unsubscribe	Desuscripción del usuario del chat en la entidad
add_lead_contact	Añadir un lead y un contacto que están vinculados entre sí
set_budget	Establecer el presupuesto del lead (venta)
add_linked_company	Añadir compañía
add_note	Añadir una nota
link	Enlazar elementos
change_responsible_user	Cambiar de la persona responsable
link_to_unsorted	Crear un contacto a partir del lead entrante y asociarlo con el lead

unsorted

La acción "unsorted" permite aceptar o rechazar un lead entrante.

{
  "handler": "action",
  "params": {
    "name": "unsorted",
    "params": {
      "value": "accept"
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "unsorted",
    "params": {
      "value": "decline"
    }
  }
}

Parámetro	Tipo de dato	Descripción
value	string	`"accept"` / `"decline"` para aceptar / rechazar el lead entrante.

change_status

La acción "change_status" permite cambiar la etapa del lead.

{
  "handler": "action",
  "params": {
    "name": "change_status",
    "params": {
      "value": 142
    }
  }
}

Parámetro	Tipo de dato	Descripción
value	int	ID de la etapa a la que se transferirá el lead
entity	int or string	Un parámetro opcional que puede ser `"double"`. Si el manejador `"find"` fue utilizado previamente, la etapa se actualizará para el lead del contacto encontrado, si existe.

set_tag

La acción "set_tag" asignará una etiqueta al lead o contacto y admite el placeholder {{origin}}, que especificará el origen del lead.

{
  "handler": "action",
  "params": {
    "name": "set_tag",
    "params": {
      "type": 2,
      "value": "Salesbot"
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "set_tag",
    "params": {
      "type": 2,
      "value": "{{origin}}"
    }
  }
}

Parámetro	Tipo de dato	Descripción
type	int	El tipo de entidad a etiquetar (1-contacto, 2-lead)
value	string	Nombre de la etiqueta

unset_tag

La acción "unset_tag" elimina la etiqueta de un lead o contacto.

{
  "handler": "action",
  "params": {
    "name": "unset_tag",
    "params": {
      "type": 2,
      "value": "Salesbot"
    }
  }
}

Parámetro	Tipo de dato	Descripción
type	int	El tipo de entidad de donde se eliminará la etiqueta (1-contacto, 2-leads).
value	string	Nombre de la etiqueta que se eliminará

set_custom_fields

La acción "set_custom_fields" establecerá los valores de los campos personalizados para un lead o contacto. Puedes encontrar los IDs de los campos en la sección de Configuración de un lead/contacto o utilizando el método para obtener la lista de los campos de entidad.. Puedes utilizar los placeholders descritos en la sección "show" como valores para los campos.

{
  "handler": "action",
  "params": {
    "name": "set_custom_fields",
    "params": {
      "type": 2,
      "value": "Value of the field",
      "custom_fields_id": 123,
      "option": "add"
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "set_custom_fields",
    "params": {
      "type": 2,
      "value": "{{message_text}}",
      "custom_fields_id": 987
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "set_custom_fields",
    "params": {
      "type": "lead",
      "value": "{{last_validation_result}}",
      "custom_field": "{{cf.talk.nps}}"
    }
  }
}

Parámetro	Tipo de dato	Descripción
type	int	El tipo de entidad para la cual se establecerán los campos personalizados (1-contacto, 2-lead).
value	string	El valor del campo que se establecerá puede utilizar placeholders del bloque `"show"` . Luego del manejador `"validations"`, está permitido utilizar placeholder `{{last_validation_result}}`, que utilizará los datos reconocidos de la última condición `true`. Port ejemplo, si se utilizó la condición`"contains email"`, el correo electrónico encontrado será sustituido como el valor.
custom_fields_id	int	El ID del campo en el que se establecerá el valor.
custom_field	string	El identificador del campo que se está modificando puede incluir lo siguiente: {{lead.price}} – la venta del lead. {{lead.name}} – el nombre del lead. {{contact.name}} – el nombre del contacto. {{cf.talk.nps}} – la calificación de la conversación actual.
calculated	bool	Si es necesario intentar calcular el valor de este campo personalizado utilizando la fórmula, por ejemplo`{{lead.cf.123}} * {{lead.cf.456}}`.
option	string	Utiliza la opción `“add”` para añadir un valor a un campo de tu elección. Tipos de campo disponibles: phone number, email, multiselect list.

La acción "subscribe" suscribirá a un usuario/grupo de usuarios al chat.

{
  "handler": "action",
  "params": {
    "name": "subscribe",
    "params": {
      "type": "group",
      "value": 111
    }
  }
},
{
  "handler": "action",
  "params": {
    "name": "subscribe",
    "params": {
      "type": "user",
      "value": "{{lead.responsible_user_id}}"
    }
  }
}

Parámetro	Tipo de dato	Descripción
type	string	`"group"` o `"user"`
value	int	El ID del grupo de usuarios o el ID del usuario

unsubscribe

La acción "unsubscribe" dará de baja a un usuario/grupo de usuarios del chat.

{
  "handler": "action",
  "params": {
    "name": "unsubscribe",
    "params": {
      "type": "user",
      "value": "{{lead.responsible_user_id}}"
    }
  }
}

Parámetro	Tipo de dato	Descripción
type	string	`"group"` ,`"user"` o `"all"`
value	int	El ID del grupo de usuarios o el ID del usuario. Es opcional si has pasado`"all"` como `"type"`.

add_lead_contact

La acción "add_lead_contact" Creará un lead y un contacto, y los vinculará. Todos los campos del lead y del contacto pueden ser configurados. Los valores de los campos personalizados admiten los mismos placeholders que en el manejador "show". La acción "preset" también se admite, lo que permite que el contacto y el lead se creen solo si se recibe un mensaje o un número de teléfono del cliente.

{
  "handler": "action",
  "params": {
      "name": "add_lead_contact",
      "params": {
          "preset": "contacts.require_email_or_phone",
          "lead": {
              "name": "Nombre del lead",
              "status_id": 142,
              "responsible_user_id": 123,
              "price": 2000,
              "tags": "",
              "custom_fields": [
                  {
                      "id": 77744111,
                      "values": [
                          {
                              "value": "{{contact.name}}"
                          }
                      ]
                  },
                  {
                      "id": 77744222,
                      "values": [
                          {
                              "value": "{{lead.cf.77744222}}"
                          }
                      ]
                  }
              ]
          },
          "contact": {
              "name": "Nombre del contacto",
              "responsible_user_id": 123,
              "tags": "",
              "custom_fields": [
                  {
                      "id": 77744444,
                      "values": [
                          {
                              "value": "{{message_text.email}}",
                              "enum": "WORK"
                          }
                      ]
                  },
                  {
                      "id": 77744555,
                      "values": [
                          {
                              "value": "{{message_text.phone}}",
                              "enum": "WORK"
                          }
                      ]
                  }
              ]
          }
      }
  }
}

Parámetro	Tipo de dato	Descripción
lead	object	Conjunto de campos del lead
contact	object	Conjunto de campos de contacto
preset	string	Parámetro opcional. Se admite un ajuste preestablecido `contacts.require_email_or_phone` , que verifica si se envió el teléfono o el correo electrónico en un mensaje del cliente.

set_budget

La acción "set_budget" establecerá la venta para el lead.

{
  "handler": "action",
  "params": {
    "name": "set_budget",
    "params": {
      "value": "{{lead.cf.555123}}*{{lead.cf.555321}}"
    }
  }
}

Parámetro	Tipo de dato	Descripción
value	string	El número que se registrará en la venta del lead. Este campo también puede ser calculado, permitiendo que se utilicen los placeholders del bloque `"show"` en el cálculo. Las operaciones disponibles incluyen +, -, _ y /. También puedes utilizar paréntesis, por ejemplo: `({{lead.cf.555123}} + 1){{lead.cf.555321}}`.

add_linked_company

La acción "add_linked_company" añade una compañía vinculada a un lead y a un contacto.

{
  "handler": "action",
  "params": {
    "name": "add_linked_company",
    "params": {
      "name": "{{message_text}}"
    }
  }
}

Parámetro	Tipo de dato	Descripción
name	string	Nombre de la compañía, se pueden usar los placeholders del bloque`"show"` .

add_note

La acción add_note añade una nota.

{
  "handler": "action",
  "params": {
    "name": "add_note",
    "params": {
      "element_type": 1,
      "note_type": 4,
      "text": "Texto de la nota"
    }
  }
}

Parámetro	Tipo de dato	Descripción
element_type	int	La entidad a la que se adjuntará la nota: 1 – contacto, 2 – lead
note_type	int	Tipo de nota: 4 – Nota regular. 10 – Nota de llamada entrante. 11 – Nota de llamada saliente. 102 – Nota de mensaje de texto entrante. 103 – Nota de mensaje SMS saliente. 25 – Nota de servicio.
text	string	Texto de la nota, se pueden utilizar los placeholders del bloque`"show"` .

link

La acción "link" vincula elementos.

{
  "handler": "action",
  "params": {
    "name": "link",
    "params": {
      "from": 2,
      "to": 11,
      "to_id": "{{founded_id}}",
      "to_catalog_id": 123
    }
  }
}

Parámetro	Tipo de dato	Descripción
from	int	La entidad a la que se vinculará la segunda entidad ( 1 – contacto, 2 – lead).
from_id	int	Parámetro opcional. El ID de la entidad a la que se vinculará la segunda entidad. Si no se especifica, se utilizará el ID de la entidad actual. También se pueden usar placeholders de la sección`"show"`.
to	int	La entidad que se vinculará: 1 – contacto, 2 – lead, 3 – compañía, 11 – elemento de lista.
to_id	string	ID del elemento que se vinculará, puedes utilizar los marcadores de posición de la sección `"show" .
to_catalog_id	int	Parámetro opcional, ID de lista (si el elemento de la lista está vinculado).
quantity	int	Un parámetro opcional, el número de elementos de la lista que se adjuntarán a la entidad. Se pueden usar los placeholders de la sección `"show"`.

change_responsible_user

La acción change_responsible_user cambia el usuario responsable de un lead o del contacto asociado.

{
  "handler": "action",
  "params": {
    "name": "change_responsible_user",
    "params": {
      "value": 123,
      "type": 2
    }
  }
}

Parámetro	Tipo de dato	Descripción
value	int	ID del usuario que deseas asignar como responsable
type	int	Parámetro opcional, el tipo de entidad para la cual se está cambiando el usuario responsable: 1 – contacto, 2 – lead. Si no se proporciona, por defecto es 2.

link_to_unsorted

La acción "link_to_unsorted" vincula un chat de los leads entrantes con el contacto especificado en un lead. Si el contacto especificado no existe en el lead, la vinculación no se realizará. Si no se proporciona el contact_id se creará un contacto en el lead especificado.

{
  "handler": "action",
  "params": {
    "name": "link_to_unsorted",
    "params": {
      "entity_type": 2,
      "entity_id": "12345"
    }
  }
}

Parámetro	Tipo de dato	Descripción
entity_type	int	Tipo de entidad (2-lead)
entity_id	string	El ID de la entidad a la que se debe vincular el contacto. Se pueden utilizar placeholders, por ejemplo, si se utilizó un manejador `"filter"` se puede utilizar `{{external_lead.id}}`.
contact_id	string	Parámetro opcional. El ID del contacto al que se debe vincular el chat. El contacto debe estar en el lead especificado. Se pueden utilizar los placeholders, por ej.: si se utilizó un manejador `"filter"` , puedes usar`{{external_contact.id}}`.

Parámetro	Tipo de datos	Descripción
delimiter	string	El caracter que separará el contenido entrante en elementos.
values	array	Un arreglo de valores donde se almacenarán los elementos de la información entrante. Los valores pueden ser registrados en etiquetas o campos de lead.

condition

El manejador "condition" está diseñado para crear condiciones lógicas.

{
  "handler": "condition",
  "params": {
    "term1": "chat.origin",
    "term2": "telegram",
    "operation": "=",
    "result": [
      {
        "handler": "action",
        "params": {
          "name": "change_status",
          "params": {
            "value": 123
          }
        }
      }
    ]
  }
}

Parámetro	Tipo de dato	Descripción
term1	string	La condición 1 puede ser: `lead.tags` – que devuelve una lista de etiquetas, `chat.origin` – que devuelve la fuente de la cual provino la solicitud (Facebook, Telegram, Viber), cualquier placeholder del bloque descrito en la sección del manejador `"show"`, por ejemplo `{{contact.name}}`.
term2	string/obj	La condición 2: para el operador `in_range`, debes pasar un objeto con parámetros; de lo contrario, se debe proporcionar una cadena o placeholder de la sección `"show"` del manejador.
term2.from	int	El valor "from" del rango
term2.to	int	El valor "to" del rango
operation	string	El operador de comparación: `"="`, `"! ="`, `"in"`, `"not_in"` o `"in_range"`
result	array	Si la comparación es exitosa, el arreglo de manejadores

Operadores

Operadores	Descripción
`"="`	El operador "=" verifica si `"term1"` es igual a `"term2"`
`"!="`	El operador "!=" verifica si `"term1"` no es igual a `"term2"`
`"in"`	Toma cadenas de `"term1"` y `"term2"`, las divide en valores con comas y busca ocurrencias de los valores de `"term2"` en `"term1"`. Si hay al menos una coincidencia, se ejecutarán los manejadores de resultados.
`"not_in"`	Toma cadenas de `"term1"` y `"term2"`, las divide en valores con comas y busca ocurrencias de los valores de `"term2"` en `"term1"`. Si no hay coincidencias, se ejecutarán los manejadores de resultados
`"in_range"`	Encuentra todos los enteros en `"term1"`. Si al menos uno de estos números cae dentro del rango especificado por`"term2"`, se ejecutará el arreglo de manejadores de resultados.

validations

El manejador "validations" está diseñado para crear condiciones lógicas.

{
  "handler": "validations",
  "params": {
    "logic": "and",
    "conditions": [
      {
        "client_value": "{{message_text}}",
        "type": "regex",
        "condition_value": "/[0-9]+/",
        "operation": "contains"
      },
      {
        "client_value": "{{message_text}}",
        "type": "simple",
        "condition_value": "654",
        "operation": "equal"
      },
      {
        "client_value": "{{message_text}}",
        "type": "range_numbers",
        "condition_value": {
          "from": 123,
          "to": 321
        },
        "operation": "contains"
      },
      {
        "client_value": "{{message_text}}",
        "type": "email",
        "condition_value": "",
        "operation": "contains"
      }
    ],
    "result": [
      {
        "handler": "goto",
        "params": {
          "type": "question",
          "step": 3
        }
      }
    ]
  }
}

Parámetros	Tipo de dato	Descripción
logic	string	La lógica para verificar las condiciones es la siguiente: si se especifica `"and"`, todas las condiciones deben ser verdaderas; si se especifica `"or"`, al menos una de las condiciones debe ser verdadera.
conditions	array	La lista de condiciones para verificar se describe a continuación
result	array	Tras una validación exitosa, se ejecutará el arreglo de manejadores

Condición simple

La condición "simple" verifica la igualdad/desigualdad o compara la longitud

{
  "client_value": "{{message_text}}",
  "type": "simple",
  "condition_value": "654",
  "operation": "equal"
}

Parámetro	Tipo de dato	Descripción
client_value	string	El valor que se está verificando puede ser un placeholder de la sección del manejador `"show"`, por ejemplo, `"{{contact.name}}"`.
type	string	Debe establecerse en `"simple"`
condition_value	string	Puede ser un placeholder de la sección del manejador `"show"` (por ej.: `"{{contact.name}}"`) o un valor personalizado.
operation	string	Puede ser `"equal"`, `"not_equal"` o `"length"`. Si se selecciona el operador `"equal"`, la condición será `true` si `"client_value"` es igual a `"condition_value"`. Si se selecciona el operador `"not_equal"` , la condición será `true` si `"client_value"` no es igual a `"condition_value"`. Si se selecciona el operador `"length"`, la condición será `true` si la longitud de la cadena`"client_value"` es igual a `"condition_value"`.

Condición email/phone

Las condiciones "email" y "phone" verifican si una cadena contiene un número de teléfono o un correo electrónico.

{
  "client_value": "{{message_text}}",
  "type": "email",
  "condition_value": "",
  "operation": "contains"
}

Parámetro	Tipo de dato	Descripción
client_value	string	El valor que se está verificando puede ser un placeholder de la sección del manejador `"show"` , por ejemplo, `"{{contact.name}}"`.
type	string	El tipo de condición puede ser `"email"` para buscar un correo electrónico o `"phone"` para buscar un número de teléfono.
condition_value	string	Debe ser una cadena vacía (`""`)
operation	string	Puede ser `"contains"` o `"not_contains"`. Si se selecciona el operador `"contains"` , la condición será `true` si `"client_value"` contiene un correo electrónico o un número de teléfono. Si se selecciona el operador `"not_contains"` , la condición será `true` si `"client_value"` no contiene un correo electrónico o un número de teléfono.

Condición regex

Una condición "regex" verifica si una cadena contiene una expresión regular.

{
  "client_value": "{{message_text}}",
  "type": "regex",
  "condition_value": "/[0-9]+/",
  "operation": "contains"
}

Parámetro	Tipo de dato	Descripción
client_value	string	El valor que se está verificando puede ser un placeholder de la sección del manejador `"show"` , por ejemplo, `"{{contact.name}}"`.
type	string	Debe ser "regex"
condition_value	string	Texto de la condición
operation	string	Puede ser `"contains"` o `"not_contains"`. Si se selecciona el operador `"contains"`, la condición será `true` si `"client_value"` contiene la expresión regular. Si se selecciona el operador `"not_contains"` , la condición será `true` si `"client_value"` no contiene la expresión regular.

Condición range_numbers

Una condición "range_numbers" verifica si una cadena contiene un número dentro de un rango especificado.

{
  "client_value": "{{message_text}}",
  "type": "range_numbers",
  "condition_value": {
    "from": 123,
    "to": 321
  },
  "operation": "contains"
}

Parámetro	Tipo de dato	Descripción
client_value	string	El valor que se está verificando puede ser un placeholder de la sección del manejador `"show"`, por ejemplo, `"{{contact.name}}"`.
type	string	Debe ser `“range_numbers”`
condition_value	obj	El rango en el que verificamos todos los números en `"client_value"`.
condition_value.from	string, number	El valor del rango `"from"` se puede especificar como un placeholder de la sección del manejador `"show"` (por ejemplo, `"{{lead.price}}"`) o como un valor personalizado.
condition_value.to	string, number	El valor del rango `"to"` se puede especificar como un placeholder de la sección del manejador `"show"` (por ejemplo, `"{{lead.price}}"`) o como un valor personalizado.
operation	string	Puede se `"contains"` o `"not_contains"`. Si se selecciona el operador `"contains"`, la condición será `true` si `"client_value"` contiene un número dentro del rango especificado. Si se selecciona el operador `"not_contains"`, la condición será`true` si `"client_value"` no contiene un número dentro del rango especificado.

preset

El manejador "preset" está diseñado para procesar mensajes entrantes utilizando plantillas predefinidas.

Parámetro	Tipo	Descripción
name	string	Nombre del manejador
params	array	Parámetros del manejador

contacts.validate_base_info

La plantilla "contacts.validate_base_info" te permite obtener y verificar la información del usuario, y luego solicitar cualquier información faltante.

{
  "handler": "preset",
  "params": {
    "name": "contacts.validate_base_info",
    "params": {
      "empty_email": "Por favor, proporciona tu correo electrónico.",
      "empty_phone": "Por favor, proporciona tu número de teléfono.",
      "invalid_phone": "Parece que hay un error en el número de teléfono.",
      "success": "Gracias",
      "empty_all": "Por favor, proporciona tu correo electrónico y número de teléfono",
      "check_doubles": true,
      "phone_doubles": "Este número de teléfono ya está en uso. Por favor, ingresa un número diferente.",
      "email_doubles": "Este correo electrónico ya está en uso. Por favor, ingresa un correo electrónico diferente.",
      "all_doubles": "Este número de teléfono y correo electrónico ya están en uso. Por favor, ingresa información de contacto diferente.",
      "use_quick_replies": true
    }
  }
}

Parámetro	Tipo	Descripción
empty_email	string	Mensaje en ausencia de correo electrónico del contacto
empty_phone	string	Mensaje en ausencia de un número de teléfono del contacto
invalid_phone	string	Mensaje al recibir un número de teléfono inválido
success	string	Mensaje después de recibir todos los datos
empty_all	string	Mensaje en ausencia de todos los datos
check_doubles	bool	Un parámetro que determina si se habilita la búsqueda de contactos duplicados basados en el correo electrónico y el número de teléfono. Si está habilitado, cuando se encuentre un contacto duplicado, se solicitará nuevamente la información del contacto.`true` significa habilitado, mientras que `false` o la ausencia del parámetro significa deshabilitado.
phone_doubles	string	El mensaje que se mostrará si se encuentra un contacto duplicado basado en el número de teléfono.
email_doubles	string	El mensaje que se mostrará si se encuentra un contacto duplicado basado en el correo electrónico.
all_doubles	string	El mensaje que se mostrará si se encuentran duplicados para el contacto basados tanto en el número de teléfono como en el correo electrónico.
use_quick_replies	string	Un parámetro que envía botones de respuesta rápida cuando al contacto le falta un correo electrónico y/o número de teléfono. Esto solo está disponible para Facebook y muestra botones con la información de cuenta de Facebook del usuario (teléfono, correo electrónico). Para habilitar esta función, establece el valor en `true`.

contacts.get_base_info

La plantilla "contacts.get_base_info" te permite obtener información sin hacer preguntas adicionales.

{
  "handler": "preset",
  "params": {
    "name": "contacts.get_base_info"
  }
}

send_internal

El manejador "send_internal" te permite enviar un mensaje interno en el chat del lead.

🚧
Si se especifican tanto group_id como user_id simultáneamente, el mensaje se enviará al grupo de usuarios.

{
  "handler": "send_internal",
  "params": {
    "entity_id": "{{lead.id}}",
    "entity_type": 2,
    "message": "¡Hola!"
  }
}

Parámetro	Tipo de dato	Descripción
entity_id	int or string	El ID del lead al que se enviará el mensaje. Se puede utilizar un placeholder como `"{{lead.id}}"`.
entity_type	int	Un tipo de entidad al que se enviará el mensaje. Solo 2 (lead) está disponible.
message	string	Una cadena con un mensaje
group_id	int	Un parámetro opcional, el ID del grupo de usuarios al que se debe enviar el mensaje.
user_id	int	Un parámetro opcional, el ID del usuario al que se debe enviar el mensaje.

widget_request

El manejador "widget_request: está diseñado para enviar webhooks a URLs externas desde Salesbot.

🚧
Este manejador solo se puede utilizar desde el paso Widget del Salesbot. Encuentra información adicional sobre el widget del Salesbot aquí.

{
  "handler": "widget_request",
  "params": {
    "url": "https://example.com/endpoint",
    "data": {
      "contact": "{{contact.name}}",
      "from": "widget"
    }
  }
}

onSalesbotDesignerSave: function (handler_code, params) {
  var request_data = {
    message: params.message,
  };

  if (APP.getBaseEntity() === 'lead') {
    request_data.lead = '{{lead.id}}';
  };

  return JSON.stringify([
    {
      question: [
        {
          handler: 'widget_request',
          params: {
            url: 'https://example.com/webhook',
            data: request_data,
          },
        },
        {
          handler: 'goto',
          params: {
            type: 'question',
            step: 1,
          },
        },
      ],
    },
    {
      question: [
        {
          handler: 'conditions',
          params: {
            logic: 'and',
            conditions: [
              {
                term1: '{{json.status}}',
                term2: 'success',
                operation: '=',
              },
            ],
            result: [
              {
                handler: 'exits',
                params: {
                  value: 'success',
                },
              },
            ],
          },
        },
        {
          handler: 'exits',
          params: {
            value: 'fail',
          },
        },
      ],
    },
  ]);
},

Parámetro	Tipo de dato	Descripción
url	string	El punto de enlace URL del servidor externo
data	array	Un arreglo de cualquier dato que contenga cadenas y/o placeholders de la sección del manejador `"show"` , por ejemplo, `"{{contact.name}}"`.

El punto de enlace recibirá una solicitud POST. Para confirmar que el webhook ha sido recibido, debes responder dentro de los 2 segundos con un código de estado HTTP 200.

{
      "token": "JWT_TOKEN",
      "data": {
          "contact": "Nombre del contacto",
          "from": "widget"
      },
      "return_url": "https://subdomain.kommo.com/api/v4/salesbot/321/continue/123"
    }

El token JWT se necesita para validar los datos enviados en la solicitud. Está autenticado con la clave secreta del cliente.

Respuesta del widget y reanudación de las operaciones del bot

Para reanudar la operación del bot, necesitas realizar una solicitud con los datos. El bot actual no continuará su operación hasta que reciba la solicitud. Además, no podrás continuar con la ejecución del bot si otro bot para la misma entidad ya se encuentra en funcionamiento.

stop

El manejador "stop" está destinado a realizar acciones cuando el bot haya terminado.

{
  "finish": [
    {
      "handler": "stop",
      "params": {
        "action": "talk-close"
      }
    },
    {
      "handler": "stop",
      "params": {
        "action": "salesbot-start",
        "bot": 1234
      }
    }
  ]
}

Parámetro	Tipo de dato	Descripción
action	string	Puede ser `"talk-close"` o `"salesbot-start"`. `"talk-close"` termina la conversación. Si esto se ejecuta dentro del bot de NPS, la conversación se cerrará; de lo contrario, se iniciará el bot de NPS.`"salesbot-start"` inicia otro bot.
bot	int	El parámetro es obligatorio si la acción seleccionada es `"salesbot-start"`. Especifica el ID del bot que debe ser iniciado.

Ejemplos

Suscribir a un grupo de usuarios al chat:

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "subscribe",
                    "params": {
                        "type": "group",
                        "value": 111
                    }
                }
            }
        ]
    }
]

Mover el lead a otra etapa:

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "change_status",
                    "params": {
                        "value": 142
                    }
                }
            }
        ]
    }
]

Enviar cualquier texto al cliente:

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "text",
                    "value": "Hola"
                }
            }
        ]
    }
]

Enviar un mensaje con los botones de selección:

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "buttons",
                    "value": "Por favor, elige el tipo de participación:",
                    "buttons": [
                        "Fuera de línea",
                        "En línea"
                    ]
                }
            }
        ],
        "answer": [
            {
                "handler": "buttons",
                "params": [{
                    "regex": "/offline/iu",
                    "params": [{
                        "handler": "action",
                        "params": {
                            "name": "set_custom_fields",
                            "params": {
                                "type": 2,
                                "value": "Fuera de línea",
                                "custom_fields_id": 4242
                            }
                        }
                    }]
                },
                    {
                    "regex": "/online/iu",
                    "params": [{
                        "handler": "action",
                        "params": {
                            "name": "set_custom_fields",
                            "params": {
                                "type": 2,
                                "value": "En línea",
                                "custom_fields_id": 4242
                            }
                        }
                    }]
                }]
            }]
    }
]

Establecer una etiqueta para un lead:

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "set_tag",
                    "params": {
                        "type": 2,
                        "value": "salesbot"
                    }
                }
            }
        ]
    }
]

Establecer un valor para un campo personalizado:

[
    {
        "question": [
            {
                "handler": "action",
                "params": {
                    "name": "set_custom_fields",
                    "params": {
                        "type": 2,
                        "custom_fields_id": 123,
                        "value": "Valor de campo"
                    }
                }
            }
        ]
    }
]

Guardar metadatos en la tarjeta del lead:

[
    {
        "question": [
            {
                "handler": "meta",
                "params": {
                    "delimiter": "-",
                    "values": [
                        "lead.tags",
                        "lead.custom_fields.123",
                        "lead.custom_fields.124",
                        "lead.tags"
                    ]
                }
            }
        ]
    }
]

Solicitar correo electrónico y número de teléfono, registrándolos en la tarjeta del lead solo con la primera respuesta:

[
    {
        "question": [
            {
                "handler": "show",
                "params": {
                    "type": "text",
                    "value": "Por favor, proporciona tu número de teléfono y correo electrónico."
                }
            }
        ],
        "answer": [
            {
                "handler": "preset",
                "params": {
                    "name": "contacts.get_base_info"
                }
            }
        ]
    }
]