# PHP XMPP Invitation Landing Page

This is an XMPP invitation landing page that client developers or XMPP server
admins can host on their servers. It allows users to send XMPP invitations
(contacts or chat rooms) to people who do not have an XMPP client yet. This is
part of the [Easy XMPP](https://wiki.xmpp.org/web/Easy_XMPP) initiative to
improve the ["first contact"](https://wiki.xmpp.org/web/Easy_Onboarding#First_Contact)
experience.

For the JID romeo@xmpp.example, it will create the following page ([live example](https://zachdecook.com/chat?romeo@xmpp.example)):

> # Invitation from Romeo
> 
> ## Romeo has invited you to chat
>
>   [**[Add Romeo to Contact List]**](https://zachdecook.com/chat?romeo@xmpp.example)
> 
> `xmpp:romeo@xmpp.example`
>
> If this link does not work, you need to install and configure an XMPP client, and visit this page again afterwards.
> 
> *[snipped client list and disclaimer]*


## Principal operation

 * Romeo clicks on his XMPP client's "Create Invitation" button
    * The server provides the URI, and
    * either the server provides an invite web page link, or the client transforms the link into a landing page link.
 * Romeo sends the resulting invitation link via E-Mail, SMS, QR-Code, [A5S2 messenger](http://shakespeare.mit.edu/romeo_juliet/romeo_juliet.5.2.html) or any other means to Juliet.
 * Juliet opens the link in a web browser, which has a button linking to the `xmpp:` URI
   * If Juliet has an XMPP client, it will handle the button click and open the "Add to roster" dialog
   * If Juliet does not have an XMPP client, the link won't work. She must install a client and return to the link later


## Supported URIs

* [xmpp:romeo@xmpp.example](https://zachdecook.com/chat?romeo@xmpp.example)
* [xmpp:name@muc.example.com?join](https://zachdecook.com/chat?xmpp:name@muc.example.com?join)
* Registration with pre-defined account name ([XEP-0445](https://xmpp.org/extensions/xep-0445.html#sect-idm46085194296336)):  [xmpp:juliet@example.com?register;preauth=TOKEN](https://zachdecook.com/chat?xmpp:juliet@example.com?register;preauth=TOKEN)
* Registration on a server ([XEP-0445](https://xmpp.org/extensions/xep-0445.html#sect-idm46085194293584)):  [xmpp:example.com?register;preauth=TOKEN](https://zachdecook.com/chat?xmpp:example.com?register;preauth=TOKEN)
* Contact Invitation with IBR ([XEP-0445](https://xmpp.org/extensions/xep-0445.html#sect-idm46085194290992)) [xmpp:romeo@example.com?roster;preauth=TOKEN;ibr=y](https://zachdecook.com/chat?xmpp:romeo@example.com?roster;preauth=TOKEN;ibr=y)


## Design decisions

 * The (privacy sensitive) JID and parameters are put into the Query String, which **is** transmitted to the hosting server
 * The fragment is parsed by the receiving server, this **doesn't** require JavaScript
 * User agent string is parsed server-side.

## Privacy considerations

Don't use an instance from an untrusted server administrator.
A malicious server administrator could use the URI
(just the same as someone who intercepted the message).

## Inspiration

This project was forked from [easy-xmpp-invitation](https://github.com/ge0rg/easy-xmpp-invitation), which implements this with client-side javascript.

## License

This code is licensed under the MIT License.