--- updatedAt: 2026-02-11T15:09:54.000Z agentTools: projectIndex: https://es-developers.kommo.com/llms.txt --- # Salesbot # 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:: 1. 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. 2. 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. ```json [ { "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**: ```json Manejador error { "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. ```json text { "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](https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies). 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. ```json buttons { "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. ```json buttons_url { "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 | | En el cual '123' es el ID del grupo | | WhatsApp | | 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. ```json Manejador buttons { "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. ```json Manejador goto { "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. ```json Manejador wait_answer { "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](https://es-developers.kommo.com/docs/salesbot-1#show) de `{{contact.*}}`. ```json contact_double { "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" ] } } ] } } } ``` ```json catalog_elements { "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`. ```json Manejador filter { "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. ```json unsorted { "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. ```json change_status { "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. ```json set_tag { "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. ```json unset_tag { "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.](https://es-developers.kommo.com/reference/campos-personalizados). Puedes utilizar los placeholders descritos en la sección [`"show"`](https://es-developers.kommo.com/docs/salesbot-1#show) como valores para los campos. ```json set_custom_fields { "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.
### subscribe La acción `"subscribe"` suscribirá a un usuario/grupo de usuarios al chat. ```json subscribe { "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. ```json Acción unsubscribe { "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](https://es-developers.kommo.com/docs/salesbot-1#show) `"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. ```json Acción add_lead_contact { "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. ```json set_budget { "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. ```json Acción add_linked_company { "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. ```json Acción add_note { "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. ```json Acción link { "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. ```json Acción change_responsible_user { "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. ```json Acción link_to_unsorted { "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}}`. | ## meta El manejador `"meta"` está diseñado para manejar datos adicionales que se envían cuando se inicia el chat. Para más información sobre el envío de metadatos, consulta la documentación del mensajero: * [Telegram](https://core.telegram.org/bots#deep-linking) * [Viber](https://developers.viber.com/docs/tools/deep-links/) * [Messenger](https://developers.facebook.com/docs/messenger-platform/discovery/m-me-links) ```json Manejador meta { "handler": "meta", "params": { "delimiter": "-", "values": [ "lead.tags", "lead.custom_fields.123", "lead.custom_fields.124", "lead.tags" ] } } ``` | 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. ```json Manejador condition { "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. ```json Manejador validations { "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 ```json Condición simple { "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. ```json Condición email { "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. ```json Condición regex { "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. ```json Condición range_numbers { "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. ```json Plantilla contacts.validate_base_info { "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](https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies) 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. ```json Plantilla contacts.get_base_info { "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. ```json Manejador send_internal { "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. | ## send\_external\_message El handler `send_external_message` envía un mensaje/botones al chat del cliente. La principal diferencia con el handler `show` es la capacidad de especificar los destinatarios y los canales de chat del mensaje enviado. ```json Texto { "handler": "send_external_message", "params": { "message": { "type": "externo", "text": "Proporcione su número de teléfono y correo electrónico" }, "recipient": { "type": "contacto_principal", "way_of_communication": "over_all" }, "channels": [ { "id": 23499795 } ], "metadata": { "facebook_tag": "EVENTO_CONFIRMADO_ACTUALIZACIÓN" }, "on_error": { "handler": "goto", "params": { "step": 1, "type": "pregunta" } } } } ``` ```json Botones { "handler": "send_external_message", "params": { "message": { "type": "externo", "text": "Seleccione la opción:", "buttons": [ { "type": "en línea", "text": "Opción 1" }, { "type": "en línea", "text": "Opción 2" } ] }, "recipient": { "type": "contacto_principal", "way_of_communication": "en_general" }, "channels": [ { "id": 23499795 } ], "metadata": { "facebook_tag": "EVENTO_CONFIRMADO_ACTUALIZACIÓN" }, "on_error": { "handler": "goto", "params": { "step": 1, "type": "pregunta" } } } } ``` ```json Botones con URLs { "handler": "send_external_message", "params": { "message": { "type": "externo", "text": "Botones con enlaces", "buttons": [ { "type": "url", "text": "Google", "url": "https://google.com" }, { "type": "url", "text": "YouTube", "url": "https://youtube.com" } ] }, "recipient": { "type": "contacto_principal", "way_of_communication": "en_general" }, "channels": [], "metadata": { "facebook_tag": "EVENTO_CONFIRMADO_ACTUALIZACIÓN" }, "on_error": null } } ``` ```json Mensaje de texto con filtrado por valor del campo de contacto { "handler": "send_external_message", "params": { "message": { "type": "externo", "text": "Proporcione su número de teléfono y correo electrónico" }, "recipient": { "type": "contactos_filtrados", "filter": { "logic": "y", "result": 1, "conditions": [ { "term1": "{{contact.cf.1880614.is_checked}}", "term2": "{{contact.cf.1880614.1300836}}", "operation": "=", "value_type": "valor" } ] }, "way_of_communication": "en_general" }, "channels": [], "metadata": { "facebook_tag": "EVENTO_CONFIRMADO_ACTUALIZACIÓN" }, "on_error": { "handler": "goto", "params": { "step": 1, "type": "pregunta" } } } } ```
## 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í](https://es-developers.kommo.com/docs/salesbot). ```json widget_request { "handler": "widget_request", "params": { "url": "https://example.com/endpoint", "data": { "contact": "{{contact.name}}", "from": "widget" } } } ``` ```json Ejemplo 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. ```json Ejemplo del cuerpo de la solicitud { "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 ](https://es-developers.kommo.com/docs/tokens-de-solo-uso) 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](https://es-developers.kommo.com/reference/confirmaci%C3%B3n-de-bloqueo-de-ejecuci%C3%B3n-del-widget-salesbot). 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. ```json Manejador stop { "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: ```json [ { "question": [ { "handler": "action", "params": { "name": "subscribe", "params": { "type": "group", "value": 111 } } } ] } ] ``` Mover el lead a otra etapa: ```json [ { "question": [ { "handler": "action", "params": { "name": "change_status", "params": { "value": 142 } } } ] } ] ``` Enviar cualquier texto al cliente: ```json [ { "question": [ { "handler": "show", "params": { "type": "text", "value": "Hola" } } ] } ] ``` Enviar un mensaje con los botones de selección: ```json [ { "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: ```json [ { "question": [ { "handler": "action", "params": { "name": "set_tag", "params": { "type": 2, "value": "salesbot" } } } ] } ] ``` Establecer un valor para un campo personalizado: ```json [ { "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: ```json [ { "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: ```json [ { "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" } } ] } ] ```