Base de conocimiento de GetMyBot

Integraciones de CRM

Transfiere clientes y negocios entre el bot y tu CRM: conexión, correspondencia de campos, vista previa, sincronización y resolución de errores.

En esta página

Una conexión de CRM permite intercambiar perfiles de clientes, negocios y resúmenes de conversaciones entre el bot y tu sistema de ventas. Por ejemplo, el teléfono recogido por el bot puede aparecer en el contacto del CRM y el estado de un negocio puede volver al perfil del cliente.

Abre Integraciones → CRM. Cada conexión vincula un bot con una cuenta de CRM. Se admiten amoCRM/Kommo, Bitrix24, RetailCRM y OzmaCRM (ozma.io). Otros CRM pueden usar el adaptador HTTP propio que se describe más abajo.

Durante la configuración encontrarás tres conceptos:

  • Correspondencia de campos (mapping): indica de dónde tomar un dato y dónde guardarlo. Por ejemplo, phone en GetMyBot corresponde al campo «Teléfono» del CRM.
  • Conflicto: el valor se modificó en ambos sistemas. Puedes decidir qué cambio prevalece o resolverlo manualmente.
  • Supresión del eco: un cambio enviado al CRM no debe volver como si fuera nuevo e iniciar una sincronización sin fin.

Estas reglas son comunes a todas las conexiones. Los formatos de intercambio y las direcciones de API varían según el proveedor; los detalles técnicos se explican después de los pasos de configuración.

Solicitudes del chat del sitio

Las solicitudes del chat del sitio se pueden activar para las conexiones de CRM compatibles, incluido el adaptador HTTP propio. Consulta la configuración y las capacidades de cada proveedor.

  1. En Integraciones → CRM, abre una conexión y Correspondencia. En Solicitudes del chat del sitio, activa el envío del contacto y la solicitud, selecciona el embudo y la etapa inicial y guarda. Configura cada conexión adicional por separado. En RetailCRM, selecciona el sitio como embudo y el estado inicial del pedido como etapa.
  2. Configura el widget para recoger nombre, correo y teléfono y asigna los campos necesarios a la CRM. El evento se produce cuando el visitante proporciona o cambia el correo o el teléfono. Si el widget exige consentimiento para el tratamiento de datos, el envío espera la aceptación del texto vigente; un cambio de política puede requerir una nueva aceptación.
  3. Para enviar el origen «чат на сайте» (chat del sitio), añade en Correspondencia de campos una correspondencia saliente de deal.source a un campo adecuado de la CRM. Si hace falta, crea primero el campo en la CRM.
  4. Comprueba la operación y sus tareas en el Registro de sincronización. Si la conexión o la configuración impide poner en cola la solicitud, aparecerá en Solicitudes del chat con error. Corrige la configuración y pulsa Reintentar envío; necesitas permisos de escritura en CRM. Que se acepte el reintento solo significa que está en cola: comprueba el resultado en el registro y en la CRM. El reintento puede requerir el consentimiento vigente del visitante.

La lista muestra hasta las 100 solicitudes más recientes del proyecto. Volver a proporcionar los mismos datos no crea por sí solo una solicitud nueva. No se garantiza la ausencia de duplicados en una CRM externa; comprueba las coincidencias y el resultado en la CRM.

Si Bitrix24 encuentra un contacto existente con los mismos datos, abre la operación en el Registro de sincronización y selecciona Ver coincidencia en la tarea del contacto. Abre la ficha en la CRM y compárala con el visitante. Solo si es la misma persona, selecciona Vincular contacto y reintentar. Consultar y confirmar requieren los permisos correspondientes. La confirmación pone la solicitud en cola; comprueba el resultado en el registro y en la CRM. Si no se encuentra la coincidencia o no se puede comprobar, revisa la conexión y repite la búsqueda.

La búsqueda por teléfono en RetailCRM puede ser incompleta. Si el registro de sincronización informa de un error de búsqueda, selecciona Ver coincidencia, compara la ficha por nombre e ID y confirma solo si es la misma persona. Si no se encuentra ninguna ficha, añade o corrige el contacto en RetailCRM y repite la búsqueda. En este caso MyBot no crea un contacto a ciegas; no se garantiza una prevención completa de duplicados, en particular frente a cambios hechos fuera de MyBot.

Orden de configuración

  1. Elige un CRM y conecta la cuenta con el método indicado en la tabla siguiente.
  2. Carga sus campos y configura las correspondencias. Por ejemplo, asigna profile.phone al teléfono del cliente en el CRM.
  3. Elige la dirección de la sincronización y la política de conflictos. Si un dato cambia en ambos sistemas, decide de antemano qué cambio debe prevalecer.
  4. Ejecuta la Vista previa de la correspondencia. Muestra lo que se enviaría sin escribir nada en el CRM.
  5. Revisa los avisos e inicia la sincronización inicial con una confirmación explícita.
  6. Consulta el registro de sincronización y comprueba el resultado en varios clientes. Puedes añadir webhooks para recibir cambios más rápido.

Para una configuración habitual, empieza por el asistente, la correspondencia de campos y la vista previa. Las secciones sobre transporte, formatos y API están dirigidas a quien desarrolla la integración.

Qué está disponible ahora

La pantalla Integraciones → CRM requiere el permiso del bot Reacciones. Desde ahí puedes:

  • conectar un CRM con el asistente, cambiar el nombre de la conexión, comprobarla, volver a conectarla o eliminarla;
  • editar la correspondencia de campos y guardarla como una nueva revisión;
  • probarla con perfiles reales de suscriptores e iniciar la sincronización inicial;
  • ver las operaciones de sincronización y sus tareas por registro, y reintentar una tarea fallida;
  • resolver los conflictos que la política dejó pendientes;
  • consultar y volver a emitir la dirección que recibe los webhooks de la conexión.

La sincronización fiable ya funciona en segundo plano: el trabajador se activa cada 5 segundos y procesa lotes de 20 tareas, con una reserva de 2 minutos por tarea. La conciliación por consultas se ejecuta cada 30 segundos, con lotes de 20 cursores vencidos. No hay que activar estos procesos por separado.

Los cuatro proveedores integrados usan rutas de conexión y de entrada distintas:

ProveedorMétodo de conexiónCambios entrantes
amoCRM / KommoOAuth desde el asistenteWebhook saliente de amoCRM a la dirección emitida o consultas periódicas
Bitrix24Webhook entrante creado en tu portal; OAuth aún no está disponibleWebhook saliente del portal o consultas periódicas
RetailCRMClave API desde el asistenteWebhook de RetailCRM con un token MyBot en la cabecera o consultas periódicas
OzmaCRMCliente OIDC y usuario desde el asistenteDisparador instalado por ti en OzmaDB o consultas periódicas

Las consultas periódicas están disponibles para estos cuatro proveedores integrados. El webhook es opcional y solo reduce el tiempo de espera.

Cómo se conecta con el proveedor

Todas las solicitudes al CRM pasan por un transporte protegido:

  • Solo se admite HTTPS, sin credenciales en la dirección, puertos personalizados ni proxies heredados del entorno del proceso.
  • El nombre del servidor se resuelve antes de cada solicitud. Se rechaza la conexión si cualquiera de sus direcciones es de loopback, privada, link-local, multicast o de metadatos de la nube. Las redirecciones deben permanecer en el mismo servidor y se verifican igual.
  • El cuerpo de la respuesta está limitado a 1 MB. El límite de tiempo es de 30 segundos para la solicitud, 10 segundos para el inicio de TLS y 15 segundos para las cabeceras de respuesta.
  • Retry-After y X-RateLimit-Reset sirven como indicaciones para reintentar, con un máximo de 5 minutos. Los límites de frecuencia los fija el propio CRM; la plataforma no añade una cuota de llamadas.
  • Los errores del proveedor se convierten en códigos breves en minúsculas. HTTP 429, 5xx y los fallos de transporte son temporales y se reintentan; los demás son definitivos. Los cuerpos de respuesta, direcciones de solicitud y mensajes de error del proveedor no se guardan en logs, errores de tareas ni auditorías.

En tres proveedores, el servidor debe pertenecer al conjunto permitido que se deduce de la cuenta:

  • amoCRM y Kommo: <cuenta>.amocrm.ru o <cuenta>.kommo.com.
  • Bitrix24: <portal>.bitrix24.ru o <portal>.bitrix24.com. El intercambio confidencial de tokens se realiza además con el servidor fijo oauth.bitrix.info.
  • RetailCRM: <cuenta>.retailcrm.ru.

OzmaCRM es la excepción porque permite instancias propias. Su dirección base la indica quien administra la instancia; se comprueba su formato: HTTPS sin credenciales, puerto, ruta, parámetros de consulta ni fragmento. El bloqueo de solicitudes a direcciones privadas descrito arriba impide conectarla a un servidor interno.

amoCRM y Kommo

Antes de conectar. El operador de la plataforma registra una integración OAuth y configura AMOCRM_CLIENT_ID y AMOCRM_CLIENT_SECRET conjuntamente. APP_BASE_URL debe ser el origen HTTPS absoluto, ya que el URI de retorno será <APP_BASE_URL>/api/integrations/crm/amocrm/callback. Hasta que esté configurado, los endpoints de conexión devuelven 503.

Conexión. Usa la tarjeta amoCRM del asistente. Mediante REST, el propietario del bot envía el servidor de su cuenta y abre la dirección recibida:

curl -X POST "$BASE_URL/api/bots/$BOT_ID/crm/connections/amocrm/start" \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{"account_key":"acme.amocrm.ru"}'

La respuesta contiene redirect_url. El estado de la autorización en el navegador se usa una sola vez, dura 5 minutos y se guarda como hash. Se permiten hasta tres inicios por minuto y cuenta. Rechazar el consentimiento también consume ese estado, de modo que no se puede repetir el mismo retorno con un código falsificado.

Comprobación al conectar. Tras intercambiar los tokens, se vuelve a leer la cuenta mediante GET /api/v4/account. El subdominio devuelto debe coincidir con la cuenta indicada y su moneda debe ser un código ISO 4217 válido. Si no, se rechaza la conexión. Los tokens se cifran vinculados a la conexión, el bot, el proveedor, el servidor normalizado, la versión de clave y la revisión de credenciales. Un texto cifrado copiado a otra conexión o subdominio no se puede abrir allí.

Funciones disponibles. Clientes, leads, negocios, conversaciones, webhooks, consultas periódicas, OAuth y moneda de la cuenta.

Campos y embudos. Se descubren los campos personalizados de contactos y leads bajo claves custom:<id del campo>. Un campo calculado nunca se puede escribir; multiselect se marca como múltiple y un tipo que MyBot desconozca solo se ofrece para lectura. Los embudos y sus estados se obtienen de GET /api/v4/leads/pipelines.

Escritura. Los contactos y leads se envían con request_id igual a la clave de idempotencia del registro, de hasta 255 caracteres. La respuesta debe contener exactamente un registro con esa misma clave; de otro modo, el resultado se considera ambiguo.

Conversaciones. Se exportan como notas ordinarias de contactos o leads. El resumen y cada mensaje recibido se limitan a 24 000 caracteres, solo se conservan los 50 mensajes más recientes y el texto unido se recorta a 6 000 caracteres.

Webhooks. amoCRM y Kommo no firman el cuerpo. La dirección opaca que MyBot emite al crear la conexión sirve de secreto. El adaptador acepta JSON o formularios codificados de hasta 256 KB, rechaza claves JSON duplicadas, datos adicionales al final y más de 64 niveles de anidamiento. Cada entrega debe contener exactamente un evento de entidad. Si aparece account[subdomain], debe coincidir con la cuenta conectada. Se admiten altas y cambios de contactos, así como altas, cambios y cambios de estado de leads. Después se vuelve a leer el registro mediante la API y se comprueba que su updated_at no sea anterior al evento: el estado fiable procede de la API, nunca del cuerpo del webhook.

Consultas periódicas. Los contactos se recorren por updated_at ascendente, en páginas de 50, con un cursor cifrado.

Bitrix24

Bitrix24 tiene dos métodos de conexión, pero por ahora solo funciona uno.

Webhook entrante: método disponible. Crea en tu portal «Aplicaciones → Webhooks → Webhook entrante». Necesitas el dominio del portal, el member_id y el código de webhook de esa página. Puedes introducirlos en la tarjeta Bitrix24 del asistente o enviar:

curl -X POST "$BASE_URL/api/bots/$BOT_ID/crm/connections/bitrix24" \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Portal","account_key":"acme.bitrix24.ru","member_id":"…","webhook_token":"…"}'

El portal, el member_id y el token se cifran juntos. Las solicitudes REST usan la ruta /rest/<member_id>/<token>/<método>.json. Este método no tiene refresh token y la conexión indica que OAuth no está disponible. Como el token forma parte de la ruta, los errores de transporte se reducen siempre a un código estable y nunca muestran la dirección.

OAuth: aún no disponible. POST /api/bots/{botID}/crm/connections/bitrix24/start devuelve 503: la plataforma solo lee AMOCRM_CLIENT_ID y AMOCRM_CLIENT_SECRET, y no tiene una aplicación OAuth propia para Bitrix24. En el asistente, el botón Mediante OAuth aparece deshabilitado; el formulario Mediante webhook entrante sigue disponible. La descripción siguiente es solo una referencia para cuando exista la aplicación.

Modo OAuth futuro. El consentimiento se daría en https://<portal>/oauth/authorize/ y el intercambio de tokens usaría oauth.bitrix.info. La respuesta debe indicar ese dominio de tokens y el endpoint de cliente exacto https://<portal>/rest/; de lo contrario, se rechaza por discrepancia de portal. El member_id devuelto es obligatorio y se guarda para autenticar los webhooks posteriores.

Recepción de webhooks. Las entregas se verifican mediante application_token. Sin BITRIX24_APPLICATION_TOKEN en el despliegue, se rechazan antes de leer el cuerpo. Ambos métodos de conexión comunican esta situación mediante inbound_warning, que se muestra por separado en la interfaz. Así puedes evitar configurar una dirección que rechazaría todas las entregas. Las consultas periódicas siguen funcionando.

Permisos mínimos. Concede solo los permisos CRM necesarios para tus correspondencias. El adaptador usa profile, crm.contact.fields, crm.lead.fields, crm.deal.fields, crm.dealcategory.list, crm.status.list, crm.contact.list, crm.{contact,lead,deal}.{add,update,get} y crm.timeline.comment.add.

Funciones disponibles. Clientes, leads, negocios, conversaciones, webhooks, consultas periódicas y claves externas idempotentes. Bitrix24 no comunica la moneda de la cuenta, así que una correspondencia monetaria debe indicar expresamente la moneda ISO.

Campos y embudos. Se leen los campos de contactos, leads y negocios, incluidos los indicadores de solo lectura y de valor múltiple. Los embudos son categorías de negocios; los estados se leen con crm.status.list y el filtro DEAL_STAGE_<id de categoría>.

Contactos o leads. Por defecto, los clientes se guardan como contactos. La configuración {"customer_entity":"lead"} cambia la escritura a leads.

Escritura. crm.<entidad>.add y crm.<entidad>.update se llaman con REGISTER_SONET_EVENT=N para no llenar el feed de actividad. Crear un registro requiere un campo de clave externa asignado y editable; sin él, se rechaza la creación para evitar un registro que no pueda vincularse.

Conversaciones. Se añaden como comentarios en la cronología de un contacto, lead o negocio con el prefijo [mybot:<clave de idempotencia>], que permite reconocer un reenvío. El texto unido se recorta a 32 000 caracteres.

Webhooks. application_token y member_id se comparan en tiempo constante; auth.domain debe coincidir con el portal conectado. Se acepta solo JSON de hasta 256 KB, sin datos adicionales al final. Se procesan ONCRMCONTACTADD/UPDATE/DELETE, ONCRMLEADADD/UPDATE/DELETE y ONCRMDEALADD/UPDATE/DELETE. Salvo en las eliminaciones, se vuelve a leer el registro con crm.<entidad>.get y su ID debe coincidir con el evento.

Consultas periódicas. crm.contact.list se ordena por DATE_MODIFY e ID y continúa desde un punto de control cifrado.

RetailCRM

Antes de conectar. Necesitas una clave API. Esta integración no usa OAuth: la autorización y la renovación indican que ese método no está admitido; la clave API es la única credencial.

Conexión. Usa la tarjeta RetailCRM del asistente o esta solicitud:

curl -X POST "$BASE_URL/api/bots/$BOT_ID/crm/connections/retailcrm" \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tienda","account_key":"acme.retailcrm.ru","api_key":"…"}'

name es opcional; por defecto se usa el servidor de la cuenta. La respuesta contiene un resumen seguro de la conexión, la dirección receptora de webhooks y su token, pero nunca la clave API.

Permisos mínimos. Al conectar, el adaptador lee /api/credentials y los directorios sites, stores y order-methods; cada uno debe contener al menos una entrada válida. Para exportar conversaciones se necesita además customer_write o, en cuentas antiguas, el permiso /api/v5/customers/notes/create. Si falta, la conexión informa de que no se pueden exportar conversaciones antes de intentar hacerlo.

Funciones disponibles. Clientes, negocios, pedidos, webhooks, consultas periódicas y claves externas idempotentes. La exportación de conversaciones depende del permiso anterior.

Campos y embudos. Los campos personalizados se leen de /api/v5/custom-fields por separado para clientes y pedidos, con claves custom:<código>. Solo se ofrecen para escritura si RetailCRM los marca editable. La detección lee 250 campos por página, hasta 100 páginas y 10 000 campos. Los estados de pedidos se agrupan por sitio; cada sitio es un embudo distinto.

Escritura. Los clientes y pedidos se crean o actualizan con formularios de /api/v5/customers/... y /api/v5/orders/.... El servidor añade la clave API: nunca forma parte de la correspondencia de campos. El ID local de MyBot se guarda en externalId. Si el ID devuelto no coincide con el registro vinculado, el resultado se marca como ambiguo y el vínculo no se reasigna sin avisar.

Conversaciones. Se exportan como nota del cliente, con un máximo de 2 000 caracteres.

Webhooks. RetailCRM no firma sus llamadas. MyBot emite al crear la conexión un token que muestra una sola vez. Ponlo en la cabecera X-Mybot-Webhook-Token de la plantilla de webhook de RetailCRM. Todas las entregas deben incluirla; se compara en tiempo constante. El cuerpo está limitado a 64 KB; el tipo debe ser customer u order y el evento, create, update o delete. Salvo las eliminaciones, se vuelve a leer el registro por ID porque el cuerpo de la plantilla solo identifica cuál cambió.

Consultas periódicas. Se leen /api/v5/customers/history y /api/v5/orders/history, en páginas de 50, continuando con sinceId o startDate.

OzmaCRM

Creación automática de contactos desde el chat

Por defecto, los contactos nuevos se revisan manualmente. Para activar la creación automática en un Ozma CRM genérico, un administrador de Ozma debe instalar una acción transaccional de confianza mybot-contact-v1 y un registro de claves para la entidad de clientes configurada. Indica en la configuración del CRM el esquema y el nombre de la acción y del registro, y confirma las condiciones. Los campos de búsqueda por correo o teléfono siguen disponibles para la revisión manual.

Antes de activarla, rellena el registro con todos los contactos existentes. Su key debe ser una cadena única obligatoria y contact, una referencia a la entidad de clientes. Todos los que escriban en el CRM deben usar la misma normalización y el mismo registro. MyBot comprueba los metadatos del registro y el diario de operaciones, pero no puede verificar la acción instalada, que el relleno esté completo ni a otros escritores. Si no se cumplen estas condiciones, pueden aparecer duplicados: mantén la revisión manual.

La acción debe reservar las claves normalizadas del contacto, encontrar o crear al cliente y guardar la clave estable de la operación en una sola transacción. Un reintento idéntico debe devolver el resultado original. Los contactos existentes requieren confirmación manual. Los correos y teléfonos anteriores permanecen como claves protectoras del registro; si una dirección se reasigna, un administrador del CRM debe revisar y corregir el registro. Los contactos en conflicto deben producir un error, no una fusión. La disponibilidad de la acción se comprueba en su primera invocación. Un ejemplo del contrato y de la acción de servidor está en integrations/ozma-widget-contact/ del backend.

Para una conexión antigua sin secreto de disparador, mantén la revisión manual o crea y configura una conexión nueva de Ozma. Desactivar la creación automática no elimina contactos ni cambia los campos de búsqueda manual.

Búsqueda de contactos mediante una vista con nombre

Si un contacto no se puede encontrar por un único campo de texto de la entidad de clientes, por ejemplo porque el correo y el teléfono están en tablas distintas, puedes usar una vista de Ozma con nombre en lugar de campos de búsqueda. Indica el esquema y la entidad del contacto, por ejemplo base.people, por separado del esquema de la vista. En la configuración del CRM, selecciona Vista de Ozma con nombre e introduce el esquema y el nombre de la vista, un argumento de correo y/o de teléfono, la columna con el ID numérico del registro de la entidad de clientes de la conexión, hasta tres columnas de nombre y hasta ocho argumentos más que MyBot pasa como null. Por ejemplo: vista crm / find_contact, argumentos email y phone, columna de ID pid, columnas de nombre first_name, last_name, patronymic, argumentos nulos name, telegram, telegram_id. Los nombres usan letras latinas minúsculas, dígitos y _.

La vista solo encuentra candidatos y no cambia nada en el CRM. Al guardar, MyBot la llama con todos los argumentos en null, sin enviar datos de contacto, para comprobar el acceso de lectura y las columnas configuradas. El correo y el teléfono se buscan en solicitudes separadas: solo un argumento tiene valor y el resto se pasa como null, de modo que una condición OR en la vista no pueda ampliar la búsqueda. Las filas con el mismo ID se combinan en un solo candidato. Si se devuelven IDs distintos o demasiadas filas, la búsqueda se detiene para revisión manual. El ID encontrado también se comprueba contra la entidad de clientes de la conexión.

Revisa manualmente cada coincidencia. Un resultado vacío no demuestra que no haya un duplicado: la vista define las reglas de coincidencia, los formatos de datos y el acceso a las filas.

MyBot envía el correo recortado y en minúsculas y el teléfono en formato E.164 con un + inicial, por ejemplo +79161234567. Una vista que compare el teléfono con un LIKE parcial sobre la cadena original no encontrará números guardados como 79161234567 o 8 (916) 123-45-67. Compara solo los dígitos, por ejemplo con regexp_replace(ways.data, '[^0-9]', '', 'g'), y cubre las variantes del número nacional. Condiciones de la vista como «solo clientes» ocultan otros registros de la búsqueda, y las filas eliminadas siguen coincidiendo si la vista no las excluye. Si una pantalla del CRM también usa la vista, suele ser más sencillo crear una vista aparte para MyBot. Ordena las filas por la columna de ID de forma ascendente: de lo contrario, un resultado de más de una página (100 filas) se considera incompleto.

Los modos no se pueden combinar: la búsqueda por vista excluye los campos de búsqueda y la creación automática de contactos. Un solo guardado cambia de modo: al elegir la vista se borran los campos de correo, teléfono y nombre, y al volver a los campos se desactiva la vista. Desactiva la creación automática antes de activar la vista. Mientras las solicitudes del chat estén activadas, la búsqueda no se puede desactivar por completo: desactiva primero las solicitudes del chat o guarda el otro modo.

En la integración Ozma de Gogol, el propietario del proyecto puede seleccionar manualmente un contacto para una solicitud del chat. Abre la pestaña CRM de la persona y selecciona Elegir contacto de Ozma. La búsqueda usa el correo del perfil o el teléfono si no hay correo. Compara el contacto con el perfil, marca la confirmación y selecciona Confirmar selección. Si la lista está incompleta, precisa los datos y actualiza la búsqueda. La confirmación pone la transferencia en cola; comprueba el resultado en el registro.

Un teléfono coincidente no acredita la identidad del visitante. La selección no une perfiles de MyBot ni sus historiales. Este proceso corresponde a la integración configurada de Gogol y no presupone el mismo esquema de datos en todas las instalaciones de Ozma.

OzmaCRM es una solución CRM/ERP low-code basada en OzmaDB, disponible en ozma.io. Como no tiene un esquema CRM fijo, debes indicar a MyBot qué entidades usar.

Antes de conectar, prepara:

  • La dirección base de la instancia. En la nube tiene la forma https://<cuenta>.api.ozma.org; en una instalación propia puede ser cualquier origen HTTPS que administres.
  • Un ID y un secreto de cliente OIDC, además del usuario. La autenticación usa el flujo OIDC resource-owner password grant con las credenciales de cliente de tu cuenta.
  • El nombre de usuario y la contraseña de OzmaCRM con los que trabajará MyBot. Dale el rol mínimo que permita leer y escribir las entidades elegidas.
  • Para una instalación propia, la dirección base OIDC y el realm. En la nube, por defecto se usa el realm default en https://account.ozma.io, con endpoint /auth/realms/<realm>/protocol/openid-connect/token.
  • La entidad de registro usr.mybot_sync_marks descrita abajo. Créala antes de conectar: sin ella falla la comprobación de conexión.

El refresh token es obligatorio. La caducidad del access token se comprueba localmente: al vencer, el adaptador devuelve token_expired y vuelve a cifrar la conexión antes del siguiente envío, en vez de renovar el token a mitad de una escritura.

Entidades elegidas. La conexión contiene una configuración breve:

  • customer_entity: esquema y entidad de clientes, obligatoria.
  • deal_entity: esquema y entidad de negocios, obligatoria.
  • conversation_entity: entidad opcional para registrar conversaciones.
  • deal_status_field: columna cuyo dominio se usa como embudo.
  • updated_at_field: columna de fecha de modificación, updated_at por defecto.

Los nombres de esquemas, entidades y campos deben contener solo letras ASCII minúsculas, números y guiones bajos; no pueden comenzar con un número ni superar 64 caracteres. No es solo una regla de formato: se insertan en FunQL, por lo que estas restricciones protegen las consultas contra inyecciones.

Acción de escritura para un esquema complejo de Ozma

Cuando los datos del contacto o de la solicitud abarcan varias entidades, un desarrollador de Ozma puede instalar una acción que realice todas las escrituras necesarias en una sola transacción. En la configuración del CRM, indica su esquema y nombre en Acción de escritura de Ozma. Esto define cómo se escribe; no activa la creación automática de contactos ni sustituye la búsqueda de contactos y la revisión manual.

MyBot envía operation_id, fingerprint, entity_kind, marker, la entity configurada, fields y, para un registro existente, remote_id. La acción devuelve un ID numérico como {"result":{"remote_id":123}}. Debe gestionar los reintentos de forma idempotente: el mismo operation_id y fingerprint devuelven el resultado original, y el mismo operation_id con datos distintos no debe crear otra escritura. Para ello hace falta usr.mybot_crm_effects con un operation_id único; el desarrollador de Ozma configura la lógica de negocio, el diario y los derechos de acceso. La conexión también necesita un secreto de disparador. MyBot no instala la acción automáticamente.

El ejemplo del backend integrations/gogol-ozma/crm-write.mjs está escrito para base.people, con correos y teléfonos en base.communication_ways; no está listo para instalarse sin revisión y adaptación. Lee el correo y el teléfono solo de email_sys y phone_sys y escribe tal cual en la entidad del contacto cualquier otra clave de fields. Por defecto MyBot envía name, email, phone y tags; si esas columnas no existen, o si email y phone son referencias como en base.people, la acción falla. Hay dos opciones:

  • mediante la API o la herramienta MCP configure_ozma_widget_contact_search, activa mapped_writes_only y asigna profile.email a email_sys, profile.phone a phone_sys y el nombre a columnas reales como first_name y last_name;
  • o adapta la acción para que lea email y phone y no escriba name y tags directamente en el contacto.

El ejemplo también necesita crm.mybot_person_keys (una key de cadena con restricción de unicidad y una referencia contact) y usr.mybot_sync_marks. La cuenta de la conexión necesita permiso para ejecutar la acción, y el rol con el que se ejecuta la acción necesita acceso de lectura y escritura a todas las entidades que usa. Un error de la acción llega a MyBot como write_action_failed: las respuestas 429 y 5xx se reintentan con el mismo operation_id, y las demás detienen la tarea para su revisión. Las escrituras que eluden la acción no quedan cubiertas por esta protección.

Tras desactivar la acción, las escrituras posteriores usan el método de sincronización estándar. Comprueba que sea adecuado para tu esquema antes de desactivar la acción.

Registro de sincronización. OzmaCRM es el único proveedor cuyas marcas causales de MyBot no pueden guardarse en tus propios registros. Se guardan en una entidad aparte que debes crear tú. MyBot nunca despliega ni reemplaza el esquema, porque cargar un diseño podría sobrescribir tus datos. Créala antes de activar la sincronización:

create entity usr.mybot_sync_marks with fields:
  entity_kind string not null   -- customer | lead | deal | order | conversation
  remote_id   string            -- nullable: vacío para la primera marca de un registro nuevo
  marker      string not null   -- clave de idempotencia del efecto
  direction   string not null   -- outbound | inbound
  created_at  datetime not null

La comprobación consulta /api/check_access, luego esta entidad y por último las entidades configuradas. Si el registro falta o es incompatible, devuelve missing_sync_marks_entity junto con la definición anterior y no activa la sincronización.

Campos y embudos. Las columnas editables se descubren mediante la información de cada entidad; se omite id. int y double se convierten en entero, bool en booleano, date y datetime en fecha u hora y string, reference, enum y uuid en texto. Una columna de tipo array usa su subtipo y se marca como múltiple. Las columnas cuyo tipo MyBot no reconoce se omiten y se muestran en el apartado de datos sin correspondencia de la vista previa. Como OzmaDB no define embudos, el dominio de deal_status_field se convierte en un embudo sintético.

Escritura. Cada cambio usa un solo POST /api/entities/transaction con dos operaciones: la escritura del registro y la inserción en el registro de sincronización. Ambas se confirman juntas, por lo que nunca puede existir una marca sin el cambio correspondiente. Si falla la transacción, el error identifica cuál de las dos operaciones falló.

Tus entidades deben aceptar estas columnas, que MyBot escribe directamente:

  • Cliente: name y, cuando existan, phone, email, tags y las columnas asignadas que la detección marcó como editables.
  • Negocio: name, status, amount_minor, currency, customer (ID del cliente vinculado) y tags. Cada negocio necesita estado y moneda de tres letras.
  • Conversación: customer o deal (ID del propietario), summary y created_at.

Antes de enviar la solicitud se descarta cualquier valor asignado a una columna que no esté marcada como editable. Así, una revisión de la correspondencia no puede forzar la escritura en una columna que no se ofreció.

Conversaciones. El resumen y cada mensaje tienen un máximo de 16 384 bytes. Se conservan los 50 mensajes más recientes y el texto unido se recorta a 32 000 bytes sin dividir un carácter UTF-8.

Consultas periódicas. Los cambios se leen con una consulta FunQL por claves, ordenada por tu columna updated_at y por id, en páginas de 200. La siguiente página empieza estrictamente después del último registro devuelto, por lo que las ventanas de consulta superpuestas no omiten ni duplican registros. Cada fila se une por la izquierda con el registro de sincronización para distinguir un cambio entrante del eco de una escritura previa de MyBot.

Disparador para recibir cambios antes de la próxima consulta. OzmaDB no tiene webhooks propios. Puedes instalar un disparador AFTER INSERT/UPDATE en las entidades de clientes y negocios, desde la interfaz de OzmaDB o FunApp. Al crear la conexión, MyBot emite una dirección receptora y el secreto X-Mybot-Trigger-Secret. El disparador debe enviar un evento pequeño:

export default async function handler(args, ctx) {
  await OzmaDB.enqueueHttpRequest({
    url: '<dirección receptora>',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Mybot-Trigger-Secret': '<secreto>'
    },
    body: JSON.stringify({
      entity_kind: 'customer',
      remote_id: args.id,
      changed_at: new Date().toISOString()
    }),
    maxRetries: 10,
    retryBaseDelayMs: 2000
  })
}

entity_kind acepta customer o deal. Usa enqueueHttpRequest, que entrega la solicitud al menos una vez desde una cola de salida, y no una llamada síncrona: si MyBot tarda o no está disponible, tu transacción no debe bloquearse. Las entregas repetidas son normales y se deduplican por ID de evento. El cuerpo está limitado a 64 KB. Si no instalas el disparador, la conexión sigue funcionando mediante consultas periódicas.

MyBot nunca instala el disparador por ti ni devuelve su código por API: cargar un diseño en OzmaDB reemplazaría esquemas completos y podría destruir tus datos.

Detección y correspondencia de campos

Si otra persona cambió la correspondencia antes de que guardes, aparece un aviso de conflicto de revisión y los valores introducidos permanecen en el editor abierto. Cópialos antes de actualizar la página: el borrador del editor no se conserva tras recargar. Actualiza la página, compara la correspondencia actual con tus cambios, vuelve a introducir los ajustes acordados y guarda.

La correspondencia define qué campos se transfieren entre GetMyBot y el CRM. Cada guardado crea una nueva revisión. Las tareas que ya estaban en cola usan la revisión anterior: cambiar la configuración hoy no modifica una tarea antigua.

Cada regla de correspondencia indica:

  • una ruta local: profile.id, profile.name, profile.first_name, profile.last_name, profile.phone, profile.email, profile.tags o cualquier otra propiedad profile.<propiedad>; para negocios, deal.id, deal.customer_id, deal.name, deal.pipeline, deal.status, deal.amount_minor (o deal.value_minor), deal.currency o cualquier otra propiedad deal.<propiedad>;
  • la clave remota elegida entre los campos detectados;
  • la entidad: cliente, lead, negocio o pedido;
  • la dirección: saliente (MyBot → CRM) o entrante (CRM → MyBot);
  • la transformación;
  • si el valor es obligatorio.

Transformaciones

Se admiten identity, string, integer, boolean, timestamp, datetime_rfc3339, phone_e164, email_normalized, enum_map, tags y money_minor_currency. minor_units permanece para correspondencias creadas antes de que el dinero tuviera una moneda explícita.

Son reglas declarativas, nunca código aportado por el cliente:

  • email_normalized elimina espacios laterales, pasa a minúsculas, exige un formato de correo y rechaza más de 320 caracteres.
  • phone_e164 admite espacios, guiones y paréntesis como separadores; produce un número que empieza con +, de 9 a 16 caracteres, pero nunca con +0.
  • string limita el valor a 10 000 caracteres.
  • tags exige texto, elimina espacios laterales y duplicados, y rechaza etiquetas vacías o de más de 128 caracteres.
  • enum_map solo traduce los valores de la lista cerrada que configuras. En la dirección entrante se invierte la lista. Si dos valores locales conducen al mismo valor remoto, el resultado entrante es ambiguo y va a los datos sin correspondencia.
  • money_minor_currency produce una cantidad entera en unidades menores y una moneda ISO 4217.

Requisitos de la correspondencia

No se puede guardar una revisión si la ruta local es desconocida, la clave remota no existe en esa entidad, un envío saliente apunta a un campo de solo lectura, enum_map no tiene valores, una regla monetaria carece de moneda ISO en mayúsculas, dos reglas escriben al mismo destino remoto en la misma dirección y entidad, dos reglas entrantes escriben al mismo destino local o la transformación no es compatible con los tipos de ambos campos. Las etiquetas deben existir en ambos lados. Un disparador debe indicar un evento conocido, su embudo y uno de sus estados.

Etiquetas: solo de entrada

Las etiquetas de MyBot nunca se envían al CRM como etiquetas. El perfil guarda sus identificadores, no los nombres legibles que compara la correspondencia. Enviarlas produciría valores opacos como 7f3c1a2e-… en la ficha del cliente. Por eso la lista de etiquetas salientes permanece vacía.

Las etiquetas entrantes sí funcionan: la correspondencia traduce y normaliza las etiquetas remotas; una etiqueta desconocida va a los datos sin correspondencia. Si necesitas mostrar una etiqueta de MyBot en el CRM, asígnala como una propiedad normal del perfil mediante enum_map.

Datos sin correspondencia (overflow)

overflow recoge los valores sin campo compatible o que no pudieron transformarse. Por ejemplo, una etiqueta desconocida recibida del CRM. En vez de descartarse, el valor original y el motivo se guardan en el campo o nota que elijas.

Cada correspondencia debe definir un destino de este tipo, con su campo o nota y una clave. También recibe valores obligatorios ausentes y propiedades sin correspondencia en cualquiera de las dos direcciones.

Política de conflictos

  • mybot_wins: un cambio remoto no sobrescribe un perfil modificado localmente.
  • crm_wins: se aplica el cambio remoto.
  • newest_wins: prevalece el cambio con la fecha más reciente; si las fechas son idénticas, queda pendiente de resolución manual.
  • manual: cada cambio conflictivo queda pendiente de resolución manual.

Un perfil sin cambios locales registrados acepta el cambio remoto con cualquier política. Independientemente de la política, se ignora un cambio remoto cuya fecha no sea posterior al último cambio remoto aplicado al vínculo.

Vista previa de la correspondencia

Antes de sincronizar, comprueba el resultado con fichas reales. La vista previa aplica las reglas a una muestra y enseña los valores que se enviarían. No escribe nada en el CRM; el resultado depende de la configuración y de los datos elegidos.

Toma hasta 20 perfiles de suscriptores y, para cada campo, muestra el valor original, el transformado, los avisos y los errores. También enumera los datos que irían a overflow. Indica cuántos registros se verían afectados: el recuento es exacto si la consulta local está completa o estimado si solo hay una estimación limitada.

La lista de negocios siempre está vacía, tanto aquí como en la sincronización inicial. MyBot no tiene un objeto de negocio propio antes de conectarse al CRM: solo puede exportar perfiles de suscriptores. Los negocios llegan desde el CRM y se convierten en eventos y objetivos del cliente, como se explica en Negocios, importes y atribución. Puedes configurar sus campos para los cambios entrantes y para los negocios que envíes desde un diálogo.

La sincronización inicial se inicia con una solicitud aparte. Exige confirmación explícita, una clave de idempotencia y la revisión de la correspondencia que aparece en pantalla. Una revisión obsoleta devuelve 409.

Escrituras salientes, vínculos e idempotencia

Cada escritura lleva una clave de idempotencia estable por registro y guarda un vínculo entre su ID local y el ID remoto, junto con la versión remota y las últimas fechas de cambio local, remoto y sincronizado. Gracias a ese vínculo, y no a una suposición, un reenvío se convierte en una actualización.

Cada proveedor guarda la clave mediante su mecanismo: request_id en amoCRM y Kommo; un campo de clave externa y una marca en el comentario en Bitrix24; externalId en RetailCRM; y una fila transaccional del registro en OzmaCRM.

Recepción de webhooks y confianza

MyBot recibe cambios por consultas periódicas o por webhook. Hay cuatro rutas de webhook, una por proveedor, y cada una verifica la entrega a su manera:

RutaComprobación de autenticidad
POST /hooks/crm/{routeKey}/amocrmEl cuerpo no está firmado: el secreto es la ruta opaca; además, account[subdomain] debe coincidir con la cuenta conectada
POST /hooks/crm/{routeKey}/bitrix24application_token y member_id se comparan en tiempo constante; auth.domain debe coincidir con el portal
POST /hooks/crm/{routeKey}/retailcrmLa cabecera X-Mybot-Webhook-Token emitida por MyBot se compara en tiempo constante
POST /hooks/crm/{routeKey}/ozmacrmLa cabecera X-Mybot-Trigger-Secret emitida por MyBot se compara en tiempo constante

La clave de ruta es aleatoria para cada conexión y solo se guarda como hash. El proveedor queda fijado al registrarla. Si se envía un cuerpo de amoCRM a una ruta de RetailCRM, a una conexión desconectada o a una ruta inexistente, se recibe el mismo 404. Una entrega dirigida a la ruta correcta que falla la verificación del adaptador recibe un 400 genérico. Ninguna respuesta revela si existe una ruta o conexión. El cuerpo tiene un máximo de 256 KiB y se dan 10 segundos para leerlo.

Cómo obtener la dirección. La dirección completa se muestra una sola vez al crear la conexión, junto con el token de RetailCRM o el secreto del disparador de OzmaCRM. Cópiala entonces: no se guarda en texto claro ni se puede volver a mostrar. Si la perdiste, abre la tarjeta de conexión y pulsa Reissue inbound address (requiere el permiso Secretos de integraciones) o llama a POST /api/bots/{botID}/crm/connections/{connectionID}/webhook-route. La dirección anterior deja de funcionar inmediatamente; actualiza el CRM con la nueva.

Si el servidor no tiene configurada una dirección pública, la interfaz indicará que no puede mostrar la dirección receptora. Debe corregirse la configuración de la plataforma.

Cambios entrantes y supresión del eco

Tanto los webhooks verificados como las consultas periódicas pasan por el mismo proceso de normalización.

El eco aparece cuando MyBot escribe en el CRM y el CRM comunica esa misma escritura como un cambio entrante. Se suprime una sola vez por efecto:

  1. La escritura saliente coloca una marca en el registro remoto y la guarda como esperada para ese vínculo.
  2. El cambio entrante se suprime solo si trae una marca todavía esperada para esa conexión y ese registro remoto, de menos de 24 horas y observada no después del último cambio remoto conocido del vínculo.
  3. Después, la marca se consume.

Una modificación posterior hecha por una persona se considera real, aunque deje el mismo valor que acababa de enviar MyBot. Una marca que nunca vuelve como eco caduca; perder un webhook no bloquea para siempre la sincronización entrante.

Por eso no se usa el ID del vínculo para suprimir ecos: permanece igual durante toda su vida y ocultaría también las modificaciones humanas posteriores.

Cuando un cambio supera la supresión y la política de conflictos, los valores asignados modifican el perfil con un origen auditable para cada propiedad: conexión, vínculo, proveedor, ID y versión remotos y fecha del cambio. Un valor vacío limpia un campo entrante opcional; en uno obligatorio va a overflow.

Conciliación manual

Las consultas periódicas avanzan automáticamente los cursores vencidos cada 30 segundos. También puedes pedir que una conexión se ponga al día inmediatamente:

curl -X POST "$BASE_URL/api/bots/$BOT_ID/crm/connections/$CONNECTION_ID/reconcile" \
  -H "Authorization: Bearer $PAT"

Una ejecución satisfactoria devuelve 202 y un informe de los recursos consultados y fallidos. Los errores se distinguen para no presentar una conexión rota como sana: 409 si ya hay una conciliación en curso, 422 si la conexión no puede consultarse y probablemente requiere volver a autorizarla, 502 si falló la consulta de todos los recursos.

Úsala tras una caída del proveedor, una entrega que crees perdida o un cambio del CRM que no aparece en MyBot. Repetirla es seguro: el vínculo y la clave de idempotencia identifican los cambios ya aplicados.

La interfaz todavía no tiene un botón para esta operación. Solo está disponible por API, con el alcance crm:write y el permiso del bot Reacciones.

Leer y escribir datos del CRM desde una reacción

Además de sincronizar clientes, una reacción puede consultar el CRM con Read from CRM (crm_query) o escribir en él con Write to CRM (crm_write). Ambas acciones usan la misma conexión que la sincronización y no necesitan una correspondencia de campos.

Read from CRM. Elige una conexión y un objeto, indica filtros, campos, orden, límite y una clave de contexto para el resultado. Devuelve una lista de objetos cuyas claves son los códigos de los campos del CRM. Por ejemplo, para buscar los negocios abiertos de un cliente por teléfono, elige deal, filtra PHONE por {{param.phone}}, establece el límite en 5 y guarda el resultado como deals. Después podrás usar {{ctx.deals}} en la reacción. Cada página contiene 50 registros por defecto y hasta 500, o menos si el propio CRM impone otro límite. El campo Page info key guarda has_more y next_offset para pedir la página siguiente.

Write to CRM. Elige un objeto, la operación Create o Update, y rellena los campos con valores de su tipo correspondiente. Una actualización requiere el ID del registro y no puede estar vacía. El editor muestra los campos del catálogo CRM, marca los obligatorios, omite los de solo lectura y enseña los valores permitidos en los campos de referencia. El resultado es un objeto con id y object.

Ten en cuenta lo siguiente:

  • Los nombres de objetos y campos se fijan en la configuración y no admiten sustituciones. Los valores e identificadores sí las admiten.
  • Si el catálogo CRM no está disponible, puedes introducir el objeto y los campos manualmente; el servidor los comprobará.
  • Preview read consulta como máximo 20 registros y solo admite valores literales, sin sustituciones. Puedes pasar el resultado al analizador con Use as parser sample. Si cambias los filtros, se oculta la vista previa anterior.
  • Las escrituras no se reintentan automáticamente. Si se desconoce el resultado, por ejemplo porque se cortó la conexión, el paso y su ruta de error indican «indeterminado». Comprueba el CRM antes de repetir la operación.
  • Sincronizar con el CRM (crm_sync) también está disponible en reacciones, además de campañas. Una clave de contexto opcional recibe los customer_id y deal_id remotos cuando se conocen.
  • Los errores del proveedor, los límites del plan y los errores al interpretar la respuesta se registran como pasos fallidos en la traza y activan la ruta de error configurada.

Objetos por proveedor

ProveedorObjetos
Bitrix24lead, deal, contact, company, quote, smart_invoice, procesos inteligentes dynamic_<id del tipo>, tareas task, usuarios user (solo lectura), listas universales list_<tipo>_<id>
amoCRM / Kommoleads, contacts, companies, customers (si está activada la función de compradores), elementos de catálogo catalog_<id>, tasks, users (solo lectura), embudos pipelines (directorio)
RetailCRMorders, customers, customers-corporate, tasks; directorios statuses, order-types, payment-types, delivery-types, sites, products
OzmaCRMEntidades del catálogo Ozma de la instancia conectada

Ejemplo en Bitrix24: para asignar una tarea a un responsable tras recibir una solicitud en el bot, añade Write to CRM, objeto task, operación Create, con TITLE = Llamar a {{param.name}} y RESPONSIBLE_ID = número 42.

Comprobación de conexión y campo marcador

El botón Probar conexión solo lee: no crea campos ni cambia datos en el CRM. El campo de servicio que marca los registros de MyBot se crea en otro paso explícito del asistente, al activar la sincronización. Si solo usas acciones de lectura y escritura, no necesitas crear ese campo.

Acciones desde la conversación

Quien atiende una conversación puede consultar el estado CRM de esa persona y enviarla manualmente. El menú CRM del diálogo tiene Sincronizar ahora y Exportar conversación…; la ficha del suscriptor tiene una pestaña CRM con el vínculo y la última sincronización. Todas estas acciones requieren el permiso del bot Diálogos.

Hay tres rutas REST:

  • GET /api/bots/{botID}/subscribers/{subscriberID}/crm/status (subscribers:read): informa si el suscriptor está vinculado, a qué conexión y registro remoto, cuándo se sincronizó por última vez y el resultado de la última tarea.
  • POST /api/bots/{botID}/subscribers/{subscriberID}/crm/sync (subscribers:write): envía al suscriptor ahora. El cuerpo incluye connection_id y puede añadir un deal opcional con nombre, embudo, estado, value_minor, currency y propiedades adicionales. Ese negocio se crea o actualiza con el cliente. El menú del diálogo solo envía al cliente: allí no se puede elegir embudo ni estado. La proyección del suscriptor es igual a la de la sincronización en segundo plano.
  • POST /api/bots/{botID}/subscribers/{subscriberID}/crm/export-conversation (subscribers:write): exporta la conversación como nota. El cuerpo solo incluye connection_id; el contenido permitido se explica a continuación.

Cada acción devuelve el mismo objeto de operación fiable que aparece en el registro de sincronización. Por tanto, las acciones manuales figuran junto con las demás operaciones de la conexión.

Qué contiene una conversación exportada

La exportación es un extracto recortado y depurado, no una transcripción íntegra. Antes de que los datos salgan de MyBot:

  • Se conservan como máximo los 50 mensajes más recientes. Los anteriores se omiten, no se exportan en páginas adicionales.
  • Cada mensaje y el resumen se recortan a 4 000 caracteres.
  • Cada adjunto se convierte en el texto literal [attachment], sin nombre, enlace, tipo MIME ni tamaño. El CRM solo sabe que existía un adjunto.
  • Los autores se reducen a dos roles, customer y operator. No se identifica qué operador escribió cada mensaje.
  • Se descartan los mensajes vacíos.

Se aplican además los límites de cada proveedor al texto unido: 6 000 caracteres en amoCRM, 2 000 en RetailCRM, 32 000 en Bitrix24 y 32 000 bytes en OzmaCRM.

Las notas privadas de los operadores nunca se exportan. El código de exportación solo lee la secuencia normal de mensajes del diálogo; no tiene ninguna ruta ni campo de solicitud que acceda a la tabla de notas privadas. Consulta Chats y operadores para saber cómo funcionan esas notas.

Envío de leads cualificados por el agente de IA

El agente de IA puede enviar un lead cualificado al CRM mediante la herramienta restringida crm.sync_qualified_lead. Como escribe datos, se aplican las reglas habituales de confirmación e idempotencia del agente.

Hay dos límites para lo que el modelo puede hacer:

  • La conexión debe estar autorizada explícitamente en la política de herramientas del agente de IA del bot. La herramienta solo ve los IDs incluidos allí. Si el modelo indica otra conexión, aunque exista y pertenezca al mismo bot, se rechaza antes de ejecutar nada.
  • Los datos se limitan a campos ya configurados en la correspondencia. El modelo puede aportar hasta 20 elementos {key, value}, con claves de hasta 128 caracteres y valores de hasta 1 000. Cada clave debe ser una ruta local que la revisión actual ya envía a un campo de cliente, negocio o pedido. Una clave desconocida rechaza toda la llamada: ni descartarla ni aceptarla en silencio permitiría controlar bien qué llega al CRM.

El modelo no proporciona el texto de la conversación. Si establece export_conversation, el servidor añade el mismo extracto limitado y depurado descrito arriba. El servidor determina el suscriptor, el bot y las credenciales.

La herramienta solo devuelve el ID de la operación y su estado.

Negocios, importes y atribución

Los importes se guardan como enteros en la unidad menor de la moneda: 1250 con EUR representa 12,50 €. El formato técnico es un entero con signo de 64 bits y una moneda ISO 4217; no se usan números de coma flotante.

Se envía al proveedor la cantidad en unidades menores y se guarda la moneda en el registro unificado del negocio. Al leerla, la correspondencia monetaria advierte de que la moneda procede de la configuración. Si varía entre negocios, asígnala mediante un campo aparte.

Un cambio de negocio genera un evento del cliente llamado crm.deal_created, crm.deal_updated, crm.deal_won o crm.deal_lost. Sus propiedades pueden incluir el ID local del negocio (local_id), el embudo (pipeline) y el estado (status); no incluyen el ID del cliente, el importe ni la moneda. Un negocio ganado también genera el objetivo crm.deal_won para la atribución, donde el importe en unidades menores y la moneda se guardan por separado cuando se conocen. Para ver los ingresos en un informe de pop-up se necesita un permiso de ingresos independiente.

Privacidad y datos ocultos

  • Las credenciales no se pueden serializar: su tipo se niega a convertirse en JSON. Así no pueden aparecer por accidente en una respuesta, un log o la carga de una tarea.
  • Las credenciales y los cursores se cifran en disco y se vinculan a la conexión, el bot, el proveedor, la cuenta, la versión de clave y la revisión de credenciales. El texto cifrado copiado a otro lugar no se puede descifrar allí.
  • Al consultar una conexión solo se recibe un resumen seguro: IDs, bot, proveedor, nombre, clave de cuenta, estado, funciones, revisión de correspondencia, código del último error y fechas. No incluye credenciales cifradas ni el material de la ruta de webhook.
  • La auditoría registra que se volvió a emitir una ruta, pero no la clave nueva ni su hash.
  • Los metadatos de solicitud y respuesta que se guardan para diagnosticar fallos se reducen a método, esquema, servidor y ruta, estado HTTP y recomendación de reintento. Toda cabecera cuyo nombre contenga authorization, token, secret, api-key, cookie o password se guarda como [redacted].
  • Las conversaciones exportadas son extractos limitados con roles anónimos; las notas privadas quedan excluidas por la estructura del proceso de exportación.
  • Los cambios entrantes del perfil se auditan con su origen, de modo que cada dato escrito por el CRM puede remontarse a la conexión y el registro remoto.
  • Los vínculos CRM forman una categoría de conservación aparte de 730 días. Se incluyen en la exportación y eliminación de datos como las demás categorías.

Estado, reconexión y desconexión

Cada bot puede tener una sola conexión por combinación de proveedor y clave de cuenta. Una conexión nueva tiene estado connected; también se admiten pending, expired, disabled y failed, junto con un código estable del último error.

El botón de comprobación solo guarda el estado failed tras un error definitivo del proveedor. Un timeout, 502 o fallo de transporte no demuestran que las credenciales hayan dejado de funcionar; pulsar el botón durante una caída del proveedor no saca la conexión de las colas ni de las consultas periódicas.

Al reconectar, las credenciales se reemplazan en conjunto y se comprueba la revisión esperada. Dos solicitudes simultáneas no pueden combinar credenciales antiguas y nuevas. El cifrado depende de la revisión: tras guardar las credenciales nuevas, el texto cifrado anterior deja de aceptarse.

Para desconectarte de forma segura:

  1. Revoca primero la credencial en el CRM: acceso OAuth de amoCRM o Kommo, webhook entrante de Bitrix24, clave API de RetailCRM o cliente OIDC de OzmaCRM.
  2. Desactiva la vía de entrada que hayas configurado: suscripción al webhook en el CRM o disparador en OzmaDB.
  3. Elimina la conexión mediante Eliminar conexión en su tarjeta o DELETE /api/bots/{botID}/crm/connections/{connectionID} (crm:write). También se eliminan sus revisiones de correspondencia, vínculos y cursores, pero no se cambia nada dentro de tu CRM.

La entidad de registro de OzmaCRM te pertenece. Puedes conservarla o borrarla cuando ninguna conexión use esa instancia.

API

Salvo donde se indique otra cosa, estas rutas empiezan por /api/bots/{botID}/crm/… y requieren además el permiso del bot Reacciones. Los esquemas de solicitud y respuesta están en la Referencia de API.

Conexiones

EndpointAlcanceFunción
GET /connectionscrm:readLista de conexiones con resúmenes seguros
GET /connections/{connectionID}crm:readResumen de una conexión
POST /connections/{provider}/startcrm:writeInicia OAuth en el navegador y devuelve redirect_url; funciona con amoCRM, mientras que bitrix24 devuelve 503 hasta que haya una aplicación configurada
GET /api/integrations/crm/{provider}/callback—Destino de retorno del navegador; se autentica con un estado de un solo uso, sin token
POST /connections/bitrix24crm:writeConecta Bitrix24 mediante un webhook entrante del portal
POST /connections/retailcrmcrm:writeConecta RetailCRM mediante clave API
POST /connections/ozmacrmcrm:writeConecta OzmaCRM mediante credenciales OIDC, usuario y configuración de entidades
POST /connections/{connectionID}/webhook-routecrm:writeVuelve a emitir la dirección receptora; requiere el permiso Secretos de integraciones
PATCH /connections/{connectionID}crm:writeCambia el nombre
DELETE /connections/{connectionID}crm:writeDesconecta y elimina correspondencias, vínculos y cursores
POST /connections/{connectionID}/testcrm:writeRepite las comprobaciones de conexión y requisitos

Correspondencia y vista previa

EndpointAlcanceFunción
GET /connections/{connectionID}/fieldscrm:readCampos remotos detectados
GET /connections/{connectionID}/pipelinescrm:readEmbudos y estados
GET /connections/{connectionID}/mappingcrm:readRevisión actual de la correspondencia
PUT /connections/{connectionID}/mappingcrm:writeGuarda una revisión nueva e inmutable
POST /connections/{connectionID}/previewcrm:readAplica la correspondencia a perfiles reales sin escribir en el CRM

Sincronización

EndpointAlcanceFunción
POST /connections/{connectionID}/initial-synccrm:writeExporta perfiles; requiere confirmación, clave de idempotencia y revisión actual
POST /connections/{connectionID}/reconcilecrm:writeFuerza una conciliación inmediata
GET /operationscrm:readOperaciones más recientes primero, con paginación por clave
GET /operations/{operationID}crm:readUna operación y sus tareas
POST /operations/{operationID}/cancelcrm:writeCancela una operación en curso
POST /jobs/{jobID}/retrycrm:writeReintenta una tarea fallida
GET /conflictscrm:readTareas pendientes de resolución manual
POST /conflicts/{jobID}/resolvecrm:writeResuelve un conflicto

Las acciones desde la conversación usan subscribers:read o subscribers:write y el permiso del bot Diálogos. Sus rutas son GET|POST /api/bots/{botID}/subscribers/{subscriberID}/crm/status|sync|export-conversation, descritas arriba. Todavía no aparecen en la Referencia de API.

Herramientas MCP

Se publican seis herramientas generales de MCP, todas de solo lectura y con alcance crm:read:

  • list_crm_connections: conexiones del bot, con proveedor, estado y funciones.
  • get_crm_connection: resumen seguro de una conexión.
  • get_crm_mapping: revisión actual de la correspondencia.
  • list_crm_operations: últimas operaciones, opcionalmente filtradas por conexión y con las más recientes primero.
  • get_crm_operation: una operación con sus tareas, sin la carga sin procesar de sus solicitudes.
  • list_crm_conflicts: tareas pendientes de resolución manual.

Ninguna herramienta devuelve credenciales. Además hay herramientas para solicitudes del chat y revisión de contactos: lectura con crm:read (list_widget_crm_failures, get_crm_contact_candidate, get_crm_contact_search_config y otras) y cambios con crm:write (retry_widget_crm_failure, confirmación de candidato o de creación con confirm: true, set_crm_contact_search_config, create_custom_http_crm_connection, rotate_custom_http_crm_bearer_token y otras). La sincronización general, el reintento de cualquier tarea y la resolución de conflictos de correspondencia siguen solo en REST.

Limitaciones conocidas

  • OAuth de Bitrix24 no está disponible: connections/bitrix24/start devuelve 503 porque la plataforma no tiene una aplicación OAuth para ese proveedor. Conéctalo mediante un webhook entrante del portal.
  • Los webhooks de Bitrix24 necesitan BITRIX24_APPLICATION_TOKEN en el despliegue. Sin él se rechazan las entregas, aunque las consultas periódicas funcionan.
  • Las etiquetas de MyBot no se exportan como etiquetas del CRM; la correspondencia de etiquetas entrantes sí funciona.
  • La lista de negocios en la vista previa y la sincronización inicial está vacía: MyBot no tiene un objeto de negocio propio.
  • OzmaCRM no tiene webhooks propios: para recibir cambios al instante debes instalar tú el disparador, cuyo código MyBot no proporciona por API.
  • La dirección receptora se muestra una sola vez. Si se pierde, hay que emitir otra; no se puede recuperar la anterior.
  • La conciliación manual no tiene botón en la interfaz; solo se ofrece por API.
  • Las acciones CRM de un suscriptor aún no figuran en la Referencia de API, aunque sí están disponibles en la interfaz.

Páginas relacionadas

Búsqueda de contactos HTTP propia

En la configuración del CRM, abre Búsqueda de contactos propia. Introduce el origen HTTPS del servidor, la ruta de búsqueda y un secreto bearer dedicado a ese endpoint. El secreto no se vuelve a mostrar y debe introducirse en cada cambio. Solo el propietario del bot puede modificar este ajuste. La búsqueda recibe los datos del contacto y devuelve candidatos; no crea ni fusiona contactos. Un operador revisa cada coincidencia. Si se encuentran varios candidatos, elige uno manualmente; un contacto ya vinculado a otro usuario no se puede seleccionar. Tras guardar, las nuevas solicitudes del chat usan esta búsqueda. Revisa cada coincidencia antes de vincular el contacto.

El manejador de búsqueda recibe un POST con el mismo tipo de autorización y el cuerpo {"email":"test@example.test","phone":"+15551234567","name":"Test customer"}; los campos vacíos se omiten, el correo va en minúsculas y el teléfono en formato E.164 con +. El manejador normaliza los datos propios del CRM. Responde con HTTP 200, Content-Type: application/json y exactamente dos claves: {"candidates":[{"id":"123","name":"Test customer","url":"https://crm.example/contacts/123"}],"complete":true}. Un candidato puede contener solo id, name y una url HTTPS opcional; devuelve como máximo 20 candidatos con ID únicos, en 64 KB y 10 segundos. Si el manejador no puede devolver todos los contactos coincidentes, responde "complete":false: no se muestra ninguna lista y no se ofrece crear el contacto. Las claves adicionales, null, las redirecciones y otros códigos de estado son errores de búsqueda, no «sin coincidencias». Para amoCRM, Bitrix24, OzmaCRM y RetailCRM, el ID de un candidato debe ser un entero positivo.

CRM propio mediante HTTP

Un desarrollador de CRM puede implementar dos manejadores HTTPS para un CRM sin conector integrado. En Otro CRM mediante HTTP, introduce un dominio HTTPS público sin puerto, las rutas relativas a la raíz para contactos y solicitudes, y un token bearer de 16 a 4096 caracteres ASCII visibles sin espacios. El token no se muestra después de guardar. Guardar la conexión no demuestra que los manejadores sean accesibles. Al cambiar el destino, crea una conexión nueva para que las tareas pendientes no se redirijan.

Ambos manejadores reciben solicitudes POST con Content-Type: application/json y Authorization: Bearer <token>. Los campos vacíos de nombre, correo o teléfono pueden omitirse de contact. Estos ejemplos usan datos sintéticos.

La ruta de contactos recibe:

{"operation_id":"customer-operation-key","subscriber_key":"subscriber-id","contact":{"name":"Test customer","email":"test@example.test","phone":"+15551234567"},"selected_contact_id":"optional-id"}

Devuelve HTTP 200 o 201 con {"contact_id":"crm-contact-id"}. Si selected_contact_id está presente, actualiza exactamente ese contacto y devuelve el mismo ID. En caso contrario, busca o crea el contacto sin duplicados.

La ruta de solicitudes recibe:

{"operation_id":"lead-operation-key","lead_key":"lead-id","contact_id":"crm-contact-id","source":"чат на сайте","contact":{"name":"Test customer","email":"test@example.test","phone":"+15551234567"}}

Asocia la solicitud a ese contacto y devuelve HTTP 200 o 201 con {"lead_id":"crm-lead-id"}. Los ID se envían y se devuelven como cadenas JSON, por ejemplo "123", no 123. Para elegir un contacto mediante la búsqueda, usa de 1 a 256 caracteres entre letras, dígitos, -, _, ., : y ~; un ID formado solo por puntos no es válido.

La integración del CRM es responsable de evitar duplicados. Guarda operation_id y el cuerpo de la solicitud de forma atómica con cada cambio. Un reintento con la misma clave y el mismo cuerpo debe devolver el ID original; la misma clave con un cuerpo distinto debe devolver HTTP 409. GetMyBot puede reintentar tras un error de red aunque el CRM ya haya aplicado el cambio. El manejador también debe buscar o crear los contactos de forma atómica: una búsqueda vacía no puede descartar una creación simultánea en otro lugar.

Configura la búsqueda de candidatos por separado en los ajustes de correspondencia del CRM. Un operador revisa y selecciona un contacto existente. Tras un resultado vacío y completo, el operador puede confirmar la creación; GetMyBot vuelve a comprobar la búsqueda, la configuración y el consentimiento antes de poner la tarea en cola. Ponerla en cola no demuestra la entrega.

Una solicitud corresponde a una consulta, no a una persona. El lead_key de la primera consulta es la clave anterior del visitante. Una consulta iniciada por el primer mensaje del cliente después de cerrar el diálogo recibe un lead_key nuevo: crea para ella una solicitud nueva con el mismo contact_id. Los mensajes de la misma consulta, los reintentos y los cambios de contacto llegan con el mismo lead_key, así que para un lead_key conocido actualiza la solicitud existente en lugar de crear una segunda. Una solicitud automática para una consulta nueva necesita el disparador de solicitud del chat del sitio y el consentimiento que el visitante dio en el widget; un contacto conocido solo por correo o mensajería no lo tiene.

Cada solicitud se limita a 10 segundos y a una respuesta de 64 KB. Un error de red, un tiempo de espera agotado, HTTP 429 o 5xx, y una respuesta 200 o 201 que no sea un objeto JSON, no tenga el campo de ID o tenga un lead_id no válido se reintentan con el mismo operation_id y cuerpo, como máximo 8 intentos en 24 horas; se respeta Retry-After. Los demás códigos de estado, incluidos 202, 204, 400, 404, 409 y 422, detienen la tarea sin reintento, así que devuelve 409 solo para un conflicto real de clave. Un 401 o 403 detiene la tarea sin desactivar la conexión. Un contact_id no válido, ya vinculado a otro visitante, o un ID distinto del vínculo existente requiere una revisión manual: puede que el CRM ya se haya modificado.

GetMyBot garantiza el mismo operation_id y cuerpo en cada reintento de una operación, envía el contacto de una solicitud del chat solo con un selected_contact_id ya vinculado o tras una confirmación explícita de creación, y pasa el contact_id devuelto a la solicitud. GetMyBot no garantiza una entrega única, la ausencia de duplicados en el CRM ni que una coincidencia de correo o teléfono sea la misma persona.

Antes de confiar en la integración, prueba con un contacto y una solicitud sintéticos acordados: creación, reintento, conflicto de clave, búsqueda, selección de un contacto existente, errores y recuperación. Protege el token y los datos personales que reciben los manejadores.