Read or write a show’s sponsor messages from code, as the Sponsors screen’s Messages tab does
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 }.titleis the podcaster’s own name for it, never shown to listeners.bodyis HTML that has been throughwp_kses_post.start_dateandend_dateareYYYY-MM-DDcalendar dates in the site’s time zone, both inclusive, or''when open.sponsor_idis a sponsor’s id,0for none;sponsoris{ id, company, archived }, ornull. Sponsors are site-wide (see Read, create, change, archive or restore the site’s sponsors and a show’s sponsor campaigns from code).statusis where the dates stand today in the site’s time zone:upcoming,running,ended, ornone(no dates).shortcodeis the tag to paste.archivedis 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}/messagesanswers200 { items }: the show’s active messages, title A–Z. Witharchived=1, its archived ones instead. -
POST /shows/{show_id}/messagesanswers201with the new message. It takestitle(required),body,start_date,end_dateandsponsor_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(orPATCH) on the same path changes only the fields sent. -
POST …/messages/{id}/archiveandPOST …/messages/{id}/restoreanswer200with the message. Asking for the state it already has writes nothing and fires no hook. -
GET /shows/{show_id}/messages/expiredanswers200 { items, dismissed }, the screen’s Recently expired notice: the show’s active messages whoseend_datefell in the last 30 days, latest end first. Today is excluded, because a message still shows on its end date.dismissedis true when the current user has dismissed every message listed (false for an empty list).POST …/messages/expired/dismissanswers200 { 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 is401 benecaster_sponsor_manager_no_user. -
Refusals are
400 benecaster_sponsor_manager_invalid_fieldwithdata.field:titleempty or over 200 charactersbodynot a string, or over 20,000 characters afterwp_kses_poststart_dateorend_datenot a realYYYY-MM-DDdate, orend_datebefore the start (checked against the stored date for the one not sent)sponsor_idnot a sponsor, or an archived sponsor the message does not already have (0,''ornullis 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.
- benecaster_sponsor_manager_before_save_message
( int $message_id, int $show_id, array $fields )and benecaster_sponsor_manager_after_save_message( int $message_id, int $show_id, array $fields, bool $created ).$message_idis0before a create.$fieldsholds what is written, cleaned: on a create all five oftitle,body,start_date,end_dateandsponsor_id; on an update only the keys sent. - benecaster_sponsor_manager_before_archive_message and benecaster_sponsor_manager_after_archive_message
( int $message_id, int $show_id, bool $archived ). - benecaster_sponsor_manager_rest_message
( array $data, int $message_id ), a filter over each message a route returns.
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 );
Hooks Used
Need this built rather than just documented? See our services →