DOCSEARCHbyAlgolia
Submit Docs

Yap Documentation

website·Indexed 34 days ago

https://yap.bmlt.app

Documentation for Yap, a PHP-based helpline and meeting search system. Covers installation via Docker, Laravel environment configuration, SMS gateway integration, call routing strategies, and admin REST API authentication using Laravel Sanctum. Includes guides for upgrading between versions (e.g., Yap 4.x to 5.x) and configuring meeting search parameters such as radius, sorting, and geocoding.

Tokens
19K
Snippets
115
Records
187
Agent score
53%

What's inside Yap

  1. Manage multiple Twilio accounts with a single Yap server

    Since version 3.0.0, Yap supports using a single server with multiple Twilio accounts. This allows one service body to manage server overhead while another manages phone numbers and billing. This is achieved through 'configuration precedence,' which allows settings to be defined at a regional level and automatically cascade down to member areas in the BMLT hierarchy without requiring direct access to the server's config.php file.

  2. Understand Yap core functionality

    Yap is designed to bridge BMLT root server results with telephone systems. Its primary capabilities include:

    1. Playing back BMLT root server results over the phone.
    2. Configuring routing rules based on zip codes and helpline numbers, including optional extension dialing.
    3. Managing volunteer schedules and defining rules for answering calls.

  3. System requirements for Yap 5.0

    Yap 5.0 requires the following environment:

    • PHP: Version 8.2 or newer
    • Database: MySQL 8.0+ or MariaDB 10.3+
    • Web Server: Apache-based server with mod_rewrite enabled
    • Security: HTTPS with a valid TLS certificate (required for Twilio webhooks)

  5. Add Public Relations or miscellaneous extensions to Yap

    To add Public Relations or other miscellaneous extensions to the system, utilize the 'Menu Options' and 'Custom Extensions' configuration settings.

  6. Configure Twilio Signature Validation in Yap 5.0

    Yap 5.0 enforces X-Twilio-Signature validation on all Twilio-facing routes. If validation fails, the server returns an HTTP 403, resulting in a total outage for calls and SMS.

    Requirements:

    1. Auth Token: Set twilio_auth_token in config.php to the token of the Twilio account owning the phone numbers.
    2. Trusted Proxies: If Yap is behind a reverse proxy, you must configure TRUSTED_PROXIES so Yap can correctly reconstruct the public URL for signature comparison.

    TRUSTED_PROXIES Configuration:

    • Direct connection (Apache/nginx to PHP): Leave unset.
    • Cloudflare, ngrok, or single-hop load balancer: Set to *.
    • Specific Proxies: Provide a comma-separated list of proxy IPs.

    Caveats:

    • If a proxy strips a URL path prefix (e.g., /yap), the proxy must send X-Forwarded-Prefix: /yap and TRUSTED_PROXIES must be configured.
    • TWILIO_DISABLE_SIGNATURE_VALIDATION=true can be used for development but is ignored in production.

  7. Migrate Yap server data between instances

    To migrate data from a source Yap server to a target server while maintaining configuration integrity, follow these steps:

    1. Clear target configuration: Delete existing configuration for the target service bodies on the destination server to avoid conflicts.
    2. Export source data: Perform a MySQL export from the source server. Select only 'data' and explicitly exclude the flags table. Use a self-contained file.
    3. Sanitize IDs: To prevent ID collisions or incorrect mapping during import, run a sed command to replace numeric IDs with NULLs in the export file.
    4. Import: Import the modified SQL file into the target Yap server.
    5. Configure Overrides: Ensure phone numbers have explicit service body overrides to pull configuration values from the database. Use override_service_body_id to change the service body for call routing, or override_service_body_config_id to select a specific configuration.
    # Step 1: Delete target config
# Run this SQL on the target server
DELETE FROM config where service_body_id in (x [,x]);

# Step 3: Sanitize the export file (replace IDs with NULL)
cat export.sql | sed -e "s/([0-9]*,/(NULL,/g" > export-mod.sql

  8. Install PHP extensions on self-hosted Linux

    Install the extension packages corresponding to your PHP version and restart the service.
    # Debian / Ubuntu (example for PHP 8.2)
sudo apt install php8.2-fpm php8.2-mysql php8.2-mbstring php8.2-xml php8.2-curl php8.2-fileinfo
sudo systemctl restart php8.2-fpm

# RHEL / Alma / Rocky
sudo dnf install php-mysqlnd php-mbstring php-xml php-curl php-fileinfo
sudo systemctl restart php-fpm

  9. Server requirements for Yap installation

    To install and run Yap, your server must meet the following minimum requirements:

    • SSL Certificate: Required for secure connections (mandatory for Twilio integration).
    • PHP: Version 8.2+ with fileinfo and pdo_mysql extensions.
    • Database: MySQL 8.0+ or MariaDB 10.3+.
    • Web Server: Apache with mod_rewrite enabled.

  10. Upgrade Yap from 3.x to 4.x

    Upgrading from Yap 3.x to 4.x is a standard version upgrade with no special one-time migration steps. To upgrade: replace the application files while keeping your existing config.php and database. It is recommended to test the upgrade on a staging copy first.

  11. Set up Google Maps API for Yap

    To enable geolocation and time zone features, obtain a Google Maps API key and assign it to $google_maps_api_key in config.php.

    Requirements:

    • Enable "Google Maps Geocoding API" and "Google Maps Time Zone API" in the Google API console.
    • Use a key separate from your BMLT key.
    • Do not apply server restrictions to this key (it is safe as Yap does not pass the key to the client side).
    $google_maps_api_key = 'your_google_maps_api_key';

  12. Add a volunteer group to the routing list

    Groups do not dial automatically; they must be explicitly added to a service body's routing list. When a group card is enabled and active, Yap expands the group to include all members currently on shift at the time of the call. The selected call strategy (e.g., linear cycle or blasting) is then applied to this expanded list of members.

    Steps to add a group:

    1. Open the Volunteers tab and select the service body.
    2. Click Include Group and select the desired group.
    3. A GROUP card will appear; enable it and drag it to set the dial order relative to individual volunteers.
    4. Click Save Volunteers.