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's Operation dropdown offers two operations: send (default) and update_state. Sending files is not an Operation of this connector — it uses a separate node type (Contact: Send File, added from the node palette), documented under Sending files below.

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.

---

Fetching files (Contact: Fetch File node)#

Fetching a tag-routed file's bytes is a separate node type — Contact: Fetch File (platform.contact.fetch_file), added from the node palette. It reads a file Contact routed to your workflow and returns the bytes base64-encoded, typically to chain into a Contact: Send File node, an HTTP upload, or a Surface scan. It authenticates with the platform's internal token, so it needs no entity API key.

Single-consume: a successful fetch reclaims the file and its sender's storage. Fetch each routed file exactly once.

Node Configuration#

On success the node adds the file bytes as content_base64 (plus size) to the output — which is exactly what a downstream Contact: Send File node reads by default.

Fetch File Example#

Fetch a file the trigger routed in, ready to hand to a Send File node downstream:

{
  "transfer_id": "{{ payload.data.transfer_id }}",
  "size": "{{ payload.data.size }}",
  "max_inline_bytes": 10485760
}

---

Sending files (Contact: Send File node)#

Sending a file is a separate node type — Contact: Send File (platform.contact.send_file), added from the node palette — not an operation of this connector. It sends 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):

{
  "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