Tendrl

Docs / Contact / sdks/javascript/api-reference

JavaScript SDK: API Reference

TendrlClient

new TendrlClient(options)

Create a new client instance. See Configuration for all options.

javascript

const client = new TendrlClient({ apiKey: 'your_key' });

client.start()

Start the client. Begins background message polling (if a callback is set) and batch processing.

client.stop()

Stop the client. Updates entity status to offline and clears intervals.

Publishing

client.publish(data, tags?, entity?, waitResponse?)

Publish a message to Contact.

Parameter Type Default Description
data any — JSON-serializable data
tags string[] [] Tags for routing to flows (max 10)
entity string null Target entity. null sends to self.
waitResponse boolean false true = send immediately and await response
javascript

client.publish({ temp: 23.5 }, ['sensor']);
client.publish({ cmd: 'reboot' }, ['admin'], 'device-001');
await client.publish({ alert: 'high' }, ['alert'], null, true);

Message Receiving

Poll for incoming messages in managed mode. Route by tag or msg_type with client.on():

javascript

client.on({ tag: 'ai-response' }, (message) => {
    console.log(message.data);
});

client.on({ msgType, tag, tags, tagsAll }, handler)

Register a route handler. All specified criteria must match (AND semantics). Routes are checked in registration order; first match wins.

Option Type Description
msgType string Match this message type
tag string Match a single tag
tags string[] Match if message has any listed tag
tagsAll string[] Match if message has all listed tags

client.onDefault(handler)

Catch-all handler when no route matches.

client.setMessageCallback(fn)

Catch-all fallback when no route or onDefault handler matches. The callback receives:

javascript

{
    msg_type: 'publish',
    source: 'account:region:entity:name',
    timestamp: '2025-01-15T10:30:00Z',
    data: { ... },
    tags: ['tag1']
}

Return true to acknowledge.

client.setMessageCheckRate(ms)

Set polling interval in milliseconds.

client.setMessageCheckLimit(n)

Set maximum messages retrieved per poll.

client.checkMessages(limit?)

Manually poll for incoming messages. Triggers the callback for each message.

State Receiving

Poll the state table at the same interval as messages (checkMsgRate). Handlers fire when the table changes:

javascript

client.onState((state) => {
    if (state.status === 'needs_maintenance') {
        console.log('Maintenance required');
    }
});

client.onState(handler)

Register a handler for remote state table changes detected by polling.

client.setStateCallback(fn)

Catch-all fallback when onState is not used.

client.checkState()

Manually poll the state table and dispatch handlers if it changed.

File Transfer

Send and receive files between entities. Files are malware-scanned by Surface before delivery and deleted once downloaded. See File Transfer.

client.sendFile(file, { filename?, dest?, tags? })

Upload a File/Blob/bytes to an entity (dest) or tag-routed automation (tags). Resolves to the response object (transfer_id, status, …) or null on failure.

javascript

const res = await client.sendFile(file, { dest: "gateway-01" });

client.checkFiles(limit = 50)

List clean files addressed to this entity.

client.downloadFile(transferId)

Download a clean file's bytes as an ArrayBuffer (consumes delete-on-download files).

State Table

client.getState() → Promise<object>

Retrieve the entity's current state table.

client.updateState(data, tags?) → Promise<boolean>

Merge data into the state table (PATCH).

client.replaceState(data, tags?) → Promise<boolean>

Replace the entire state table (PUT).

Heartbeat

client.sendHeartbeat(data) → Promise

Send system metrics to Contact.

Field Type Description
mem_free number Free memory in bytes
mem_total number Total memory in bytes
disk_free number Free disk space in bytes
disk_size number Total disk space in bytes

Connectivity

client.checkConnectionState() → Promise<boolean>

Check if the Contact API is reachable. Results are cached for 30 seconds.

React Hook

useTendrlClient(options)

React hook that manages client lifecycle automatically.

javascript


const {
    client,              // TendrlClient instance
    isConnected,         // boolean - reactive connection state
    publish,             // (data, tags, entity, wait) => void
    checkMessages,       // (limit) => void
    setMessageCallback,  // (fn) => void
    setMessageCheckRate, // (ms) => void
    setMessageCheckLimit,// (n) => void
    sendHeartbeat        // (data) => Promise
} = useTendrlClient({
    apiKey: 'your_key',
    onMessage: (msg) => { ... },
    // ...all TendrlClient options
});

The hook:

← Back to Contact docs