Merge pull request #1628 from turt2live/travis/as/external_url

Clarify how external_url is supposed to work

specification/application_service_api.rst

@@ -417,11 +417,18 @@ additional parameters on the ``/publicRooms`` client-server endpoint.
 
 {{appservice_room_directory_cs_http_api}}
 
-Event fields
+Referencing messages from a third party network
-~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Application services should include an ``external_url`` in the ``content`` of
+events it emits to indicate where the message came from. This typically applies
+to application services that bridge other networks into Matrix, such as IRC,
+where an HTTP URL may be available to reference. 
+
+Clients should provide users with a way to access the ``external_url`` if it
+is present. Clients should additionally ensure the URL has a scheme of ``https``
+or ``http`` before making use of it.
 
-We recommend that any events that originated from a remote network should
+The presence of an ``external_url`` on an event does not necessarily mean the
-include an ``external_url`` field in their content to provide a way for Matrix
+event was sent from an application service. Clients should be wary of the URL
-clients to link into the 'native' client from which the event originated.
+contained within, as it may not be a legitimate reference to the event's source.
-For instance, this could contain the message-ID for emails/nntp posts, or a link
-to a blog comment when bridging blog comment traffic in & out of Matrix.