Requiere: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

La parte más difícil de dirigir un programa de recaudación de fondos de persona a persona no suelen ser las donaciones, sino encontrar nuevos embajadores que recauden fondos para ti. Invitaciones le da la vuelta a esto: en lugar de que tú reclutes a un embajador a la vez, tus seguidores existentes hacen el reclutamiento por ti.

Cada uno recibe un "enlace de invitación" personal que pueden compartir con sus amigos, familiares y red. Cada recaudador que se registra a través de ese enlace se acredita automáticamente a la persona que lo invitó.

Es una característica pequeña con un gran efecto: las personas con más probabilidades de traerte nuevos embajadores son las que ya están involucradas en tu causa.

Cuándo usarlo

• Hacer crecer un programa más allá de tu red. Has reclutado a tus 10-15 embajadores iniciales. Ahora esos 10-15 embajadores pueden atraer a 2-3 de sus contactos cada uno.
• Recompensar a tus campeones. Algunos seguidores son naturalmente evangelizadores. Invitaciones te proporciona una tabla de clasificación de quién atrae a más recaudadores, perfecta para el reconocimiento público.
• Lanzar una campaña de "trae un amigo". "Reenvía este enlace a una persona a la que le importe la causa" es una petición que cabe en un solo correo electrónico, un solo mensaje de texto, una sola publicación en redes sociales.

Cómo funcionan las invitaciones y cómo puedes beneficiarte

La recaudación de fondos de persona a persona funciona porque la gente es mucho más propensa a donar cuando se lo pide alguien que conoce, no cuando una organización benéfica les envía un correo electrónico frío. Invitaciones duplica ese principio.

En lugar de que intentes llegar a 100 nuevos recaudadores potenciales al año a través de marketing, das a los 20 recaudadores que ya tienes una forma de atraer a 2-3 de sus propios contactos. Dentro de una sola temporada de recaudación de fondos, tu lista se ha multiplicado sin que gastes un dólar adicional en adquisición.

Las matemáticas son sorprendentes. La mayoría de las organizaciones sin fines de lucro gastan entre 1 y 3 dólares para adquirir un nuevo donante a través de canales tradicionales (listas de correo electrónico, redes sociales de pago, correo directo). Adquirir un nuevo recaudador, alguien que luego recaudará fondos de su red, cuesta aún más.

Invitaciones reduce ese costo efectivamente a cero: el costo marginal de un recluta más es simplemente que el recluta haga clic en un enlace. El ahorro de costos se acumula cuando recuerdas que los recaudadores tienden a atraer donaciones de personas que nunca habrían donado a tu causa directamente, por lo que cada nuevo recluta desbloquea un grupo completamente nuevo de seguidores.

También hay una dimensión social. Cuando alguien se registra porque un amigo se lo pidió, llega con más inversión emocional que alguien que vio un anuncio. Ya confían en tu causa a través de su conexión personal.

Es estadísticamente más probable que inicien una recaudación de fondos activa (en lugar de registrarse y quedarse inactivos), y es más probable que permanezcan para una segunda campaña el próximo año. Muchas organizaciones sin fines de lucro informan un aumento de la retención de 2 a 3 veces en los recaudadores reclutados en comparación con los registros espontáneos.

Algunos consejos prácticos para sacar el máximo provecho de las Invitaciones:

• Haz una petición personal a tus 5 principales colaboradores. No envíes un correo electrónico genérico de "¡ahora puedes reclutar!" a toda tu lista de embajadores. En lugar de eso, llama o envía un correo electrónico directamente a tus 5 colaboradores más comprometidos: "Estamos probando una nueva forma de hacer crecer el programa, ¿compartirías este enlace con dos amigos?". Los campeones responden a que se les pida personalmente, no a correos masivos.
• Reconoce públicamente. Cada mes, envía una nota breve (correo electrónico, publicación en redes sociales o incluso una breve mención en tu próximo evento) agradeciendo a tus 3 principales reclutadores por su nombre. El reconocimiento público impulsa el comportamiento del mes siguiente de manera más confiable que cualquier función.
• Haz la petición específica. "Comparte esto con un corredor que se uniría a ti para el maratón" convierte mejor que "comparte esto con cualquier persona que pueda estar interesada". La especificidad da al invitado claridad sobre en quién pensar y hace que el destinatario se sienta como la persona adecuada a la que se le debe pedir.
• Vigila tu cola de moderación. Si los reclutas se registran pero sus recaudadores se quedan atascados en "Pendiente" durante días, el cuello de botella no es la adquisición, es tu flujo de trabajo de aprobación. Establece un Acuerdo de Nivel de Servicio (SLA) de 24 horas para aprobar (o rechazar con comentarios) a los nuevos reclutas, y mantendrás el impulso.
• Cuenta historias, no estadísticas. Cuando un recaudador reclutado alcanza un hito (sus primeros $100, su objetivo, su décimo donante), comparte su historia en tus canales. Las historias de "Sarah trajo a Marcus, que recaudó $2,500 para los niños" son mucho más compartibles que "tenemos 50 nuevos reclutas este mes".

Dónde encontrar Invitaciones en Embajadores

En tu administrador de WordPress, ve a la pestaña Benéfico » Embajadores » Invitaciones.

Verás un único interruptor la primera vez que la visites. Hasta que lo actives, todo lo demás permanecerá oculto.

Cómo habilitar las Invitaciones

Invitaciones es opcional. Haz clic en el interruptor Habilitar Invitaciones, y el sistema te pedirá que confirmes, ya que activarlo por primera vez crea una pequeña tabla de base de datos personalizada para almacenar los tokens de invitación. (No te preocupes: desactivarlo más tarde no pierde ningún dato, y hay un botón separado de "eliminar permanentemente" si alguna vez quieres borrar la tabla por completo).

Una vez activado, aparecen cinco configuraciones más:

Configuración	Significado en lenguaje claro
Quién puede reclutar	O "Cualquier Embajador" (cualquiera que tenga al menos una recaudación de fondos publicada) o "Solo Propietarios de Campañas Principales" (solo las personas que ejecutan las causas subyacentes). Empieza solo con los propietarios principales y amplía más tarde.
Página de Destino	La página de tu sitio donde aterrizan los enlaces de reclutamiento. Crearás una página, pegarás el shortcode [charitable_invite_landing] en ella, y luego seleccionarás esa página aquí.
Copia introductoria de la página de destino	Texto enriquecido opcional que se muestra encima de la tarjeta de causa en la página de destino. Úsalo para establecer el contexto: «Ayúdanos a atraer más corredores al maratón», etc.
Imagen de reserva de la página de destino	Si la campaña de causa para la que alguien está reclutando no tiene una imagen destacada, esta es la imagen que utiliza la página de destino en su lugar.
Invitador por correo electrónico al aprobar	Cuando está ACTIVADO, el reclutador recibe un correo electrónico de felicitación en el momento en que se aprueba el evento de recaudación de fondos de su recluta. Muy recomendable: refuerza el comportamiento que deseas ver con más frecuencia.

Configuración de tu página de destino

1. Crea una nueva página en WordPress (Páginas > Añadir nueva). Asígnale un título como «Conviértete en un recaudador de fondos» o «Únete a nuestro equipo».
2. Paste this shortcode into the page content:

   [charitable_invite_landing]
   

3. Publica la página.
4. De vuelta en la pestaña de Invitaciones, selecciona esa página en la configuración de Página de destino y guarda.

Eso es todo: la página ahora se mostrará con tu encabezado, la tarjeta de causa de quien provino el recluta y un botón de Conviértete en un recaudador de fondos que te llevará a tu formulario de envío de campaña existente.

Si deseas ver cómo se verá antes de compartir algún enlace de invitación, visita la página directamente sin iniciar sesión. Verás una versión «genérica» con contenido de marcador de posición (sin causa específica). Cuando alguien hace clic en una URL de invitación real, la página de destino inserta la causa real a la que fue referido.

Cómo lo usarán tus embajadores

Una vez que las Invitaciones estén habilitadas, cualquier persona elegible para reclutar (según tu configuración de Quién puede reclutar) verá una nueva tarjeta en la parte superior de su página de Mis campañas:

La tarjeta tiene:

• Su URL de invitación personal: un enlace único que vincula cualquier registro a ellos. Pueden copiarlo con un solo clic.
• Botones para compartir: correo electrónico, SMS, WhatsApp, X/Twitter y Facebook. Cada uno abre la aplicación correspondiente pre-rellenada con un mensaje amigable.
• Una línea de estadísticas: cuántas personas han reclutado hasta ahora, desglosadas por estado.
• Un interruptor «Tus reclutas»: pueden cambiar su página de Mis campañas para ver a todas las personas que han traído.

Si poseen varias campañas principales, también obtienen un botón de Reclutar por campaña (en la fila de acciones de cada tarjeta de campaña) que abre una ventana emergente con una URL de invitación específica de la campaña. De esa manera, pueden decir «reclutar para *esta* causa» en lugar de dejar que el recluta elija una.

Qué sucede cuando alguien hace clic en el enlace

El recorrido, desde la perspectiva del recluta:

1. Haz clic en la URL de invitación que les envió su amigo.
2. Aterriza en tu página de destino de invitación, que muestra la causa que se les invita a apoyar.
3. Haz clic en «Conviértete en un recaudador de fondos» para acceder al formulario de envío de la campaña.
4. Regístrate y envía tu evento de recaudación de fondos.
5. Tu equipo de moderación lo aprueba (si estás utilizando Aprobación manual), o se publica inmediatamente bajo aprobación automática.

En segundo plano, el sistema ha estado rastreando silenciosamente que este recluta provino de un invitador específico, utilizando una cookie de 30 días. Para conocer la mecánica completa, consulte Cómo funciona la atribución.

Viendo quién reclutó a quién

El widget de Reclutamiento en el panel de control general le ofrece la vista a nivel de programa: reclutas totales este mes, desglose de estado, gráfico de series temporales y una tabla de clasificación de los mejores reclutadores.

Los embajadores individuales ven sus propios reclutas haciendo clic en el interruptor "Tus reclutas" en su página Mis campañas:

Las etiquetas de filtro en la parte superior dividen la lista en Todos / Aprobados / Pendientes / Rechazados. Cada etiqueta muestra un recuento, para que puedan ver de un vistazo cuántos de sus reclutas aún esperan su aprobación.

Cuando algo va mal: los avisos de autocomprobación

La pestaña Invitaciones muestra banners de colores en la parte superior cuando algo necesita su atención:

Verá	Qué va mal	Qué hacer
Rojo: "Habilitado pero falta la tabla de la base de datos"	Una actualización del plugin o una limpieza manual de la base de datos eliminó la tabla.	Haga clic en Recrear tabla; el esquema se reconstruye en su lugar.
Amarillo: "Esquema obsoleto"	Una actualización introdujo un esquema de tabla más nuevo; su instalación aún no se ha migrado.	Haga clic en Ejecutar actualización. Es seguro e idempotente.
Azul: "Deshabilitado pero existen datos"	Desactivó la función, pero el historial de reclutas todavía está en la tabla.	O bien Vuelva a habilitar para restaurar el acceso, o haga clic en Eliminar permanentemente y quitar tabla para purgar. (La opción destructiva le pide que escriba el nombre de la tabla para confirmar).
Azul: "Compatibilidad de caché desactivada"	Algunos plugins de caché pueden almacenar en caché su página de destino de invitación, lo que impediría el flujo de clic a atribución.	Active Compatibilidad de caché en Charitable > Configuración > Avanzado > Varios.
Amarillo: "No hay página de destino configurada"	Habilitó las invitaciones pero no eligió una configuración de Página de destino.	Elija una; consulte "Configuración de su página de destino" arriba.

Cada banner también tiene un enlace "Más información sobre el almacenamiento de invitaciones" a la página de documentación de almacenamiento si desea más detalles.

Consejos para poner en marcha el reclutamiento

• Envíe un correo electrónico personalmente a sus 5 mejores embajadores. "Estamos probando una nueva forma de hacer crecer el programa, ¿estaría dispuesto a compartir este enlace con una o dos personas a las que les importaría?" es mejor que cualquier anuncio genérico.
• Reconozca públicamente a los reclutadores. Un correo electrónico o una publicación en redes sociales mensual de "mención especial a nuestros 3 mejores reclutadores" impulsa el comportamiento del mes siguiente.
• Haga la petición específica. "Comparte este enlace con un corredor que se uniría a ti" convierte mejor que "comparte este enlace con personas que podrían estar interesadas".
• Vigila la columna Pendiente. Si los reclutas siguen apareciendo pero sus recaudadores de fondos permanecen en Pendiente, el cuello de botella es la moderación; asegúrate de que alguien se encargue de revisar la cola.

---

Referencia del desarrollador

El resto de esta página es para desarrolladores que personalizan el sistema de Invitaciones.

Almacenamiento de ajustes

Todos los ajustes de Invitaciones se almacenan en el sub-array ambassadors de wp_options.charitable_settings, por ejemplo:

charitable_settings > ambassadors > invites_enabled
charitable_settings > ambassadors > invites_who_can_recruit
charitable_settings > ambassadors > invites_landing_page_id
…

Leer a través del ayudante:

charitable_ambassadors_get_invites_setting( $key, $default );
charitable_ambassadors_invites_enabled(); // bool

Tabla personalizada

Cuando la función se habilita por primera vez, Charitable_Ambassadors_Invites_Schema::create() crea una pequeña tabla personalizada llamada {$wpdb->prefix}charitable_ambassadors_invite_tokens a través de dbDelta(). El esquema es gestionado completamente por el plugin; la clase expone create(), exists(), is_current(), upgrade() y drop(). La versión actual del esquema se almacena en wp_option('charitable_ambassadors_invites_schema_version'). Consulta Cómo se almacenan los datos de invitación para ver el ciclo de vida completo de la tabla (creación, deshabilitación suave, actualizaciones de esquema, desinstalación destructiva).

Filtros

Filtro	Predeterminado	Propósito
Definiciones de campos de configuración de invitaciones de embajadores benéficos	array de 6 campos	Añade, elimina o modifica los ajustes de administrador de Invitaciones.
charitable_ambassadors_user_can_invite	booleano (calculado)	Anula la elegibilidad de quién ve la tarjeta de recluta. Firma ( $can, $user_id, $campaign_id_or_null ).
charitable_ambassadors_invite_attribution_mode	'last_click'	Devuelve 'first_click' para acreditar al invitador que hizo clic antes en lugar del más reciente.
charitable_ambassadors_invite_cookie_lifetime	30 * DAY_IN_SECONDS	Anula la TTL de la cookie.
charitable_ambassadors_invitations_storage_docs_url	URL de wpcharitable.com	Anula la URL de la documentación a la que enlazan los avisos de autocomprobación.
charitable_ambassadors_recruit_card_learn_more_url	''	Añade un enlace "Más información" a la tarjeta de recluta. Una cadena vacía lo suprime.
charitable_ambassadors_recruit_card_learn_more_label	__('Más información')	Etiqueta para el enlace "Más información".
charitable_ambassadors_recruit_card_empty_text	“Aún no hay reclutas…”	Texto del estado vacío cuando un invitador tiene cero reclutas.
charitable_ambassadors_recruits_view_empty_text	“Aún no has reclutado a nadie…”	Texto del estado vacío en la pestaña Tus reclutas. Recibe $status + $user_id.
charitable_ambassadors_invitations_csv_max_rows	10000	Límite en las exportaciones CSV.

Acciones

Acción	Argumentos	Se dispara cuando
charitable_ambassadors_my_campaigns_before_grid	$campaigns, $user_id	Justo antes de que se renderice la cuadrícula de campañas. La tarjeta de recluta se monta aquí.
charitable_ambassadors_my_campaigns_card_actions	$campaign_id, $context	En la fila de acciones de cada tarjeta de campaña. El popover de recluta por campaña se monta aquí para las campañas principales.
charitable_ambassadors_recruit_card_footer	$user_id, $token, $invite_url	Dentro de la tarjeta de recluta, justo encima del enlace "Más información". Muestra tu propio HTML; las devoluciones de llamada son responsables del escape.
charitable_ambassadors_invite_clicked	$token_row, $request	Después de que el manejador de URL resuelva un token válido.
charitable_ambassadors_invite_claimed	$token_row, $fundraiser_id, $inviter_user_id	Después de que se estampen los metadatos de atribución.
charitable_ambassadors_invite_self_recruit_skipped	$token_row, $fundraiser_id	La protección de autorreclutamiento bloqueó una atribución.

Funciones auxiliares

charitable_ambassadors_invites_enabled()                       // bool
charitable_ambassadors_get_invites_setting( $key, $default )   // mixed
charitable_ambassadors_user_can_invite( $user_id, $campaign_id = null )  // bool, filterable
charitable_ambassadors_invites_log( $code, $context )          // logs to Charitable Tools > Log

El ayudante de elegibilidad es la función que la tarjeta de recluta utiliza para decidir si se renderiza. Úsalo en tu propio código (por ejemplo, un aviso de administrador o una extensión personalizada de Mis Campañas) para mantener la coherencia de la elegibilidad.

Clases

Clase	Archivo	Rol
Embajadores Benéficos Invitaciones	includes/invites/class-charitable-ambassadors-invites.php	Bootstrap. Registra el shortcode [charitable_invite_landing], el manejador de URL, el oyente de atribución, el disparador de correo electrónico y los hooks de renderizado de Mis Campañas.
Embajadores Benéficos Invitaciones Esquema	class-charitable-ambassadors-invites-schema.php	Crear/eliminar/actualizar para la tabla de tokens de invitación.
Embajadores Benéficos Invitaciones Tokens	class-charitable-ambassadors-invites-tokens.php	CRUD de tokens: get_or_create, lookup, increment_view, increment_claim, revoke, build_invite_url.
Datos_de_invitaciones_de_embajadores_benéficos	class-charitable-ambassadors-invitations-data.php	Consultas del lado del administrador: principales reclutadores, actividad reciente, desglose, reclutas para el usuario.
Embajadores Benéficos Invitaciones	class-charitable-ambassadors-invitations.php	Renderizador de pestañas de administración, 5 puntos finales AJAX, manejador de desinstalación destructiva de POST de formulario, notificaciones de autocomprobación.
Charitable_Ambassadors_Invitations_CSV	class-charitable-ambassadors-invitations-csv.php	Manejador de exportación CSV con neutralización de inyección de fórmulas.
Embajadores Benéficos Correo Invitador Recluta Aprobado	class-charitable-ambassadors-email-inviter-recruit-approved.php	El correo electrónico transaccional. Resuelve 5 etiquetas de shortcode a través de los filtros charitable_email_content_field_value_*.

Manejador de URL

El manejador de URL se ejecuta en la prioridad 1 de init. Busca ?charitable-invite=<token> y, si se encuentra un token válido:

1. Establece la cookie charitable_invite_token (30 días, SameSite=Lax, secure cuando SSL).
2. Incrementa el view_count del token.
3. Emite encabezados de no caché a través de charitable_nocache_headers() (Pro 1.8.15.2+) o nocache_headers() (fallback del núcleo de WP).
4. Redirige a la página de destino configurada con ?charitable-invite eliminado.

La redirección utiliza 302 (no 301) para que las capas de caché no memoricen la redirección en sí.

Atribución

La atribución se activa mediante la acción charitable_campaign_submission_save de Pro con la firma ( $data, $campaign_id, $user_id, $form ). El manejador del hook en Charitable_Ambassadors_Invites::on_campaign_submission_save():

1. Lee la cookie charitable_invite_token.
2. Busca el token; falla silenciosamente si no se encuentra.
3. Comprueba inviter_user_id !== submitter_user_id (protección contra auto-reclutamiento).
4. Escribe dos claves de meta de publicación en la nueva recaudación de fondos:
   • _charitable_ambassadors_invited_by_user_id
   • _charitable_ambassadors_invited_via_token_id
5. Incrementa el claim_count del token + last_claimed_at.

El manejador es adaptativo a la firma: acepta tanto la forma canónica de 4 argumentos como una forma heredada de 2 argumentos ( $fundraiser_id, $user_id ) utilizada por el sistema de verificación.

Registro

Cada evento de invitación se registra en Herramientas de Charitable > Registro a través de charitable_log():

type=addon
source=ambassadors_invites
level=info  (or warning for the skip cases)

Códigos de registro: invite_clicked, invite_claimed, self_recruit_skipped, inviter_deleted_at_approval, attribution_skipped_revoked_token, unconfigured_landing_page_admin_view, recreate_table_invoked, permanent_delete_invoked.

Endpoints AJAX

Todos solo en wp_ajax_, nonce charitable_ambassadors_invitations, capacidad manage_charitable_settings:

Acción	Propósito
ambassadors_invitaciones_recrear_tabla_caritativa	Ejecuta Schema::create() después de que una autocomprobación mostrara que faltaba la tabla.
ambassadors_invitaciones_ejecutar_actualizacion_esquema_caritativa	Ejecuta Schema::upgrade() desde el estado "desactualizado" de la autocomprobación.
ambassadors_invitaciones_desactivar_funcionalidad_caritativa	Desactiva invites_enabled.
ambassadors_invitaciones_reactivar_caritativa	Activa invites_enabled de nuevo sin volver a ejecutar el modal de creación de tabla.
ambassadors_invitaciones_buscar_paginas_destino_caritativa	Autocompletado de página para la configuración de Página de destino.

La desinstalación destructiva ("eliminar y quitar tabla permanentemente") es un manejador POST de formulario en admin-post.php?action=charitable_ambassadors_invitations_purge, protegido por un nonce + una confirmación del nombre de tabla escrita manualmente.

Compatibilidad de caché

La página de destino de invitaciones es dinámica (por usuario, por token). El filtro charitable_is_dynamic_page de Pro 1.8.15.2 está conectado para marcar la página de destino y que los plugins de caché la omitan. Si esa función Pro no está disponible (versión Pro anterior), el manejador de URL aún emite nocache_headers() directamente.

Ejemplos de personalización

Ajustes comunes. Añada cualquiera de estos a functions.php de su tema o a un plugin específico del sitio.

Cambiar a atribución de primer clic (dar crédito al primer invitado, no al más reciente):

add_filter( 'charitable_ambassadors_invite_attribution_mode', function () {
    return 'first_click';
} );

Extender la cookie de seguimiento de reclutas de 30 días a 90 días:

add_filter( 'charitable_ambassadors_invite_cookie_lifetime', function () {
    return 90 * DAY_IN_SECONDS;
} );

Añadir un enlace "Más información" a la tarjeta de recluta en Mis Campañas:

add_filter( 'charitable_ambassadors_recruit_card_learn_more_url', function () {
    return home_url( '/ambassador-handbook/recruiting/' );
} );

add_filter( 'charitable_ambassadors_recruit_card_learn_more_label', function () {
    return 'Tips for inviting friends';
} );

Inyectar tu propio contenido (p. ej., un vídeo) en la tarjeta de recluta:

add_action( 'charitable_ambassadors_recruit_card_footer', function ( $user_id, $token, $invite_url ) {
    echo '<p style="margin-top: 16px;"><a href="https://example.com/recruiting-video">Watch our 2-minute walkthrough</a></p>';
}, 10, 3 );

Restringir la captación a un rol personalizado (p. ej., solo usuarios con verified_ambassador):

add_filter( 'charitable_ambassadors_user_can_invite', function ( $can, $user_id, $campaign_id ) {
    if ( ! $can ) {
        return false;
    }
    $user = get_userdata( $user_id );
    return $user && in_array( 'verified_ambassador', (array) $user->roles, true );
}, 10, 3 );

Personalizar el texto del estado vacío en la pestaña Tus Reclutas:

add_filter( 'charitable_ambassadors_recruits_view_empty_text', function ( $message, $status, $user_id ) {
    if ( 'rejected' === $status ) {
        return 'No rejected recruits - your standards are solid!';
    }
    return $message;
}, 10, 3 );

Relacionado

• Cómo funciona la atribución: el flujo de clic a crédito explicado.
• Cómo se almacenan los datos de invitación: la tabla personalizada, el ciclo de vida, la desinstalación destructiva.
• Página de destino de invitación: personalización de shortcode y anulaciones de plantilla.
• Personalización de la tarjeta de recluta: filtros y acciones para la tarjeta de Mis Campañas.
• Hooks y filtros en Embajadores – la referencia completa de filtros y acciones.