---
title: "External bus"
---

The frontend is able to set up a message bus with an external app that is embedding the Home Assistant frontend. This system is a generalization of the [external authentication](frontend/external-authentication.md), making it easier to add more commands in the future without extensive plumbing on either the app or frontend side.

## Message exchange

Just like external auth, message exchange is achieved by the external app making a JavaScript method available.

Messages are passed to the external app as serialized JSON objects. The function that will be called takes a single parameter: a string. The external app will have to process the message and deal with it accordingly (or ignore it).

On Android, your app needs to define the following method:

```ts
window.externalApp.externalBus(message: string)
```

On iOS, your app needs to define the following method:

```ts
window.webkit.messageHandlers.externalBus.postMessage(message: string);
```

To send messages to the frontend, serialize your message to JSON and call the following function from the external app:

```ts
window.externalBus(message: string)
```

## Message format

The message describes an action or a piece of information that the sender wants the receiver to do or know about. If it's an action, the sender will expect a response with the result of that action. A response to a command can either be successful or failed.

### Action and info message format

The format of a message that contains or provides information is the same. It contains an identifier, a type and an optional payload (depending on the type).

A result message will re-use the identifier in the response, to indicate to which action the response is related.

The basic format of a message is the following:

```ts
{
  id: number;
  type: string;
  payload?: unknown;
}
```

An example message:

```json
{
  "id": 5,
  "type": "config/get"
}
```

### Result message format

If the message was an action, the sender will expect a response with the result. The response is either success or failure.

The type of result depends on the type of the message that it is responding to. For example, if it is responding to `config/get`, the result should be an object describing the configuration.

Message formats:

```ts
interface SuccessResult {
  id: number;
  type: "result";
  success: true;
  result: unknown;
}

interface ErrorResult {
  id: number;
  type: "result";
  success: false;
  error: {
    code: string;
    message: string;
  };
}
```

## Supported messages

### Get external config

Available in: Home Assistant 0.92
Type: `config/get`
Direction: frontend to external app.
Expects answer: yes

Query the external app for the external configuration. The external configuration is used to customize the experience in the frontend.

Expected response payload:

```ts
{
  hasSettingsScreen: boolean;
  canWriteTag: boolean;
}
```

- `hasSettingsScreen` set to true if the external app will show a configuration screen when it receives the command `config_screen/show`. If so, a new option will be added to the sidebar to trigger the configuration screen.
- `canWriteTag` set to true if the external app is able to write tags and so can support the `tag/write` command.

### Show config screen `config_screen/show`

Available in: Home Assistant 0.92
Type: `config_screen/show`
Direction: frontend to external app.
Expect answer: no

Show the configuration screen of the external app.

### Connection status update `connection-status`

Available in: Home Assistant 0.92
Type: `connection-status`
Direction: frontend to external app.
Expect answer: no

Notify the external app if the frontend is connected to Home Assistant.

Payload structure:

```ts
{
  event: "connected" | "auth-invalid" | "disconnected";
}
```

### Trigger haptic `haptic`

Available in: Home Assistant 0.92
Type: `haptic`
Direction: frontend to external app.
Expect answer: no

Notify the external app to trigger haptic feedback.

Payload structure:

```ts
{
  hapticType:
    | "success"
    | "warning"
    | "failure"
    | "light"
    | "medium"
    | "heavy"
    | "selection";

}
```

### Write tag `tag/write`

Available in: Home Assistant 0.115
Type: `tag/write`
Direction: frontend to external app
Expect answer: yes

Tell the external app to open the UI to write to a tag. Name is the name of the tag as entered by the user. The name is `null` if no name has been set.

```ts
{
  tag: string;
  name: string | null;
}
```

Expected response payload is an empty object for now. We might add more later:

```ts
{}
```
