Docs / Contact / messages/overview

Messages Overview

Messages are the core data units in Contact. Every piece of data that flows through the platform -- sensor readings, application events, state updates, heartbeats -- is a message sent by an authenticated entity.

Message Structure

A message sent to Contact has three top-level sections: the data payload, optional context for routing and loop-prevention metadata, and a msg_type that controls how the message is processed.

{
  "msg_type": "publish",
  "data": {
    "temperature": 23.5,
    "humidity": 65,
    "location": "Building A"
  },
  "context": {
    "tags": ["sensor-data", "building-a"]
  }
}

Fields

The data.data Nesting Pattern

When a message is returned from the API (for example, when reading message history or inside a Strand workflow trigger payload), the structure is wrapped in a message envelope:

{
  "message": {
    "data": {
      "temperature": 23.5,
      "humidity": 65
    },
    "msg_type": "publish",
    "source": "100:us-east:entity:weather-station-1",
    "timestamp": "2025-01-15T10:30:00Z"
  },
  "actionResults": [],
  "flowId": "6789abcdef012345"
}

If you are accessing message data inside a Strand workflow that was triggered by Contact, the payload arrives under data at the top level of the trigger event. Your original data object is nested as data.data (the outer data is the trigger event payload, the inner data is your message payload). Use a JSONPath like $.data.data.temperature in Strand node configs to reach your fields.

Message Types

The msg_type field controls how Contact processes a message:

{ "msg_type": "heartbeat", "mem_free": 81920, "mem_total": 262144, "disk_free": 1048576, "disk_size": 4194304, "sdk_version": "0.2.5" }

| state_new | Replaces the entity's entire state table with the contents of data. Not stored as a regular message unless triggerFlowsOnStateUpdate is enabled on the entity. | | state_update | Merges data into the entity's existing state table. Like state_new, only triggers flows when explicitly enabled. |

Sending Messages

Messages are sent via HTTP POST using an entity's API key for authentication:

curl -X POST https://your-host/api/entities/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ENTITY_API_KEY" \
  -d '{
    "msg_type": "publish",
    "data": {
      "temperature": 23.5,
      "humidity": 65
    },
    "context": {
      "tags": ["sensor-data"]
    }
  }'

Endpoints

Messages can also be sent over MQTT for real-time, low-latency use cases. See Protocols for MQTT details.

Receiving Messages

When a message targets an entity (via dest, or fanned out from a fanout), it is queued for that entity with a pending state. The recipient retrieves it by polling:

GET /api/entities/check_messages?limit=10

Authenticated with the recipient entity's API key. The response is an object with a messages array of pending messages (msg_type, data, tags, source, timestamp).

• limit (default 1) caps how many messages a single call returns.
• Delivery is once-only. Each returned message is atomically moved from pending to processed, so concurrent pollers never receive a duplicate. An empty array means nothing is pending.
• For real-time push instead of polling, use MQTT.

Stored messages are browsable on the Messages page, which is the quickest way to confirm what a device actually sent and how it was routed.

Expanding a message shows its delivery status, flow ID, and the payload as stored.

How Tags Drive Routing

Tags are the primary routing mechanism in Contact. When a message includes context.tags, Contact uses those tags to determine what happens next:

Entity sends message with tags: ["alert", "critical"]
          |
          v
   Contact receives message
          |
          +---> Connectors with tag "alert" or "critical" receive the payload
          |
          +---> Strand workflows exposed with tag "alert" or "critical" are triggered
          |
          v
   Flow document tracks delivery status per connector

Message Context

The context object carries routing and control metadata alongside a message:

The strandTriggerDepth field is incremented each time a Strand workflow sends a message back to Contact that re-triggers Strand. When the depth exceeds 3, Strand rejects the trigger to prevent infinite loops. See Strand Integration for the full loop-prevention mechanism.

Validation

When an entity's service has validation rules (dynamic actions) configured, incoming publish messages are validated against those rules before storage. Validation results are attached to the message as actionResults:

{
  "message": { ... },
  "actionResults": [
    {
      "name": "temperature_range",
      "valid": false,
      "ruleName": "range_check",
      "field": "temperature",
      "actual": 150,
      "expected": "between -50 and 100",
      "message": "Value out of range"
    }
  ]
}

Messages that fail validation are still stored but are marked with a validation_status of "failed". Validation failures can also inject additional tags (from the dynamic action definition), which allows you to route failed messages to different connectors or workflows.

Message Metadata

Each stored message carries metadata used for delivery tracking and flow association:

• senderPath -- Full resource path of the sending entity (e.g., 100:us-east:entity:sensor-1)
• recipientPath -- Resource path of the destination entity (for entity-to-entity messages)
• state -- Delivery state: "pending", "processed", or "failed"
• flowId -- Reference to the flow document created when connectors matched
• processedTime -- When the message was marked as processed

This metadata is visible in the API response for messages that have a destination entity.

Message Retention

Message retention depends on your account plan: 7 days on Free through 180 days on Pro. Each account's messages are stored in isolation from other accounts. See Data Retention for what the window covers, what is exempt from it, and what happens when you change plan.

Sending files

To send a file (rather than a JSON message) between entities, use File Transfer. Files are malware-scanned by Surface before delivery and are deleted once the recipient downloads them.

← Back to Contact docs