Skip to main content

Setup

This will require that you have an SSL certificate installed on your webserver to transit a secure connection. This is required by Twilio.

Before you begin, confirm your server meets the PHP requirements: PHP 8.2+, the required PHP extensions (especially fileinfo and pdo_mysql), MySQL 8.0+ or MariaDB 10.3+, and Apache with mod_rewrite. On shared Linux hosting you enable extensions in your provider's control panel; on self-hosted Linux you install the matching php-* packages yourself.

  1. Create a new virtual application or add the yap code to an existing folder. If config.php does not exist yet, Yap shows the first-run installer until you create that file. You can always find the latest stable version here (be sure download the yap-x-x-x.zip file and not the source code): https://github.com/bmlt-enabled/yap/releases/latest. You can also try out or help test the latest bleeding edge features by installing one of the unreleased versions. The newest version would always be the highest numbered build.

  2. Once the application is configured you will need to customize the config.php file. There are several settings there that are documented in that file. There are a number of different ways to utilize the yap platform.

  3. You will need to (config.php) enter $twilio_account_sid and $twilio_auth_token. You can find this on your account dashboard. An empty $twilio_auth_token causes every inbound IVR call to return HTTP 403 — set a real token before going live. You can also use a different Twilio account using the admin portal under "Service Bodies". Keep in mind that if a key or keys are set at any parent above, all child service bodies will inherit that key. In order to use a key, just specify override_service_body_id in your webhook with the applicable id. You will also need to set a webhook for Call Detail Records. It is possible to use dummy credentials as a workaround if you do not intend for a service body to make use of the credentials in config.php, but instead use the credentials configured in service body configuration overrides.

twilio-status-callback

  1. You will need to ensure that the following config.php parameters are set. They should be a service body admin that will be responsible for reading and writing data back to your BMLT. This will not work with the "Server Administrator" account. The user should be at the highest level of access in your BMLT hierarchy that you require access to.
static $bmlt_username = "";
static $bmlt_password = "";

  1. Be sure to get a Google Maps API key. Specify this in config.php as the value for $google_maps_api_key. Make sure you have "Google Maps Geocoding API" and "Google Maps Time Zone API" enabled on your credentials. This key must be separate from your BMLT key with no server restrictions, this is safe because yap never passes the key client side. You can login into your Google API console here: https://console.cloud.google.com/apis/. This article may be useful https://bmlt.app/google-maps-api-keys-and-geolocation-issues/.

  2. Try testing that your application actually is functioning properly by opening a browser http://example.com/index.php.

  3. You will need to set up a Twilio account, and do the following. Purchase a phone number (typically you would buy one for your locale, tollfree is pretty much unnecessary these days). Configure that number to point to a Webook. It would be something like https://example.com/index.php. If you want to skip helpline call routing you can do that with the instructions here.

  4. You will need to set up a new MySQL database. Be sure to set up backups on your database as well. Your hosting provider may cover this more. Once you've done that, set the following in your config.php.

static $mysql_hostname = "";
static $mysql_username = "";
static $mysql_password = "";
static $mysql_database = "";

  1. You can test whether or not you are properly configured by going to https://example.com/api/v1/upgrade. On first deploy, pending schema migrations may run automatically on the first HTTP request. See Upgrading from Yap 4.x to Yap 5.x for details. After logging in to the admin portal, Dashboard and System Health show the same upgrade advisor checks.

  2. Make a call to your number and try it out. If there is a problem the debugger in the Twilio console will let you know why. Most likely you did not setup your config.php file correctly.

Laravel environment variables​

Yap stores most settings in config.php, but several Laravel .env values affect the admin SPA and Twilio webhooks. Copy src/.env.example to src/.env and review:

  • TRUSTED_PROXIES — required behind reverse proxies so Twilio signature validation sees the public URL.
  • SESSION_DRIVER — use file or redis; never database (conflicts with Yap's call-PIN sessions table).
  • SANCTUM_STATEFUL_DOMAINS — hosts that receive session cookies for SPA authentication.
  • TWILIO_DISABLE_SIGNATURE_VALIDATION — bypass validation outside production only; never on a live helpline.