MessageBee and Koha - Library Setup
How does it work?
MessageBee can send email, SMS, and/or phone messages, connected by a plugin. Koha notice templates are updated with YAML, indicating that it should be transmitted to MessageBee, rather than sending from Koha.
Notice setup
What notices can MessageBee send?
Currently,
MessageBee can send CHECKOUT, RENEWAL, CHECKIN, HOLD, HOLDDGST, HOLD_REMINDER, HOLD_CANCELLATION, CANCEL_HOLD_ON_LOST, PREDUE, PREDUEDGST, DUE, DUEDGST, AUTO_RENEWALS, AUTO_RENEWALS_DGST, MEMBERSHIP_EXPIRY, WELCOME HOLD, and up to 3 ODUEs.
System preferences
- If sending SMS messages, set SMSSendDriver to "MessageBee".
- If sending Voice messages, set PhoneNotification to "Enable".
Plugin configuration
Install and configure the MessageBee plugin on your site, adding library credentials (host, username, and password).
Notice configuration
In Tools > Notices and slips, for all notices the library will be sending through MessageBee:
- Copy/paste the YAML syntax from the Github documentation into the Email, SMS, and/or Phone tabs, as applicable.
- Keep content in the Print tab for any notices that the library will want to print.
Messaging settings and related preferences
Do staff need to capture patrons' mobile provider for MessageBee SMS messages?
No, the mobile provider is not necessary for SMS messages sent through MessageBee.
Do SMS numbers need hyphens?
No, SMS numbers do not need hyphens.
Do SMS numbers need the leading 1?
No, SMS numbers do not need the leading 1. MessageBee will add it on their end. If your phone numbers have the leading 1, you do not need to remove them.
How does MessageBee know what messages to send?
When a message to a patron is triggered by messaging preferences or overdue notice triggers, anything in a template where Koha finds "messagebee: yes" will be compiled and transmitted to MessageBee via the plugin. When the process_message_queue.pl cron runs, it passes those YAML bits to the plugin, the plugin pulls the related metadata for the indicated patron, checkout, item, etc. and this information is formatted into a JSON file and sent to MessageBee.
How will libraries know what MessageBee-controlled notices have been sent/delivered?
Patrons’ Notices tab will display the YAML data that was transmitted to MessageBee via the plugin. Libraries should contact MessageBee for the specific formatted notices sent to patrons.
Frequently Asked Questions
Can a message be resent?
Libraries can resend notices from the patron screen. The message status reverts to pending and the plugin will grab that message, and transmit it to MessageBee again.
If a checked out item is returned to the library, will the patron still get a message?
Yes. The plugin will check the issues table before compiling the JSON file to send to MessageBee. If it doesn't find the checkout, it will look to the oldissues table and pull the data for the JSON blob to send to MessageBee from there instead. For this reason, a checkout message can be sent to MessageBee, even after an item has been returned.
What happens if a hold generates a message and the patron checks it out before MessageBee gets the hold waiting message?
Rather than getting both the checkout and hold waiting message, the patron will only receive the checked out message.
Why do I see a 'deleted' status for MessageBee notices in a patron's Notices tab?
For some notices (observed with HOLD SMS), Koha will add the message to the message queue with a pending status. The MessageBee plugin sees this and takes any message with a 'pending' status and content like 'messagebee:yes' and puts that in a JSON file that is transmitted to MessageBee. After that, the plugin changes the status of the message from 'pending' to 'deleted'. This is so Koha doesn't attempt to send the message that MessageBee is already sending.
Troubleshooting
If MessageBee notices are not delivering as expected, there are three places to check, in order:
- Check Github to be sure that latest version of the plugin is installed.
- Check your notice templates and confirm that the YAML blobs are entered correctly.
- Open a ticket with ByWater to have our Systems team confirm that the process_message_queue.pl scripts are correct.
Related Articles
Patron Point and Koha - Library Setup
How does it work? Patron Point can send email, SMS, and/or phone messages. Similar to SIP users, an API patron/user allows third party integrations such as Patron Point to connect to Koha. The API patron will have permissions that allow it to ...Notices in Koha
Notices are a powerful way to communicate with patrons about their checked-out materials, holds, renewals, etc. Koha has many options for customizing the notices and customizing how they are delivered, both through settings configuration and through ...Overview: Courtesy and Overdue Notices in Koha
This article reviews configuration and settings for Koha's courtesy and overdue notices. It is meant as an overview for libraries in implementation or for any library who is new to using these notices. Note that there are many more notices and slips ...Preparing for Library Closures
Libraries sometimes have to close for different reasons. Here are the steps to prepare Koha for a closure. Many of these questions are significantly more complicated for multi-branch or multi-library systems. We've attempted to note those areas ...Reopening Your Library
While we can very quickly sum up what you need to do for your ILS (change all the settings in Koha back to what they were before you closed), there’s a bit more to it. This article will help guide you through the process. If you contacted us to ...