Typical
HS ---> AS : Homeserver sends events with transaction ID T.
   <---    : Application Service sends back 200 OK.

AS ACK Lost
HS ---> AS : Homeserver sends events with transaction ID T.
   <-/-    : AS 200 OK is lost.
HS ---> AS : Homeserver retries with the same transaction ID of T.
   <---    : Application Service sends back 200 OK. If the AS had processed these
             events already, it can NO-OP this request (and it knows if it is the
             same events based on the transaction ID).

2.2.3.1   PUT /_matrix/app/v1/transactions/{txnId}

This API is called by the homeserver when it wants to push an event (or batch of events) to the application service.

Note that the application service should distinguish state events from message events via the presence of a state_key, rather than via the event type.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
txnId	string	Required. The transaction ID for this set of events. Homeservers generate these IDs and they are used to ensure idempotency of requests.
JSON body parameters
events	[Event]	Required. A list of events, formatted as per the Client-Server API.

Example request:

PUT /_matrix/app/v1/transactions/35 HTTP/1.1
Content-Type: application/json

{
  "events": [
    {
      "content": {
        "membership": "join",
        "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
        "displayname": "Alice Margatroid"
      },
      "type": "m.room.member",
      "event_id": "$143273582443PhrSn:example.org",
      "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
      "sender": "@example:example.org",
      "origin_server_ts": 1432735824653,
      "unsigned": {
        "age": 1234
      },
      "state_key": "@alice:example.org"
    },
    {
      "content": {
        "body": "This is an example text message",
        "msgtype": "m.text",
        "format": "org.matrix.custom.html",
        "formatted_body": "<b>This is an example text message</b>"
      },
      "type": "m.room.message",
      "event_id": "$143273582443PhrSn:example.org",
      "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
      "sender": "@example:example.org",
      "origin_server_ts": 1432735824653,
      "unsigned": {
        "age": 1234
      }
    }
  ]
}

Response:

Status code 200:

The transaction was processed successfully.

Example

{}

2.2.4.1   GET /_matrix/app/v1/users/{userId}

This endpoint is invoked by the homeserver on an application service to query the existence of a given user ID. The homeserver will only query user IDs inside the application service's users namespace. The homeserver will send this request when it receives an event for an unknown user ID in the application service's namespace, such as a room invite.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
userId	string	Required. The user ID being queried.

Example request:

GET /_matrix/app/v1/users/%40alice%3Aexample.com HTTP/1.1

Responses:

Status code 200:

The application service indicates that this user exists. The application service MUST create the user using the client-server API.

Example

{}

Status code 401:

The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

Status code 403:

The credentials supplied by the homeserver were rejected.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}

Status code 404:

The application service indicates that this user does not exist. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}

2.2.4.2   GET /_matrix/app/v1/rooms/{roomAlias}

This endpoint is invoked by the homeserver on an application service to query the existence of a given room alias. The homeserver will only query room aliases inside the application service's aliases namespace. The homeserver will send this request when it receives a request to join a room alias within the application service's namespace.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomAlias	string	Required. The room alias being queried.

Example request:

GET /_matrix/app/v1/rooms/%23magicforest%3Aexample.com HTTP/1.1

Responses:

Status code 200:

The application service indicates that this room alias exists. The application service MUST have created a room and associated it with the queried room alias using the client-server API. Additional information about the room such as its name and topic can be set before responding.

Example

{}

Status code 401:

The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

Status code 403:

The credentials supplied by the homeserver were rejected.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}

Status code 404:

The application service indicates that this room alias does not exist. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}

2.2.5.1   GET /_matrix/app/v1/thirdparty/protocol/{protocol}

This API is called by the homeserver when it wants to present clients with specific information about the various third party networks that an application service supports.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
protocol	string	Required. The protocol ID.

Response format:

Protocol

Parameter	Type	Description
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.
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.
icon	string	Required. A content URI representing an icon for the third party protocol.
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.
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.

Field Type

Parameter	Type	Description
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.
placeholder	string	Required. An placeholder serving as a valid example of the field value.

Protocol Instance

Parameter	Type	Description
desc	string	Required. A human-readable description for the protocol, such as the name.
icon	string	An optional content URI representing the protocol. Overrides the one provided at the higher level Protocol object.
fields	object	Required. Preset values for fields the client may use to search by.
network_id	string	Required. A unique identifier across all instances.

Example request:

GET /_matrix/app/v1/thirdparty/protocol/irc HTTP/1.1

Responses:

Status code 200:

The protocol was found and metadata returned.

Example

{
  "irc": {
    "user_fields": [
      "network",
      "nickname"
    ],
    "location_fields": [
      "network",
      "channel"
    ],
    "icon": "mxc://example.org/aBcDeFgH",
    "field_types": {
      "network": {
        "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
        "placeholder": "irc.example.org"
      },
      "nickname": {
        "regexp": "[^\\s]+",
        "placeholder": "username"
      },
      "channel": {
        "regexp": "#[^\\s]+",
        "placeholder": "#foobar"
      }
    },
    "instances": [
      {
        "network_id": "freenode",
        "desc": "Freenode",
        "icon": "mxc://example.org/JkLmNoPq",
        "fields": {
          "network": "freenode.net"
        }
      }
    ]
  },
  "gitter": {
    "user_fields": [
      "username"
    ],
    "location_fields": [
      "room"
    ],
    "field_types": {
      "username": {
        "regexp": "@[^\\s]+",
        "placeholder": "@username"
      },
      "room": {
        "regexp": "[^\\s]+\\/[^\\s]+",
        "placeholder": "matrix-org/matrix-doc"
      }
    },
    "instances": [
      {
        "network_id": "gitter",
        "desc": "Gitter",
        "icon": "mxc://example.org/zXyWvUt",
        "fields": {}
      }
    ]
  }
}

Status code 401:

The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

Status code 403:

The credentials supplied by the homeserver were rejected.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}

Status code 404:

No protocol was found with the given path.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}

2.2.5.2   GET /_matrix/app/v1/thirdparty/user/{protocol}

This API is called by the homeserver in order to retrieve a Matrix User ID linked to a user on the third party network, given a set of user parameters.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
protocol	string	Required. The protocol ID.
query parameters
fields...	string	One or more custom fields that are passed to the application service to help identify the user.

Response format:

Parameter	Type	Description
<body>	[User]	List of matched third party users.

User

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

Example request:

GET /_matrix/app/v1/thirdparty/user/irc HTTP/1.1

Responses:

Status code 200:

The Matrix User IDs found with the given parameters.

Example

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

Status code 401:

The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

Status code 403:

The credentials supplied by the homeserver were rejected.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}

Status code 404:

No users were found with the given parameters.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}

2.2.5.3   GET /_matrix/app/v1/thirdparty/location/{protocol}

Retrieve a list of Matrix portal rooms that lead to the matched third party location.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
protocol	string	Required. The protocol ID.
query parameters
fields...	string	One or more custom fields that are passed to the application service to help identify the third party location.

Response format:

Parameter	Type	Description
<body>	[Location]	List of matched third party locations.

Location

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

Example request:

GET /_matrix/app/v1/thirdparty/location/irc HTTP/1.1

Responses:

Status code 200:

At least one portal room was found.

Example

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

Status code 401:

The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

Status code 403:

The credentials supplied by the homeserver were rejected.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}

Status code 404:

No mappings were found with the given parameters.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}

2.2.5.4   GET /_matrix/app/v1/thirdparty/location

Retrieve an array of third party network locations from a Matrix room alias.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
query parameters
alias	string	The Matrix room alias to look up.

Response format:

Parameter	Type	Description
<body>	[Location]	List of matched third party locations.

Location

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

Example request:

GET /_matrix/app/v1/thirdparty/location HTTP/1.1

Responses:

Status code 200:

All found third party locations.

Example

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

Status code 401:

The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

Status code 403:

The credentials supplied by the homeserver were rejected.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}

Status code 404:

No mappings were found with the given parameters.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}

2.2.5.5   GET /_matrix/app/v1/thirdparty/user

Retrieve an array of third party users from a Matrix User ID.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
query parameters
userid	string	The Matrix User ID to look up.

Response format:

Parameter	Type	Description
<body>	[User]	List of matched third party users.

User

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

Example request:

GET /_matrix/app/v1/thirdparty/user HTTP/1.1

Responses:

Status code 200:

An array of third party users.

Example

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

Status code 401:

The homeserver has not supplied credentials to the application service. Optional error information can be included in the body of this response.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

Status code 403:

The credentials supplied by the homeserver were rejected.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}

Status code 404:

No mappings were found with the given parameters.

Example

{
  "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}

2.3.5.1   PUT /_matrix/client/r0/directory/list/appservice/{networkId}/{roomId}

Updates the visibility of a given room on the application service's room directory.

This API is similar to the room directory visibility API used by clients to update the homeserver's more general room directory.

This API requires the use of an application service access token (as_token) instead of a typical client's access_token. This API cannot be invoked by users who are not identified as application services.

Rate-limited:	No.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
networkId	string	Required. The protocol (network) ID to update the room list for. This would have been provided by the application service as being listed as a supported protocol.
roomId	string	Required. The room ID to add to the directory.
JSON body parameters
visibility	enum	Required. Whether the room should be visible (public) in the directory or not (private). One of: ["public", "private"]

Example request:

PUT /_matrix/client/r0/directory/list/appservice/irc/%21somewhere%3Aexample.org HTTP/1.1
Content-Type: application/json

{
  "visibility": "public"
}

Response:

Status code 200:

The room's directory visibility has been updated.

Example

{}