Messages between instances

States are values: they exist in the object tree, anyone can read them, and they remain. For many things, this is perfectly appropriate. For a task, however, it is not.

"Send this message via Telegram" isn't a value that's stored somewhere. It's a one-time instruction, often with several details and sometimes with a reply. That's what the message box is for.

Requirement

An instance can only receive messages if its adapter announces this. In theio-package.json :

"common": {
  "messagebox": true
}

This allows ioBroker to create the object for each instance.system.adapter.<name>.<nummer>.messagebox If the entry is missing, each entry disappears.sendTo Without a trace. That's the most common reason why messages seemingly don't arrive.

Send

this.sendTo('telegram.0', 'send', { text: 'Waschmaschine fertig' });

The three pieces of information are always the same: to whom , which command , which payload . The payload is arbitrary, usually an object.

If a response is desired, a fourth parameter is appended:

this.sendTo('sql.0', 'getHistory', {
    id: 'javascript.0.Temperatur',
    options: { start: Date.now() - 3600000, aggregate: 'average' }
}, result => {
    this.log.info(`${result.result.length} Werte erhalten`);
});

The callback will be asynchronous. Those who don't want to wait indefinitely should specify a deadline:

this.sendTo('sql.0', 'getHistory', payload, callback, { timeout: 5000 });

Without a deadline, the request will likely remain pending indefinitely if the other party does not respond.

From a script in the JavaScript adapter, the same call is simply called...sendTo(...) , withoutthis It's the same mechanism.

Received

The message is displayed in the adapter.onMessage The object that arrives has four fields:

onMessage(obj) {
    if (!obj) {
        return;
    }

    switch (obj.command) {
        case 'send':
            this.sendMessage(obj.message);
            if (obj.callback) {
                this.sendTo(obj.from, obj.command, { sent: true }, obj.callback);
            }
            break;

        default:
            this.log.warn(`Unbekannter Befehl: ${obj.command}`);
            if (obj.callback) {
                this.sendTo(obj.from, obj.command, { error: 'unknown command' }, obj.callback);
            }
            break;
    }
}

Two things about this are important.

Always reply whenobj.callback The deadline is set. Even in case of an error. Otherwise, the sender is stuck within their deadline, and if they haven't set one, then it's forever.

obj.fromandobj.callback Return it unchanged. The answer will find its way based on these two pieces of information. Anyone who tries to assemble them themselves will send a message into the void.

What can be done with it

Orders to other adapters. The classic case: notification adapters such astelegram ,pushover oremail They only accept their orders in this way.

Retrieving values from a database.getHistory tohistory ,sql orinfluxdb The prerequisite iscommon.getHistory: true at the receiving adapter. See data recording .

Consult your own configuration interface. The configuration page in the admin area cansendTo Send the data to your own instance, for example to retrieve a list of detected devices or to validate an input. This is the clean way to do it when the validation requires knowledge that only the adapter code possesses.

The instance must be running for this to work. A stopped instance has no message tray that anyone is managing. The configuration interface should detect this and display a clear message instead of simply running into a time limit.

To the host instead of an instance

sendToHost This doesn't connect to an instance, but to the JS controller of a host. This allows you to retrieve system information and issue administrative commands, such as listing instances or reading log files. This is the method the administrator uses.

right

Messages require a separate permission. This is listed in the user management section.sendTo This is a separate permission from read and write permissions on objects. A user without this permission cannot submit any commands, even if they have read permissions for everything else. See Users and Permissions .