mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-13 23:14:10 +01:00
9bbb9c5397
I asked about this on matrix, and tulir confirmed[1] that the error schema was intended to be shared between all APIs. I would like the shared schema to be explicit in the spec text so that ruma can move to using the same error type for client-server and server-server endpoints. This would simplify error handling in server implementations. Error codes that are used in more than one API were moved to the appendices, while error codes specific to only one API were left there. Since the docs on which error codes are actually used by which endpoints aren't very complemete, I determined this by looking at the synapse source code. [1]: https://matrix.to/#/#matrix-spec-discussion:neko.dev/$Y2yTCeR_AeW6g_4jViFbx4gTE_AwF0RN7yrHJ25F5Q8 Signed-off-by: Olivia Lee <olivia@computer.surgery>
73 lines
2.9 KiB
Markdown
73 lines
2.9 KiB
Markdown
---
|
|
title: "Push Gateway API"
|
|
weight: 50
|
|
type: docs
|
|
---
|
|
|
|
Clients may want to receive push notifications when events are received
|
|
at the homeserver. This is managed by a distinct entity called the Push
|
|
Gateway.
|
|
|
|
## Overview
|
|
|
|
A client's homeserver forwards information about received events to the
|
|
push gateway. The gateway then submits a push notification to the push
|
|
notification provider (e.g. APNS, GCM).
|
|
|
|
```
|
|
+--------------------+ +-------------------+
|
|
Matrix HTTP | | | |
|
|
Notification Protocol | App Developer | | Device Vendor |
|
|
| | | |
|
|
+-------------------+ | +----------------+ | | +---------------+ |
|
|
| | | | | | | | | |
|
|
| Matrix homeserver +-----> Push Gateway +------> Push Provider | |
|
|
| | | | | | | | | |
|
|
+-^-----------------+ | +----------------+ | | +----+----------+ |
|
|
| | | | | |
|
|
Matrix | | | | | |
|
|
Client/Server API + | | | | |
|
|
| | +--------------------+ +-------------------+
|
|
| +--+-+ |
|
|
| | <-------------------------------------------+
|
|
+---+ |
|
|
| | Provider Push Protocol
|
|
+----+
|
|
|
|
Mobile Device or Client
|
|
```
|
|
|
|
## API standards
|
|
|
|
### Standard error response
|
|
|
|
All push gateway API endpoints MUST return error responses conforming to the
|
|
[standard error response](/appendices#standard-error-response) schema.
|
|
|
|
### Unsupported endpoints
|
|
|
|
If a request for an unsupported (or unknown) endpoint is received then the server
|
|
must respond with a 404 `M_UNRECOGNIZED` error.
|
|
|
|
Similarly, a 405 `M_UNRECOGNIZED` error is used to denote an unsupported method
|
|
to a known endpoint.
|
|
|
|
## Homeserver behaviour
|
|
|
|
This describes the format used by "HTTP" pushers to send notifications
|
|
of events to Push Gateways. If the endpoint returns an HTTP error code,
|
|
the homeserver SHOULD retry for a reasonable amount of time using
|
|
exponential backoff.
|
|
|
|
When pushing notifications for events, the homeserver is expected to
|
|
include all of the event-related fields in the `/notify` request. When
|
|
the homeserver is performing a push where the `format` is
|
|
`"event_id_only"`, only the `event_id`, `room_id`, `counts`, and
|
|
`devices` are required to be populated.
|
|
|
|
Note that most of the values and behaviour of this endpoint is described
|
|
by the Client-Server API's [Push
|
|
Module](/client-server-api#push-notifications).
|
|
|
|
{{% http-api spec="push-gateway" api="push_notifier" %}}
|