Docs / Strand / connectors/contact-message

Contact Entity

Direction: Read/Write | Type: contact.platform

Send messages and files to Contact entities and update entity state tables from your Strand workflows.

The contact.platform connector communicates with the Contact platform internally; no external access or public URLs are required.

Connector Setup

Create a Contact Entity Message connector from the Connectors page.

The API key is encrypted at rest.

Tip: Store entity API keys in the Strand vault and reference them with {{ vault.contact_api_key }} in the connector configuration to keep credentials centralized.

Operations

The connector supports three operations, selected via the Operation dropdown on the node configuration panel.

send (default)

Send a message to a Contact entity. This is the default operation if none is specified.

Node Configuration

Data is the message payload:

{
  "temperature": "{{ payload.temp }}",
  "status": "processed",
  "source": "{{ initial.meta.workflow_id }}"
}

Destination supports two formats:

• Entity name: for same-account delivery (e.g., my-sensor). The entity is looked up by name within the sending entity's account.
• Full resource path: for cross-account delivery (e.g., 12345:us-east-1:entity:my-sensor).

If omitted, the message is published without a specific destination.

Tags are used for routing and triggering Contact flows:

["alert", "high-priority", "sensor-data"]

send Example

{
  "operation": "send",
  "data": {
    "temperature": "{{ payload.temp }}",
    "humidity": "{{ payload.humidity }}",
    "timestamp": "{{ payload.ts }}"
  },
  "dest": "sensor-gateway",
  "tags": ["sensor-data", "building-a"]
}

send Permissions

The entity whose API key is used must have a role with the entity:WriteMessages action. If a destination is specified, the entity also needs entity:WriteMessages permission scoped to the destination's resource path.

---

send_file

Send a file into Contact (file transfer). The file bytes are supplied base64-encoded, typically chained from a Contact: Fetch File node or an HTTP download. The sending entity pays storage until the file is consumed.

Node Configuration

Set exactly one delivery target: dest, tags, or kind: clip. See Delivery modes for how each routes.

send_file Example

Forward a fetched file to a specific device (direct delivery):

{
  "operation": "send_file",
  "content_base64": "{{ payload.content_base64 }}",
  "file_name": "{{ payload.file_name }}",
  "content_type": "{{ payload.content_type }}",
  "dest": "gateway-01"
}

On success the node adds transfer_id, sha256, size, and mode to the output.

send_file Permissions

The entity whose API key is used must have a role with the entity:SendFiles action. For direct, group, and cross-account delivery the entity also needs entity:SendFiles scoped to the destination's resource path.

---

update_state

Update an entity's status table. The status table is a JSON key-value store attached to each Contact entity, useful for tracking device state, configuration, or metadata.

Node Configuration

update_state Example

Merge new sensor readings into an entity's state table, preserving existing keys:

{
  "operation": "update_state",
  "entity": "{{ initial.meta.entity_name }}",
  "state": {
    "last_temperature": "{{ payload.temp }}",
    "last_seen": "{{ payload.timestamp }}",
    "firmware": "{{ payload.fw_version }}"
  },
  "replace": "false"
}

Replace the entire state table (all previous keys are removed):

{
  "operation": "update_state",
  "entity": "thermostat-01",
  "state": {
    "mode": "cooling",
    "target_temp": 22,
    "updated_by": "{{ initial.meta.workflow_id }}"
  },
  "replace": "true"
}

Important: When replace is "true", any keys not included in state will be deleted from the entity's status table. Use "false" (the default) to safely merge updates.

update_state Permissions

The entity whose API key is used must have a role with the entity:UpdateEntityStatusTable action.

Errors

The connector translates Contact API responses into descriptive messages:

send Errors

send_file Errors

update_state Errors

Related

• Connector Output Structure
• Templating Guide

← Back to Strand docs