Notification and email hooks

These hooks change the emails HappenBoard sends: to attendees who sign up for an event, to customers who book an appointment, and to the host and the site admin about each booking. Use them to rewrite or cancel a message, choose its language, change when reminders go out or decide who hears about a booking.

For the settings side, see automatic emails and emails in the attendee’s language. New to hooks? Start with Extending HappenBoard with hooks.

Which emails HappenBoard sends

Each email has a template id. The id ends the name of the filter that can rewrite the message, and it is passed to happenboard_email_locale.

Sign-up emails go through happenboard_notifications_{$template_id}:

Booking emails go through happenboard_notifications_booking_{$template_id}:

These settings are under HappenBoard → Settings → Email. See approving booking requests for the request flow.

How reminders go out

Sign-up reminders come from one WP-Cron event, happenboard_rsvp_reminder_sweep, which runs every 15 minutes. Each run finds the dates that now start within the lead time (Send reminder hours before start, 24 by default). It then fires happenboard_cron_reminder once for each attendee still going.

HappenBoard’s reminder email listens there, and so do HappenBoard Pro’s WhatsApp and MailerPress reminders. Before version 0.2.0, each sign-up scheduled its own cron event; the first sweep after the update takes those over.

Booking reminders work differently. Each confirmed booking schedules its own reminders, with Action Scheduler when it is installed and WP-Cron otherwise, at the hours set by happenboard_booking_reminder_offsets.

Which language an email uses

• Sign-up emails: the language of the event translation the attendee signed up on (WPML or Polylang), else the site language.
• Booking emails to the customer: the language of the page they booked on, else their profile language when they have an account, else the site language.
• Booking emails to the host and the site admin: each person’s profile language. happenboard_email_locale does not run for these.

happenboard_email_locale can change the first two. HappenBoard Pro uses it to read a language field from the registration form.

MailerPress triggers (Pro)

The happenboard_mp_* actions exist only in HappenBoard Pro, and only fire when MailerPress is active and the MailerPress integration is turned on. HappenBoard sends nothing on them: they are the triggers you build automations on in MailerPress. See MailerPress automations.

apply_filters( 'happenboard_email_locale', string $locale, string $template_id, WP_Post|null $event, array<string,mixed> $row )

add_filter(
    'happenboard_email_locale',
    function ( $locale, $template_id, $event, $row ) {
        // Attendee rows have "email", booking rows "customer_email".
        $email = (string) ( $row['email'] ?? $row['customer_email'] ?? '' );

        return str_ends_with( $email, '.fr' ) ? 'fr_FR' : $locale;
    },
    20,
    4
);

apply_filters( "happenboard_notifications_{$template_id}", array<string,mixed> $payload, WP_Post $event, array<string,mixed> $attendee )

add_filter(
    'happenboard_notifications_confirmation',
    function ( array $payload, $event = null, $attendee = array() ): array {
        $payload['subject'] = '[' . get_bloginfo( 'name' ) . '] ' . $payload['subject'];
        $payload['body']   .= '<p>' . esc_html__( 'See you there.', 'my-plugin' ) . '</p>';

        // Return array( 'send' => false ) + $payload to cancel the email.
        return $payload;
    },
    40,
    3
);

do_action( 'happenboard_cron_reminder', int $attendee_id )

add_action(
    'happenboard_cron_reminder',
    function ( int $attendee_id ): void {
        // A channel of your own, next to the email.
        my_send_sms_reminder( $attendee_id );
    },
    50
);

apply_filters( 'happenboard_booking_email_tokens', array<string,string> $tokens, int $booking_id, array<string,mixed> $row )

add_filter(
    'happenboard_booking_email_tokens',
    function ( $tokens, $booking_id, $row ) {
        // The meeting link saved on the booking type.
        $link = (string) get_post_meta( (int) $row['booking_type_id'], 'acme_meeting_link', true );
        if ( '' !== $link && '' !== $tokens['start_local'] ) {
            $tokens['start_local'] .= ' · ' . $link;
        }

        return $tokens;
    },
    10,
    3
);

apply_filters( "happenboard_notifications_booking_{$template_id}", array<string,mixed> $payload, int $booking_id, array<string,mixed> $row )

add_filter(
    'happenboard_notifications_booking_confirmation',
    function ( array $payload, int $booking_id, array $row ): array {
        // Copy the front desk on every booking confirmation.
        $payload['headers'][] = 'Bcc: [email protected]';

        return $payload;
    },
    10,
    3
);

apply_filters( 'happenboard_booking_operator_recipients', array<int,string> $recipients, string $event, int $booking_id, array<string,mixed> $row )

add_filter(
    'happenboard_booking_operator_recipients',
    function ( array $recipients, string $event, int $booking_id, array $row ): array {
        // The front desk hears about every request waiting for approval.
        if ( 'request' === $event ) {
            $recipients[] = '[email protected]';
        }

        return $recipients;
    },
    10,
    4
);

apply_filters( 'happenboard_booking_reminder_offsets', array<int,int> $offsets, int $booking_id, array<string,mixed> $row )

add_filter(
    'happenboard_booking_reminder_offsets',
    function ( array $offsets, int $booking_id, array $row ): array {
        // Two days before, the day before, and two hours before.
        return array( 48, 24, 2 );
    },
    10,
    3
);

do_action( 'happenboard_mp_rsvp_created', array<string,mixed> $ctx )

add_action(
    'happenboard_mp_rsvp_created',
    function ( array $ctx ): void {
        // Log each sign-up sent to MailerPress.
        error_log(
            sprintf(
                '%s registered for %s (%d seats).',
                (string) ( $ctx['email'] ?? '' ),
                (string) ( $ctx['event_title'] ?? '' ),
                (int) ( $ctx['quantity'] ?? 1 )
            )
        );
    }
);

do_action( 'happenboard_mp_rsvp_cancelled', array<string,mixed> $ctx )

add_action(
    'happenboard_mp_rsvp_cancelled',
    function ( array $ctx ): void {
        // Tag the contact in your own system.
        my_plugin_tag_contact(
            (string) ( $ctx['email'] ?? '' ),
            'cancelled-' . (int) ( $ctx['event_id'] ?? 0 )
        );
    }
);

do_action( 'happenboard_mp_checked_in', array<string,mixed> $ctx )

add_action(
    'happenboard_mp_checked_in',
    function ( array $ctx ): void {
        // Log each check-in sent to MailerPress.
        error_log(
            sprintf(
                '%s checked in at %s.',
                (string) ( $ctx['email'] ?? '' ),
                (string) ( $ctx['event_title'] ?? '' )
            )
        );
    }
);

do_action( 'happenboard_mp_reminder', array<string,mixed> $ctx )

add_action(
    'happenboard_mp_reminder',
    function ( array $ctx ): void {
        // Log each reminder sent to MailerPress.
        error_log(
            sprintf(
                'Reminder due for %s (event %d).',
                (string) ( $ctx['email'] ?? '' ),
                (int) ( $ctx['event_id'] ?? 0 )
            )
        );
    }
);

do_action( 'happenboard_mp_post_event_tick', int $attendee_id, int $event_id )

add_action(
    'happenboard_mp_post_event_tick',
    function ( int $attendee_id, int $event_id ): void {
        // Log each follow-up the scan finds.
        error_log(
            sprintf(
                'Follow-up due for attendee %d of event %d.',
                $attendee_id,
                $event_id
            )
        );
    },
    10,
    2
);

do_action( 'happenboard_mp_post_event', array<string,mixed> $ctx )

add_action(
    'happenboard_mp_post_event',
    function ( array $ctx ): void {
        // Queue a satisfaction survey.
        my_plugin_queue_survey(
            (string) ( $ctx['email'] ?? '' ),
            (int) ( $ctx['event_id'] ?? 0 )
        );
    }
);

apply_filters( 'happenboard_pro_mailerpress_contact', array<string,mixed> $payload, array<string,mixed> $ctx )

add_filter(
    'happenboard_pro_mailerpress_contact',
    function ( array $payload, array $ctx ): array {
        // Store the number of seats on the contact.
        $payload['custom_fields']['hp_seats'] = (string) ( $ctx['quantity'] ?? 1 );

        return $payload;
    },
    10,
    2
);

Next steps

• Appointment booking hooks: the booking actions that send these emails.
• Attendees and sign-up hooks: the sign-up and cancellation actions behind the attendee emails.
• Customizing email branding: colors, logo and footer of every email.