Send Message

POST /messages

Sends a message to a recipient.

Plugin-originated dispatch errors use the canonical plugin dispatch error contract: type, family, code, message, and optional typed details. Fire-and-forget requests can only return plugin errors detected before the request is accepted. Synchronous requests can also map a correlated portos/errorResponse plugin response into the HTTP error statuses below.

Required scope

message:send

Request body

Fields

targetCreateMessageTargetRequired

The endpoint, system, plugin or group a message is addressed to.

message151 variantsRequired

A capability message to send to an endpoint: exactly one of the inbound capability messages. The header namespace, name and version select the variant and the body schema.

headerMessageHeaderRequired: Identifies this capability message.
bodyobjectRequired: Ask the device to report its current air quality reading.
correlationTokenstring: Token used for correlating related messages

responseTypestring

How to handle the request. AUTO resolves the actual selected route's current plugin declaration: synchronous operations wait for a correlated response; asynchronous and fire-and-forget operations return dispatch acceptance without claiming device execution. Legacy integrations retain synchronous behavior in AUTO mode. Omission retains the existing FIRE_FORGET default.

POST /messages: application/json request body: possible enum values for responseType
Value	Meaning
`SYNC`	—
`FIRE_FORGET`	—
`AUTO`	Select the operating mode automatically.

Returns

200

Request accepted; an asynchronous acknowledgment may have an empty messageId and no message. Verify device state separately.

Fields

messageIdstringRequired

Identifies the unary response message when one is returned. An accepted asynchronous request can return an empty string with no message. This field does not provide a durable dispatch receipt, retry deduplication or proof of observed device state.

message56 variants

The message that was responded with when there was a unary message response, exactly one of the outbound capability messages. A synchronous send can return one; an acknowledgment with no message back leaves this empty. The header namespace, name and version select the variant and the body schema.

headerMessageHeaderRequired: Identifies this capability message.
bodyAuthorizationInterfaceAuthorizationEstablishedMessageRequired: The authorization established message is sent to a plugin to indicate that the plugin has been installed and authorized for a principal
correlationTokenstring: Token used for correlating related messages

Errors

400 INVALID_VALUE

Invalid request payload or plugin dispatch request error

Check the request fields and any validation details, then correct the payload.

Example details

{
  "providerCode": "provider-invalid-speed",
  "parameter": "speed",
  "actual": "storm"
}

401 AUTHORIZATION_CREDENTIAL_EXPIRED

Plugin authorization credential is invalid or expired

Re-link the plugin to renew its provider credentials, then retry.

Example details

{
  "providerCode": "provider-token-expired"
}

403 INSUFFICIENT_PERMISSIONS

Plugin provider denied the requested operation

Check the linked account and its permissions for the device or resource.

Example details

{
  "providerCode": "provider-scope-missing"
}

404 NOT_FOUND

Target endpoint or plugin route was not found

Verify the target identifier and that its endpoint or plugin route still exists.

409 NOT_SUPPORTED_IN_CURRENT_MODE

Endpoint state conflicts with the requested message

Check the device’s current mode or state. Retry only after the conflict is resolved.

Example details

{
  "providerCode": "device-mode-conflict",
  "currentMode": "eco"
}

422 VALUE_OUT_OF_RANGE

Plugin rejected a semantically invalid message value

Correct the rejected value using the constraints in the error details or request schema.

Example details

{
  "providerCode": "brightness-out-of-range",
  "parameter": "brightness",
  "minimum": 1,
  "maximum": 100,
  "actual": "150"
}

423 ENDPOINT_UNREACHABLE

Endpoint is unavailable, unreachable, locked, or low power

Check device connectivity, power, and lock state before retrying.

Example details

{
  "providerCode": "device-offline",
  "pluginId": "port1.plugin.hue",
  "pluginRouteId": "hue-device-42"
}

429 RATE_LIMIT_EXCEEDED

Plugin provider rate limit exceeded

Wait for Retry-After or details.retryAfterSeconds when supplied; otherwise use backoff.

Example details

{
  "providerCode": "provider-rate-limit",
  "retryAfterSeconds": 60
}

500 INTERNAL

Internal server error

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.

502 PROVIDER_INTERNAL_ERROR

Plugin provider returned an invalid or internal error response

Check provider availability. Retry with backoff only when the operation is safe to repeat.

Example details

{
  "providerCode": "provider-internal-error"
}

503 PROVIDER_SERVICE_UNAVAILABLE

Plugin provider or bridge is unavailable

Wait for the provider or bridge to recover, then retry safely with backoff.

Example details

{
  "providerCode": "vendor-outage"
}

504 PROVIDER_TIMEOUT

Plugin provider timed out

Check whether the command completed before resending it; a timeout can leave the result uncertain.

Example details

{
  "providerCode": "provider-timeout"
}

All documented plugin error types

Plugin error family	Representative types	HTTP status
`REQUEST_INVALID`	`INVALID_DIRECTIVE`, `INVALID_VALUE`	`400`
`REQUEST_INVALID`	`VALUE_OUT_OF_RANGE`	`422`
`AUTHENTICATION`	`AUTHORIZATION_CREDENTIAL_INVALID`, `AUTHORIZATION_CREDENTIAL_EXPIRED`	`401`
`PERMISSION`	`INSUFFICIENT_PERMISSIONS`, `CLOUD_CONTROL_DISABLED`	`403`
`ENDPOINT_NOT_FOUND`	no such endpoint or route	`404`
`ENDPOINT_STATE_CONFLICT`	`ENDPOINT_BUSY`, `NOT_SUPPORTED_IN_CURRENT_MODE`	`409`
`ENDPOINT_UNAVAILABLE`	`ENDPOINT_UNREACHABLE`, `ENDPOINT_LOW_POWER`	`423`
`RATE_LIMIT`	`RATE_LIMIT_EXCEEDED`	`429`
`PROVIDER_BAD_RESPONSE`	`PROVIDER_INTERNAL_ERROR`	`502`
`PROVIDER_UNAVAILABLE`	`BRIDGE_UNREACHABLE`, `PROVIDER_SERVICE_UNAVAILABLE`	`503`
`PROVIDER_TIMEOUT`	`PROVIDER_TIMEOUT`	`504`