Base de conocimiento de GetMyBot

Campañas

Crear una serie de mensajes y acciones que dura varios días: condiciones, esperas, publicación y revisión del recorrido de un cliente.

En esta página

Una campaña ejecuta varios pasos con esperas y comprobaciones. Por ejemplo: tras una solicitud, envía el programa de un curso; un día después comprueba el pago y recuerda la inscripción a quienes aún no han pagado.

En el editor, los pasos se conectan en un diagrama llamado grafo. Cada paso, o nodo, envía un mensaje, espera, comprueba una condición o ejecuta una acción. El recorrido de un cliente por el grafo se llama viaje. Puede durar días o semanas. Si solo necesitas enviar un mensaje a un público elegido, usa una difusión o una campaña de email.

Versiones y borrador

Se edita un único borrador (draft). Al publicarlo, la plataforma guarda una copia inmutable, la versión publicada (published). Cuando se detiene, una versión puede pasar al archivo (retired). El número de versión permite saber qué reglas se aplicaron a un cliente concreto.

El borrador contiene el disparador de entrada, el público, los ajustes y el grafo de pasos. Para guardarlo por API se usa PUT /draft con expected_revision. Si otra persona guardó antes sus cambios, el servidor devuelve un conflicto. Vuelve a cargar los datos antes de seguir editando.

La publicación (POST /publish) fija el borrador actual como una nueva versión publicada y abre enseguida un borrador nuevo que es una copia. Un suscriptor que entró mientras estaba activa la versión N termina en la versión N, aunque después se publique la N+1. El nuevo disparador, público, configuración y grafo no cambian los viajes ya iniciados.

Solo puedes cambiar el grafo cuando la campaña está detenida. Si está En ejecución o En pausa, el guardado se rechaza: un suscriptor puede encontrarse en un nodo identificado por ese ID y el grafo no debe cambiar durante su viaje.

Puedes clonar cualquier versión, sea borrador, publicada o archivada: su contenido sustituirá el borrador actual. Una campaña detenida también puede archivarse para quitarla de la lista activa sin borrar su historial.

Disparadores de entrada

  • Manual: no requiere configuración. El botón Probar del editor usa la misma ruta y ejecuta el nodo inicial de inmediato, sin esperar al proceso en segundo plano.
  • Evento del sitio: el mismo evento del Customer SDK o del widget que usan las reacciones, con el mismo editor de condiciones. El botón de suscripción por email desde una ventana emergente selecciona $email_subscribed, que se emite tras la confirmación independiente de una suscripción nueva o reactivada mediante el formulario.
  • Programado: se ejecuta una vez en at o de forma recurrente. La recurrencia usa una hora local (HH:MM) y una zona horaria IANA explícita; el valor «Local» no se acepta. Puede filtrarse por días de la semana y requiere start_at y end_at separados por no más de dos años. Toda programación recurrente debe tener un final para que una campaña olvidada no siga buscando destinatarios indefinidamente. Una hora que no existe por el cambio de horario de primavera se omite por defecto; la política «siguiente instante válido» la traslada al final del intervalo inexistente.
  • Cambio de etiqueta: añadir o quitar una etiqueta concreta. Cada una de estas transiciones puede iniciar un viaje diferente con otro contenido.
  • Cambio de propiedad: una propiedad aprobada del perfil pasa de un estado a otro. Las condiciones de valor anterior y nuevo son independientes y ambas opcionales. Guardar de nuevo el mismo valor no es una transición y no inicia un viaje.
  • Entra al segmento: la persona pasa de no pertenecer a pertenecer a un segmento listo. Un recálculo que solo confirme la pertenencia existente no inicia otro viaje.

Nodos del grafo

Las líneas del diagrama conectan los pasos. Una etiqueta como yes o no sobre una línea indica qué resultado lleva por ese camino. Debe haber exactamente un nodo inicial y cada paso debe tener una ruta hasta Meta alcanzada o Salida. No se puede guardar un grafo con nodos inaccesibles o caminos sin final. En términos técnicos, los pasos son nodos y las líneas son aristas. Cada nodo admite hasta 32 KiB de configuración; la campaña completa, hasta 200 nodos y 400 aristas.

  • Mensaje: envía bloques de texto, foto, archivo o demora como una reacción normal al mismo suscriptor. Aquí no se admiten bloques de IA, reacciones anidadas, espera de respuesta ni escrituras de parámetros con efectos secundarios. Reintentar el nodo tras un fallo debe ser seguro.
  • Contenido: envía un documento publicado y fijado a una versión a un canal indicado expresamente: Telegram, VK, WhatsApp, chat web, email, push del navegador o push móvil. Para email se necesita un documento Email publicado, un asunto y el envío configurado. No cambia por sí solo a otro canal. Si no se puede contactar al destinatario, sigue la rama «canal no disponible», si la has conectado, o el nodo falla. Para push se necesita un documento publicado de tipo Push.
  • Retraso: espera un número de segundos, como máximo 180 días.
  • Esperar evento: espera un evento de cliente por nombre, de hasta 64 caracteres y sin el prefijo reservado $, con un tiempo límite de hasta 180 días. Tiene exactamente dos ramas: la principal, si llegó el evento, y timeout.
  • Filtro de audiencia: elige yes o no según parámetros del suscriptor, períodos de tiempo, tiempo desde la última visita o número de mensajes. Usa las mismas condiciones que las reacciones.
  • Prueba A/B: reparte el tráfico entre ramas con pesos. El hash del nodo y del ID del suscriptor hace que la misma persona permanezca en la misma rama tras una nueva comprobación o un reinicio.
  • Experimento: elige una rama según la variante de un experimento común, con ID y versión fijados. Admite entre 2 y 16 variantes y exige una rama por cada variante declarada. Si faltara una, el viaje de quienes recibieron esa variante terminaría sin aviso.
  • Canal disponible: elige yes o no según sea posible contactar al suscriptor ahora mismo en el canal indicado. Email y teléfono no son válidos aquí como canales de entrega. Este nodo permite decidir expresamente un canal alternativo, en lugar de suponer que el envío cambiará de canal por sí solo.
  • Acción: ejecuta una de estas operaciones:
    • Cambiar etiquetas, incluidas las temporales con ttl_days.
    • Cambiar derechos de un participante (change_rights) en un chat indicado: banear, desbanear, expulsar, aprobar o rechazar una solicitud, silenciar, reactivar el sonido o restringir. chat_id es obligatorio porque la campaña se ejecuta sin un chat actual. Escríbelo como un número corriente, sin espacios, signo más ni ceros iniciales. Por ejemplo, para expulsar a alguien de un chat privado N días después de asignarle una etiqueta, conecta Retraso → Acción → Cambiar permisos → Expulsar. Las operaciones disponibles dependen del canal; consulta permisos por canal.
    • Quitar parámetros. Establecerlos, sumarlos o incrementarlos no se admite aquí, para que los reintentos sean seguros, igual que en Mensaje.
    • Hacer una solicitud web síncrona, sin ejecución en segundo plano ni reacciones anidadas de éxito o error. La cabecera Idempotency-Key está reservada: la plataforma le asigna el mismo valor al reintentar el paso, de modo que tu servicio pueda descartar duplicados. No puedes elegir un valor propio.
    • Sincronizar con un CRM conectado; asignar un diálogo de soporte a un agente o grupo; emitir un evento de cliente como track() del widget, visible para segmentos, embudos y disparadores; o iniciar un lead bot.
  • Meta alcanzada y Salida: nodos finales sin ajustes. El primero indica que se cumplió el objetivo; el segundo, que el viaje terminó sin cumplirlo.

Dos emails después de la suscripción

  1. Prepara el envío: un plan con email, un dominio de envío verificado y un método de entrega configurado. Crea y publica dos documentos de tipo Email en el Estudio de contenido.
  2. Crea una campaña y selecciona el disparador de suscripción por email desde una ventana emergente. En el formulario de la ventana emergente, añade un campo email obligatorio y una casilla independiente de consentimiento, activa la suscripción y selecciona ambos campos. La dirección debe estar verificada y vinculada al perfil; si es necesario, el visitante puede verificarla con un código en la ventana emergente. Verificar que una persona controla la dirección no equivale a obtener su consentimiento para recibir publicidad.
  3. Conecta Contenido → Retraso → Contenido → Meta alcanzada. En cada nodo Contenido, elige el canal email y un documento publicado, y escribe el asunto; el preencabezado es opcional. Configura la rama de canal no disponible y conéctala con Salida.
  4. Ejecuta la comprobación previa, publica e inicia la campaña. Después de enviar el formulario, el visitante recibe un email independiente de suscripción: debe abrir el enlace y confirmar en la página que aparece. Solo entonces se emite $email_subscribed y puede comenzar el recorrido. Una suscripción ya activa no genera otro evento. Comprueba que el participante tenga una dirección disponible y esté suscrito. El consentimiento y las bajas se comprueban antes de cada envío: si se da de baja después del primer email, no recibirá el segundo. La comprobación previa no confirma la entrega real.

Si no se puede usar la configuración SMTP guardada

Si el servicio no puede usar la configuración SMTP guardada del proyecto al enviar un email automático, por ejemplo porque no puede descifrar la contraseña, la traza del viaje pide revisar esa configuración. El paso espera a que se corrija sin consumir un intento ni cobrar ese envío. No cambia automáticamente al servidor de la plataforma. Revisa y guarda la configuración en Email; después de corregirla, el paso volverá a comprobarse automáticamente.

Si antes de iniciar el envío no se puede conectar al servidor SMTP del proyecto, establecer TLS o autenticar, el paso también espera a que se restablezca el servicio sin consumir un intento ni cobrar el envío. Comprueba la conexión y las credenciales; el servicio volverá a comprobarlo automáticamente. Otros errores SMTP, como el rechazo de MAIL o RCPT y los errores posteriores al inicio del envío, pueden gestionarse de otra forma.

Permisos por canal

La posibilidad de banear o silenciar depende de la plataforma. Antes de poner el paso en cola, el sistema comprueba si el canal del suscriptor puede realizar esa operación en ese chat. Si no puede, el paso termina con un error y el viaje permanece en el mismo nodo hasta el siguiente intento. No queda una acción aplicada a medias.

  • Telegram: admite las ocho operaciones, banear, desbanear, expulsar, aprobar una solicitud, rechazarla, silenciar, reactivar el sonido y restringir, en el grupo, supergrupo o canal indicado en chat_id donde el bot es administrador.
  • VK: una comunidad solo puede moderarse a sí misma. Admite cuatro operaciones: banear, desbanear, expulsar y aprobar una solicitud. chat_id debe ser exactamente el ID de la comunidad conectada, el mismo número que aparece para VK en Canales. Otro valor se rechaza: VK habría aplicado la acción a la comunidad conectada aunque el grafo indicara otro chat. Silenciar, reactivar el sonido, restringir y rechazar solicitudes no están disponibles porque las comunidades VK no tienen una API para ello.
  • WhatsApp, Instagram Direct, Messenger, email y el widget web no admiten cambiar derechos de participantes. change_rights siempre falla en esos canales.

Verificación previa y publicación

POST /preflight comprueba la estructura del borrador actual con el mismo validador del grafo que se usa al guardar. También verifica que sigan existiendo los segmentos, documentos de contenido y experimentos referenciados. No envía nada. Devuelve ready, el número de versión, una suma de verificación y errores con código, como invalid_graph o invalid_reference, y un mensaje. No calcula el tamaño del público, la disponibilidad de los canales ni los consentimientos: esos aspectos quedan fuera de esta comprobación.

POST /publish vuelve a verificar las referencias en una sola transacción. Aunque el cliente haya omitido la verificación previa o alguna referencia haya cambiado, no podrá publicar una campaña que apunte a un segmento o documento eliminado. La publicación exige la revisión actual del borrador. Una revisión antigua o un borrador ya publicado provoca un conflicto sin un resultado parcial.

Informe por versión y traza del viaje

El informe (GET /report) se calcula por versión, no para toda la campaña. La versión N y la N+1 tienen contadores distintos; publicar otra versión no cambia las cifras de la anterior. Incluye un embudo de viajes (entraron, activos, en espera, en reintento, alcanzaron la meta, salieron, fallaron) y, por nodo, los recuentos de entradas, finalizaciones y fallos. Un informe queda sellado (sealed) cuando esa versión ya no admite nuevas entradas y ninguno de sus viajes puede avanzar. Sus cifras se conservan y no vuelven a calcularse; el informe de una versión publicada y activa se calcula de nuevo en cada lectura.

Para saber por qué un cliente no recibió el siguiente mensaje, abre la traza de su viaje (GET /journeys/{subscriberID}/{runNo}). Muestra los pasos recorridos, esperas, ramas elegidas, reintentos y errores. No copia el texto de los mensajes ni las respuestas de servicios externos.

La marca truncated significa que hubo más eventos de los permitidos y parte de la traza no se conservó. GET /failures muestra a los clientes cuyos intentos de ejecutar un paso se agotaron. Puedes reintentar uno de esos viajes con POST /journeys/{subscriberID}/{runNo}/retry.

Horas de silencio

Cada versión guarda una ventana de envío. Activa las horas de silencio para aplazar los nodos de mensaje, contenido y comprobación de disponibilidad del canal durante los intervalos semanales o fechas excluidas. Cuando termina la restricción, el ejecutor vuelve a comprobar el nodo. Una ventana cerrada no envía al cliente por sí sola a la rama de canal no disponible.

Elige la zona horaria del bot o la del destinatario. Actualmente la zona del destinatario se determina para push del navegador y push móvil; para mensajeros se usa la zona del bot. Si no se conoce la zona del destinatario, también se usa la del bot. Por ejemplo, un intervalo de 22:00 a 08:00 aplaza un recordatorio nocturno hasta la siguiente hora permitida. La posibilidad de que un mismo cliente vuelva a entrar en la campaña se configura aparte.

Permisos

Los tokens personales y los roles acceden a las campañas mediante tres permisos independientes: campaigns:read, campaigns:write y campaigns:publish. Publicar una versión y reintentar un viaje detenido se separan de la edición normal del borrador. Los tres requieren el permiso «Reacciones» sobre el bot. Sin él, la sección no es visible ni está disponible para lectura o escritura.

Qué sigue