NAME
    RT-Extension-SMSWebhook-Twilio - Add a webhook to receive SMS from
    Twilio

DESCRIPTION
    A Twilio SMS number can be configured to call a webhook anytime it
    receives a text.

    This RT extension adds a webhook to your RT install to receive the
    webhook call and either create a new ticket or add a comment to an
    existing ticket.

RT VERSION
    Works with RT 5.

INSTALLATION
    perl Makefile.PL
    make
    make install
        May need root permissions

    Edit your /opt/rt5/etc/RT_SiteConfig.pm
        Add this line:

            Plugin('RT::Extension::SMSWebhook::Twilio');

        To allow Twilio to send data to RT without a referrer:

            Set( %ReferrerComponents,
                '/SMSWebhook/Twilio.html' => 1,
            );

        To define the interactions between RT and Twilio:

            Set(
                $SMSWebhookTwilio,
                {
                    url   => 'https://YourRTServer.com/SMSWebhook/Twilio.html',
                    token => 'twilio auth token',
                    queue => 'General',
                }
            );

        The url value is the full url for the webhook, without the username
        and password portion used for web server basic authorization as
        described next.

        The token is the Twilio auth token. See
        <https://support.twilio.com/hc/en-us/articles/223136027-Auth-Tokens-
        and-How-to-Change-Them> for details on finding your auth token.

        The url and token values are used to validate the signature of the
        call made to the webhook to ensure it is coming from Twilio. If the
        signature is failing to validate make sure both of these values are
        correct.

        The queue value is an optional value to specify which queue new
        tickets should be created in when receiving an SMS. It defaults to
        General if not specified.

    Configure your web server to require Basic Authorization for the
    location $WebPath/SMSWebhook/Twilio.html. This is *very important*
    because this plugin does not do any authentication and must be used with
    HTTP Basic Authorization.
        For example:

            <Location /SMSWebhook/Twilio.html>
                AuthType Basic
                AuthName "Twilio WebHook"
                AuthUserFile "/etc/apache2/twiliopass"
                Require valid-user
            </Location>

        /etc/apache2/twiliopass could be generated by command htpasswd:

            htpasswd -c /etc/apache2/twiliopass twilio

    Clear your mason cache
            rm -rf /opt/rt5/var/mason_data/obj

    Restart your webserver

    Set up a webhook in Twilio
        See the video at
        <https://www.twilio.com/docs/usage/webhooks/getting-started-twilio-w
        ebhooks> to learn how to set a Messaging webhook for your Twilio
        phone number.

        When setting the webhook url include the username and password you
        are using in the web server basic authorization as described
        previously:

            https://username:[email protected]/SMSWebhook/Twilio.html

WEBHOOK LOGIC
    When the Twilio webhook receives a call from Twilio it searches for a
    user with a Pager number that matches the from number of the SMS.

    If it does not find a user it creates a new one with the name
    'SMS-###-###-####' using the from number in place of the number signs.
    It then creates a new ticket with the new user as the requestor.

    If it does find a user it then looks for active tickets where that user
    has any role on a ticket. If it finds one active ticket it adds a
    comment to that ticket with the content of the SMS. If it finds zero or
    more than one active ticket it creates a new ticket with the user as the
    requestor.

AUTHOR
    Best Practical Solutions, LLC <[email protected]>

BUGS
    All bugs should be reported via email to
        [email protected]
    or via the web at
        http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-SMSWebhook-Twilio
LICENSE AND COPYRIGHT
    This software is Copyright (c) 2022 by BPS

    This is free software, licensed under:

      The GNU General Public License, Version 2, June 1991