Helpline Support

BMLT has a feature-rich system for NA helplines called yap. It can manage volunteer lists, connect callers with NA volunteers in their areas, read and text BMLT schedule information to the caller, and read the current Just for Today.

WSZF has set up a yap server for the zone, and service bodies are welcome to use it for their helplines. (See Current Status to see which service bodies in the zone are using it.) There is no charge to regions or areas to use the server itself, but regions or areas will need to set up and pay for their own phone numbers using Twilio. You can usually port existing helpline numbers to Twilio. (Areas are reporting significant savings after moving to yap from other phone systems — perhaps 1/6 their previous expenses or even less.)

For questions or to request a yap demo please contact bmlt@wszf.org. If your service body decides to go ahead with yap, or is even seriously considering it, start by getting your own test number from Twilio. Then you can get your number configured to your liking before going live or making a final decision. Some regions (for example Washington/Northern Idaho Region) have a region-wide Twilio account and provide numbers for their areas who want them. This makes things easier for areas to get on, and if your region is a 501(c)(3) nonprofit, you can take advantage of the Twilio nonprofit rate.

Supported Yap Configurations

Folks who have a zonal yap server with dozens of active helplines report that upgrades can be difficult for them since many of the helplines have different configurations and the only way to be sure that yap is still working after an upgrade is to call all of them. But that is prohibitively time-consuming. To address this, the WSZF IT Workgroup has committed to supporting a small number of yap configurations, in that we’ll test any new releases on these configurations. See “WSZF Supported Yap Configurations” (pdf or docx). Regions and areas are free to use any other configurations, but they will need to do their own testing; if something is wrong, notify us and we’ll work with them to fix it.

We also have a mailing list for discussing zonal yap issues, and in particular for giving a couple of days notice when an upgrade is planned, so that folks could know to test. Contact bmlt@wszf.org to be added.

Logging in to yap

The URL for logging into the zone’s yap server is https://bmlt.wszf.org/yap/admin. Normally you log in using your area or region’s BMLT user name and password. It is also possible to set up separate logins if needed, but it will be simpler to just use your BMLT credentials. You will need to log in for the initial configuration, and fairly regularly after that, for example to add and change volunteers, see current volunteer schedules, or mark voicemails as deleted after you’ve dealt with them.

There is a completely separate login for Twilio. You will need to log into that also to get yap set up (unless your region does that for you). After you’re set up, you will probably need to log in to Twilio only occasionally (for example to access billing).

Steps for getting yap set up in your area

  1. Set up an account on Twilio, and buy a new number. Even if you want to port your existing number, it’s good to get a test number to get the setup worked out for your area. Numbers on Twilio are cheap ($1/month for local numbers, plus any per-minute charges for using it). Twilio has free trial numbers, but it’s better to buy one — the free trial number is restricted to only call “validated” numbers, which is most inconvenient even just for testing.
  2. Get yap working for your area with your test number. (See “Configuring yap” below.)
  3. Line up volunteers willing to answer calls, and enter their numbers and times available on the yap admin website. Identify at least one of the volunteers as the person who gets notified when someone leaves a voicemail and who will return calls.
  4. To go live, port your existing number, or publish the new number on your area website and start using it. If you are porting your existing number, you should get the number set up in advance on the Twilio dashboard, so that it will continue working when porting is complete. (Our experience so far is that there isn’t any downtime for the number being ported, although there may be a short time during which some people reach your old helpline service and some people reach yap.)
  5. After you go live, you should probably get your Twilio account set up to automatically add more money when it drops below a certain amount (if you didn’t do this earlier). Twilio has a nonprofit rate; this is worth getting if your service body is a 501(c)(3) nonprofit.

Directions for porting existing numbers to Twilio

Configuring yap

There are two different things you need to configure: the settings on Twilio, and the settings on the yap admin panel.

Settings on Twilio

Log into your Twilio account to set these. The following two screenshots show the webhooks to provide in the Twilio dashboard for using the zone’s yap server. These are for Seattle Area (whose ID is 3 in the zonal server). Substitute the ID for your region or area for the 3 in the URLs. To find this ID, go to https://bmlt.wszf.org/main_server/semantic/, then pick “get service bodies” and click on the “response URL”. The ID will be the number in the first column corresponding to the area or region you want. The webhooks are also shown as text after the screenshot to make it easier to copy and paste them into your Twilio dashboard. Be sure to set HTTP GET or HTTP POST correctly for each of them as well.

Setting up the voice webhooks for yap on the Twilio dashboard
The SMS webhook

Settings on the yap admin panel

Log into the yap admin panel at https://bmlt.wszf.org/yap/admin/ and select your service body. You’ll need to edit settings under both “Call Handling” and “Configure”. See “Supported Yap Configurations” above for recommended groups of settings.

For “Call Handling”, for “Helpline Routing” pick “Volunteers”. Also pick a call strategy. Our usual recommendation is “Blasting, Then Voicemail” — this first calls all of the available volunteers, then sends the call to voicemail if nobody answers. Another option is “Linear Cycle Once, then Voicemail” — this calls volunteers one at a time. The advantage of blasting is that someone will likely answer more quickly; the disadvantage is that you ring volunteers more often. For Inbound call SMS to Volunteer options, you can send an SMS to the volunteers also (including the number that is calling), or not. If you don’t like the synthesized voice that reads the greeting, you can record and upload a custom greeting; if you do that, make sure it says “press 1 to find someone to talk to. Press 2 to search for meetings” in addition to the greeting, since this completely replaces the standard greeting.

For “configure”, some items that you need to override are twilio_account_sid and twilio_auth_token (get these from the Twilio dashboard), and the title (which gets read out to the caller). Yap provides a large number of other settings that can be configured as well. These generally have reasonable default values, so you can just leave them alone if you want (particularly when getting started). Two that are overridden from the factory defaults in the zone’s configuration are:

You can further override these in your region or area configuration. If you set $sms_summary_page = false, the default is to send 5 separate text messages with the top 5 meetings. Instead you can set $sms_combine = true to combine them into one text, or set $sms_ask = true to ask first before sending these texts.

Regional yap servers

In addition to the zonal yap server, some regions in the zone have their own yap servers. It’s fine to continue using those indefinitely, even if the region moves its BMLT data to the zonal server. Alternately, existing yap installations can be re-directed to use the zonal server once the region’s data is moved over, although some work will be needed to fix service body IDs and similar things. Here is a blog post with some suggestions for migrating a regional yap server into a zonal one: https://bmlt.app/merging-a-regional-yap-server-into-a-zonal-yap-server/.