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/v3/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.

[
  {
    "alias": "#freenode_#matrix:matrix.org",
    "fields": {
      "channel": "#matrix",
      "network": "freenode"
    },
    "protocol": "irc"
  }
]

404 response

Error
Name	Type	Description
`errcode`	`string`	Required: An error code.
`error`	`string`	A human-readable error message.

{
  "errcode": "M_NOT_FOUND"
}

GET /_matrix/client/v3/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.

[
  {
    "alias": "#freenode_#matrix:matrix.org",
    "fields": {
      "channel": "#matrix",
      "network": "freenode"
    },
    "protocol": "irc"
  }
]

404 response

Error
Name	Type	Description
`errcode`	`string`	Required: An error code.
`error`	`string`	A human-readable error message.

{
  "errcode": "M_NOT_FOUND"
}

GET /_matrix/client/v3/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",
  "instances": [
    {
      "desc": "Freenode",
      "fields": {
        "network": "freenode"
      },
      "icon": "mxc://example.org/JkLmNoPq",
      "network_id": "freenode"
    }
  ],
  "location_fields": [
    "network",
    "channel"
  ],
  "user_fields": [
    "network",
    "nickname"
  ]
}

404 response

Error
Name	Type	Description
`errcode`	`string`	Required: An error code.
`error`	`string`	A human-readable error message.

{
  "errcode": "M_NOT_FOUND"
}

GET /_matrix/client/v3/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.

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.

{
  "gitter": {
    "field_types": {
      "room": {
        "placeholder": "matrix-org/matrix-doc",
        "regexp": "[^\\s]+\\/[^\\s]+"
      },
      "username": {
        "placeholder": "@username",
        "regexp": "@[^\\s]+"
      }
    },
    "instances": [
      {
        "desc": "Gitter",
        "fields": {},
        "icon": "mxc://example.org/zXyWvUt",
        "network_id": "gitter"
      }
    ],
    "location_fields": [
      "room"
    ],
    "user_fields": [
      "username"
    ]
  },
  "irc": {
    "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",
    "instances": [
      {
        "desc": "Freenode",
        "fields": {
          "network": "freenode.net"
        },
        "icon": "mxc://example.org/JkLmNoPq",
        "network_id": "freenode"
      }
    ],
    "location_fields": [
      "network",
      "channel"
    ],
    "user_fields": [
      "network",
      "nickname"
    ]
  }
}

GET /_matrix/client/v3/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.

[
  {
    "fields": {
      "user": "jim"
    },
    "protocol": "gitter",
    "userid": "@_gitter_jim:matrix.org"
  }
]

404 response

Error
Name	Type	Description
`errcode`	`string`	Required: An error code.
`error`	`string`	A human-readable error message.

{
  "errcode": "M_NOT_FOUND"
}

GET /_matrix/client/v3/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.

[
  {
    "fields": {
      "user": "jim"
    },
    "protocol": "gitter",
    "userid": "@_gitter_jim:matrix.org"
  }
]

404 response

Error
Name	Type	Description
`errcode`	`string`	Required: An error code.
`error`	`string`	A human-readable error message.

{
  "errcode": "M_NOT_FOUND"
}