mailbox.send

The mailbox.send command enables you to send a command to a thing or a connection in the platform. The most common use case is sending commands to things by addressing the thingKey of the device. Alternatively, you can send commands directly to a session (that represents a specific connection from an application/user to the portal). This is typically used for asynchronous exchanges where an application sends a command to a device, and the device needs to respond with multiple responses.

TR50 Request

// Send a command to a thing
{
  "cmd": {
    "command": "mailbox.send",
    "params": {
      "thingKey": "52ebe698f2057f19980001e1",
      "command": "COMMAND",
      "params": {
        ...
      },
      "singleton": false,
      "ackTimeout": 30
    }
  }
}

If ackTimeout is not set in the mailbox.send then the Default method timeout is used as the ackTimeout. The Default method timeout (defaultAckTimeout)is set while creating the Thing Definition. For more information, see thing_def.create.

Request Parameters

Name	Type	Required	Description
thingKey	String		The thing that should execute the command.
command	String	Yes	The command to execute.
params	Object		The parameters for the command.
ackTimeout	Integer		The acknowledgment timeout. The "ackTimeout" specifies how long the sender is willing to wait for a reply from the receiving client.
ttl	Integer		The lifetime of the message. "ttl" of -1 holds the message "forever" until it is delivered to a client.
singleton	Boolean		It ensures that if multiple mailbox messages are sent with the same command and if `singleton=true` then only one of the commands will get executed

If the command is sent successfully a success message and the command results are returned. Otherwise, an error and error message will be returned.

TR50 Response

{
  "cmd": {
    "success": true,
    "params": {
      "key1": "value string",
      "key2": false,
      "key3": 42
    }
  }
}

Response Parameters

An object of results. Actual object structure will vary according to the command executed.

C API

// basic API
int tr50_mailbox_send(void *tr50, const char *mailbox_cmd, JSON* params);
 
// extended API
int tr50_mailbox_send_ex(void *tr50, const char *command, JSON* req_params, void* optional_params, void** reply_params, char** error_msg);

JAVA API

// Synchronous
int send(String thingKey, String command, DwOpenCommandParam params, Integer ackTimeout, Boolean singleton, String sessionId, Object response);
 
// Asynchronous
int send(String thingKey, String command, DwOpenCommandParam params, Integer ackTimeout, Boolean singleton, String sessionId, DwOpenReceiveActionListener recv, Object response);

Response Objects: StringReply, DwOpenResponse, DwOpenMailboxSend