Third Party Networks

Application services can provide access to third party networks via bridging. This allows Matrix users to communicate with users on other communication platforms, with messages ferried back and forth by the application service. A single application service may bridge multiple third party networks, and many individual locations within those networks. A single third party network location may be bridged to multiple Matrix rooms.

Third Party Lookups

A client may wish to provide a rich interface for joining third party locations and connecting with third party users. Information necessary for such an interface is provided by third party lookups.

GET /_matrix/client/r0/thirdparty/location

Retrieve an array of third party network locations from a Matrix room alias.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
alias string Required: The Matrix room alias to look up.

Responses

Status Description
200 All found third party locations.
404 The Matrix room alias was not found

200 response

Array of Location.

Location
Name Type Description
alias string Required: An alias for a matrix room.
fields object Required: Information used to identify this third party location.
protocol string Required: The protocol ID that the third party location is a part of.

404 response

Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_NOT_FOUND"
}

GET /_matrix/client/r0/thirdparty/location/{protocol}

Requesting this endpoint with a valid protocol name results in a list of successful mapping results in a JSON array. Each result contains objects to represent the Matrix room or rooms that represent a portal to this third party network. Each has the Matrix room alias string, an identifier for the particular third party network protocol, and an object containing the network-specific fields that comprise this identifier. It should attempt to canonicalise the identifier as much as reasonably possible given the network type.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
protocol string Required: The protocol used to communicate to the third party network.
query parameters
Name Type Description
searchFields string One or more custom fields to help identify the third party location.

Responses

Status Description
200 At least one portal room was found.
404 No portal rooms were found.

200 response

Array of Location.

Location
Name Type Description
alias string Required: An alias for a matrix room.
fields object Required: Information used to identify this third party location.
protocol string Required: The protocol ID that the third party location is a part of.

404 response

Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_NOT_FOUND"
}

GET /_matrix/client/r0/thirdparty/protocol/{protocol}

Fetches the metadata from the homeserver about a particular third party protocol.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
protocol string Required: The name of the protocol.

Responses

Status Description
200 The protocol was found and metadata returned.
404 The protocol is unknown.

200 response

Protocol
Name Type Description
field_types { string: Field Type} Required:

The type definitions for the fields defined in the user_fields and location_fields. Each entry in those arrays MUST have an entry here. The string key for this object is field name itself.

May be an empty object if no fields are defined.
icon string Required: A content URI representing an icon for the third party protocol.
instances [Protocol Instance] Required: A list of objects representing independent instances of configuration. For example, multiple networks on IRC if multiple are provided by the same application service.
location_fields [string] Required: Fields which may be used to identify a third party location. These should be ordered to suggest the way that entities may be grouped, where higher groupings are ordered first. For example, the name of a network should be searched before the name of a channel.
user_fields [string] Required: Fields which may be used to identify a third party user. These should be ordered to suggest the way that entities may be grouped, where higher groupings are ordered first. For example, the name of a network should be searched before the nickname of a user.
Field Type
Name Type Description
placeholder string Required: An placeholder serving as a valid example of the field value.
regexp string Required: A regular expression for validation of a field’s value. This may be relatively coarse to verify the value as the application service providing this protocol may apply additional validation or filtering.
Protocol Instance
Name Type Description
desc string Required: A human-readable description for the protocol, such as the name.
fields object Required: Preset values for fields the client may use to search by.
icon string An optional content URI representing the protocol. Overrides the one provided at the higher level Protocol object.
network_id string Required: A unique identifier across all instances. 
{
  "field_types": {
    "channel": {
      "placeholder": "#foobar",
      "regexp": "#[^\\s]+"
    },
    "network": {
      "placeholder": "irc.example.org",
      "regexp": "([a-z0-9]+\\.)*[a-z0-9]+"
    },
    "nickname": {
      "placeholder": "username",
      "regexp": "[^\\s#]+"
    }
  },
  "icon": "mxc://example.org/aBcDeFgH",
  "location_fields": [
    "network",
    "channel"
  ],
  "user_fields": [
    "network",
    "nickname"
  ]
}

404 response

Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_NOT_FOUND"
}

GET /_matrix/client/r0/thirdparty/protocols

Fetches the overall metadata about protocols supported by the homeserver. Includes both the available protocols and all fields required for queries against each protocol.
Rate-limited: No
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The protocols supported by the homeserver.

GET /_matrix/client/r0/thirdparty/user

Retrieve an array of third party users from a Matrix User ID.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
userid string Required: The Matrix User ID to look up.

Responses

Status Description
200 An array of third party users.
404 The Matrix User ID was not found

200 response

Array of User.

User
Name Type Description
fields object Required: Information used to identify this third party location.
protocol string Required: The protocol ID that the third party location is a part of.
userid string Required: A Matrix User ID represting a third party user.

404 response

Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_NOT_FOUND"
}

GET /_matrix/client/r0/thirdparty/user/{protocol}

Retrieve a Matrix User ID linked to a user on the third party service, given a set of user parameters.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
protocol string Required: The name of the protocol.
query parameters
Name Type Description
fields... string One or more custom fields that are passed to the AS to help identify the user.

Responses

Status Description
200 The Matrix User IDs found with the given parameters.
404 The Matrix User ID was not found

200 response

Array of User.

User
Name Type Description
fields object Required: Information used to identify this third party location.
protocol string Required: The protocol ID that the third party location is a part of.
userid string Required: A Matrix User ID represting a third party user.

404 response

Name Type Description
errcode string Required: An error code.
error string A human-readable error message. 
{
  "errcode": "M_NOT_FOUND"
}