---
title: "Modify a pusher for this user on the homeserver."
method: POST
path: "/_matrix/client/v3/pushers/set"
tags: ["Push notifications"]
---

# Modify a pusher for this user on the homeserver.

`POST /_matrix/client/v3/pushers/set`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/pushers/set`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/pushers/set/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint allows the creation, modification and deletion of [pushers](https://spec.matrix.org/v1.19/client-server-api/#push-notifications)
for this user ID. The behaviour of this endpoint varies depending on the
values in the JSON body.

If `kind` is not `null`, the pusher with this `app_id` and `pushkey`
for this user is updated, or it is created if it doesn't exist. If
`kind` is `null`, the pusher with this `app_id` and `pushkey` for this
user is deleted.

## Request body

- object
  - `app_display_name` string: Required if `kind` is not `null`. A string that will allow the user to identify what application owns this pusher.
  - `app_id` string, required: This is a reverse-DNS style identifier for the application. It is recommended that this end with the platform, such that different platform versions get different app identifiers. Max length, 64 chars. If the `kind` is `"email"`, this is `"m.email"`.
  - `append` boolean: If true, the homeserver should add another pusher with the given pushkey and App ID in addition to any others with different user IDs. Otherwise, the homeserver must remove any other pushers with the same App ID and pushkey for different users. The default is `false`.
  - `data` object: Required if `kind` is not `null`. A dictionary of information for the pusher implementation itself. If `kind` is `http`, this MUST contain `url` which is the URL to use for sending notifications. Clients MAY use this object to pass custom data to their push gateway. Servers MUST forward the entire content including `format` and any custom keys but excluding `url` when calling [`/_matrix/push/v1/notify`](https://spec.matrix.org/v1.19/push-gateway-api/#post_matrixpushv1notify).
    - `format` 'event_id_only': The format in which to send notifications to the push gateway if the `kind` is `http`. The details about what fields the homeserver should include are defined in the [Push Gateway Specification](https://spec.matrix.org/v1.19/push-gateway-api/). If omitted, the server is expected to populate all of the event-related fields specified in [`/_matrix/push/v1/notify`](https://spec.matrix.org/v1.19/push-gateway-api/#post_matrixpushv1notify).
    - `url` string, uri: Required if `kind` is `http`. The URL to use for sending notifications. MUST be an HTTPS URL with a path of `/_matrix/push/v1/notify`.
  - `device_display_name` string: Required if `kind` is not `null`. A string that will allow the user to identify what device owns this pusher.
  - `kind` string, nullable, required: The kind of pusher to configure. `"http"` makes a pusher that sends HTTP pokes. `"email"` makes a pusher that emails the user with unread notifications. `null` deletes the pusher.
  - `lang` string: Required if `kind` is not `null`. The preferred language for receiving notifications (e.g. 'en' or 'en-US').
  - `profile_tag` string: This string determines which set of device specific rules this pusher executes.
  - `pushkey` string, required: This is a unique identifier for this pusher. The value you should use for this is the routing or destination address information for the notification, for example, the APNS token for APNS or the Registration ID for GCM. If your notification client has no such concept, use any unique identifier. Max length, 512 bytes. If the `kind` is `"email"`, this is the email address to send notifications to.

## Response `200`

The pusher was set.

- object: An empty object.

## Other responses

- `400`: One or more of the pusher values were invalid.
- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)