Skip to main content

Read or write a show’s sponsor messages from code, as the Sponsors screen’s Messages tab does

Premium Intermediate Sponsor Manager

The routes behind Benecaster → Sponsors → Messages, under /benecaster-sponsor-manager/v1.

A sponsor message is reusable sponsor copy that a podcaster places in show notes with benecaster_sponsor_message. A message belongs to one show and never changes show.

Every route is admin only (manage_options plus the X-WP-Nonce header), and the routes exist only while Sponsor Manager is on for at least one show. A show where Sponsor Manager is off is refused with 403 benecaster_sponsor_manager_not_active. A message of another show is 404 benecaster_sponsor_manager_message_not_found, the same answer as one that does not exist.

  • A message is { id, show_id, title, body, start_date, end_date, sponsor_id, archived, status, shortcode, sponsor }.

    • title is the podcaster’s own name for it, never shown to listeners.
    • body is HTML that has been through wp_kses_post.
    • start_date and end_date are YYYY-MM-DD calendar dates in the site’s time zone, both inclusive, or '' when open.
    • sponsor_id is a sponsor’s id, 0 for none; sponsor is { id, company, archived }, or null. Sponsors are site-wide (see Read, create, change, archive or restore the site’s sponsors and a show’s sponsor campaigns from code).
    • status is where the dates stand today in the site’s time zone: upcoming, running, ended, or none (no dates).
    • shortcode is the tag to paste.
    • archived is more than a list filter: an archived message’s tag shows nothing, like one past its end date. Nothing deletes a message.
  • GET /shows/{show_id}/messages answers 200 { items }: the show’s active messages, title A–Z. With archived=1, its archived ones instead.

  • POST /shows/{show_id}/messages answers 201 with the new message. It takes title (required), body, start_date, end_date and sponsor_id; those left out default to an empty body, no dates and no sponsor.

  • GET /shows/{show_id}/messages/{id} answers with one message. PUT (or PATCH) on the same path changes only the fields sent.

  • POST …/messages/{id}/archive and POST …/messages/{id}/restore answer 200 with the message. Asking for the state it already has writes nothing and fires no hook.

  • GET /shows/{show_id}/messages/expired answers 200 { items, dismissed }, the screen’s Recently expired notice: the show’s active messages whose end_date fell in the last 30 days, latest end first. Today is excluded, because a message still shows on its end date. dismissed is true when the current user has dismissed every message listed (false for an empty list). POST …/messages/expired/dismiss answers 200 { items, dismissed: true }. It remembers the messages listed now, for the current user and show, so the notice comes back only when a message is listed that was not dismissed. With no signed-in user it is 401 benecaster_sponsor_manager_no_user.

  • Refusals are 400 benecaster_sponsor_manager_invalid_field with data.field:

    • title empty or over 200 characters
    • body not a string, or over 20,000 characters after wp_kses_post
    • start_date or end_date not a real YYYY-MM-DD date, or end_date before the start (checked against the stored date for the one not sent)
    • sponsor_id not a sponsor, or an archived sponsor the message does not already have (0, '' or null is no sponsor)

    A write the database refuses is 500 benecaster_sponsor_manager_write_failed.

Hooks

They fire for writes made through these routes. A refused request fires nothing, and a failed write fires the before hook alone.

Read messages through these routes, never from the messages table.

Code

<?php
// Log every change to a show's sponsor copy for the ad-sales team.
add_action( 'benecaster_sponsor_manager_after_save_message', function ( int $message_id, int $show_id, array $fields, bool $created ): void {
    if ( array_key_exists( 'body', $fields ) ) {
        my_sales_log( $show_id, $message_id, $created ? 'created' : 'copy changed' );
    }
}, 10, 4 );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →