HTTP API Messages

Edit this page

You send messages to and from Things and Features through the HTTP API, enabling command-and-control communication with devices.

TL;DR: Send a POST to a Thing’s or Feature’s inbox to send it a message, or to its outbox to send a message from it. Use the timeout parameter to control how long Ditto waits for a response.

Tip: Check out the WebSocket Messages API if you also need to receive or reply to Messages.

Overview

The HTTP Messages API lets you send messages to and from Things and their Features. For the underlying concepts, see the Messages page. For full parameter details and response codes, see the HTTP API Documentation.

How it works

Messages flow through two paths:

Inbox – send a message to a Thing or Feature (the device receives it)
Outbox – send a message from a Thing or Feature (simulating device-originated messages)

When you send a message to a Thing’s inbox, Ditto routes it to the device. If the device responds, you receive the response as the HTTP response body. If the device does not respond in time, you get a 408 Request Timeout.

Examples

Note: Don’t forget to replace the Authorization header and the host when trying out the examples. Also make sure the Thing, you are sending Messages to, is existing.

Send a message to a Thing

Send a message with subject ask to the Thing org.eclipse.ditto:smartcoffee:

curl --request POST \
  --url http://localhost:8080/api/2/things/org.eclipse.ditto:smartcoffee/inbox/messages/ask \
  --header 'content-type: text/plain' \
  --header 'Authorization: Basic ZGl0dG86ZGl0dG8=' \
  --data 'Hey, how are you?'

If the device responds, you receive its reply as the HTTP response body.

Control the timeout

If you do not need a response (fire-and-forget), set timeout=0 to get an immediate 202 Accepted:

curl --request POST \
  --url http://localhost:8080/api/2/things/org.eclipse.ditto:smartcoffee/inbox/messages/ask?timeout=0 \
  --header 'content-type: text/plain' \
  --header 'Authorization: Basic ZGl0dG86ZGl0dG8=' \
  --data 'Hey, how are you?'

Tip: Use the timeout query parameter to specify what timeout you expect for your Messages. A timeout of zero will instantly return a response, whilst other positive values change how long Ditto will wait for an answer before responding to you.

Send a message to a Feature

Target a specific Feature by including its ID in the URL path:

curl --request POST \
 --url http://localhost:8080/api/2/things/org.eclipse.ditto:smartcoffee/features/water-tank/inbox/messages/action \
 --header 'content-type: text/plain' \
 --header 'Authorization: Basic ZGl0dG86ZGl0dG8=' \
 --data 'heatUp'

Send a message from a Thing

Replace inbox with outbox to send a message from the Thing:

curl --request POST \
  --url http://localhost:8080/api/2/things/org.eclipse.ditto:smartcoffee/outbox/messages/inform \
  --header 'correlation-id: an-unique-string-for-this-message' \
  --header 'content-type: text/plain' \
  --header 'Authorization: Basic ZGl0dG86ZGl0dG8=' \
  --data 'No one used me for half an hour now. I am going to shutdown soon.'