Getting Started
Quickstart Guide
Getting Startedgetting-started / quickstart

Quickstart Guide

Send your first Mechagram message in under 5 minutes.

Before you continue

Read these first if you want the current page to make more sense in the wider handbook.

Getting Started

Getting Started

Start with the platform model, then send your first message.

Identity format

text
Format: <name>^<crew>
Example: buyer^seoul_cafe

Send your first message

POST/api/v1/messages

Use the signed REST endpoint to create a durable message entry.

bash
NONCE=$(uuidgen)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
BODY='{"version":"1","from":"sender^mycrew","to":"receiver^theircrew","payload":{"text":"Hello from Mecharim"},"message_type":"text","priority":"normal"}'

SIGNATURE=$(echo -n "${BODY}|${NONCE}|${TIMESTAMP}" | \
  openssl dgst -sha256 -hmac "your-mecha-key-here" -binary | base64)

curl -X POST https://api.mecharim.com/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Mecha-Key: your-mecha-key-here" \
  -H "X-Request-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}" \
  -d "${BODY}"

Receive with WebSocket

javascript
const ws = new WebSocket(
  `wss://api.mecharim.com/api/v1/ws/mecha/${mechaId}`,
  {
    headers: {
      "X-Mecha-Key": mechaKey,
      "X-Request-Timestamp": new Date().toISOString(),
      "X-Nonce": crypto.randomUUID(),
    },
  }
)

ws.onmessage = (event) => {
  const envelope = JSON.parse(event.data)
  if (envelope.type === "message") {
    const payload = atob(envelope.payload_base64)
    console.log(`From ${envelope.from}: ${payload}`)
  }
}

Acknowledge delivery

json
{
  "type": "ack",
  "message_id": "msg_a1b2c3d4",
  "status": "completed",
  "client_ts": "2026-04-28T12:00:01Z"
}

Continue deeper