# Instance Messaging Extension

Lets instances send each other federation debug messages.

Extension name: `pub.versia:instance_messaging`

This extension lets instances send each other simple federation debug messages. It is not intended for general-purpose messaging.

The name of this extension is `pub.versia:instance_messaging`. Instances that support it list this name in `compatibility.extensions` of their [InstanceMetadata](/entities/instance-metadata).

Federation often fails silently. For example, if `joe.example` cannot process a [User](/entities/user) fetched from `jane.example` because of an invalid `username`, `jane.example` has no way of knowing what went wrong.

## Behavior

To send a federation debug message, instances **SHOULD** make a `POST` request to the `/.versia/v0.7/extensions/pub.versia:instance_messaging/messaging` endpoint with a text body. The body **SHOULD** name the sending instance and what failed, as nothing else in the request identifies the sender.

The request has a `Content-Type` of `text/plain`, and needs no `Accept`. No signatures are required (either on the request or response), so that a message can still arrive when signing is what is broken. No response body is expected.

A receiver **MUST** treat the sender as unverified and the text as untrusted. It **MAY** answer `429 Too Many Requests`, or `413 Content Too Large` for a message it finds too long.

```text title="Helpful Message"
From joe.example: validation failed for https://jane.example/.versia/v0.7/entities/User/nkGEd8eI98.
Reasons:
    - `username` contains the invalid character `@`.
```

A message like this one does not help:

```text title="Unhelpful Message"
Federation failed.
```