whatsapp-gotify-relay

Use when operating or extending this WhatsApp Gotify relay as the bridge to OpenClaw. Prefer Unix tools for Docker, logs, Gotify queue checks, webhook valida...

Security Scan

The skill is an instruction-only operator guide for a WhatsApp↔Gotify relay; its required tools and actions match the described purpose, with only minor documentation inconsistencies to fix.

Purpose & Capability

Name/description, required binaries (rg, sed, curl, docker, npm, git), and the runtime actions (docker compose, curl, npm test, log inspection) align with operating and testing a Gotify↔WhatsApp relay repository.

Instruction Scope

SKILL.md confines itself to repo operations, logs, smoke tests, and curl interactions with Gotify/webhook endpoints. It does not instruct reading unrelated system files or harvesting credentials. Note: the document lists runtime env vars and uses tokens in curl examples—expected for this bridge, but the skill does not declare or require those env vars at install time.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is written to disk or downloaded by the skill itself.

Credentials

SKILL.md documents several service tokens and bearer secrets (Gotify tokens, WEBHOOK_BEARER_TOKEN) which are proportional to operating a relay. Registry metadata, however, declares no required env vars — this is not a security problem but means operators must supply tokens manually. There is a minor naming inconsistency between GOTIFY_OUTBOX_TOKEN and GOTIFY_OUTBOX_APP_TOKEN in examples that should be clarified to avoid accidental token exposure or misconfiguration.

Persistence & Privilege

always is false and the skill is user-invocable. It does not request persistent installation or modification of other skills/configs.

Assessment

This skill is an operator handbook for a WhatsApp↔Gotify relay and appears coherent with that purpose. Before using it: (1) verify environment variable names in your repository (.env.example/README) — the SKILL.md uses both GOTIFY_OUTBOX_TOKEN and GOTIFY_OUTBOX_APP_TOKEN in different places, which is likely a typo and could lead you to paste the wrong token; (2) never paste production tokens into public channels or logs when running the example curl commands; (3) confirm GOTIFY_BASE_URL and webhook endpoints point to services you control; and (4) treat GOTIFY and webhook tokens as sensitive secrets — store them securely and rotate if accidentally exposed. If you need the skill to be more prescriptive about required env vars, ask the author to align SKILL.md examples with .env.example to remove ambiguity.

OpenClaw

Use this skill when working on this repository as the WhatsApp bridge for OpenClaw.

Purpose

This project sits between WhatsApp and OpenClaw.

It does two directions of communication:

1. OpenClaw sends outbound WhatsApp jobs through Gotify.
2. The relay sends inbound WhatsApp events and connection status back to OpenClaw through webhooks.

Bridge model

Outbound path

OpenClaw posts JSON into the Gotify outbox application:

{
  "type": "send",
  "to": "[phone]",
  "text": "hello from openclaw"
}

The relay polls that outbox, sends to WhatsApp, deletes the queue item on success, and emits a send_result.

Inbound path

OpenClaw receives webhook JSON from the relay.

Webhook event types:

• conversation
• send_result
• status

Only meaningful WhatsApp activity should produce conversation events. History sync, protocol chatter, and other Baileys internals should stay filtered out.

Payload shape

The relay should keep payloads flat and readable.

Conversation

{
  "type": "conversation",
  "relay": "whatsapp-gotify-relay",
  "direction": "inbound",
  "jid": "[e-mail]",
  "senderJid": "[e-mail]",
  "pushName": "John",
  "timestamp": 1776948451,
  "messageId": "ABC123",
  "text": "hello",
  "contentType": "text"
}

Send result

{
  "type": "send_result",
  "relay": "whatsapp-gotify-relay",
  "status": "sent",
  "requestId": 5544,
  "to": "[e-mail]",
  "messageId": "3EB0...",
  "error": null,
  "timestamp": "2026-04-23T12:48:56.415Z"
}

Status

{
  "type": "status",
  "relay": "whatsapp-gotify-relay",
  "connection": "open",
  "phase": "connected",
  "qr": null,
  "statusCode": null,
  "details": null,
  "timestamp": "2026-04-23T12:48:56.415Z"
}

If WhatsApp remains disconnected, the relay sends a status reminder every 3 hours by default.

Public relay env vars

The relay runtime env surface is:

• PORT
• APP_LOG_LEVEL
• WHATSAPP_AUTH_DIR
• WHATSAPP_PAIRING_NUMBER
• WHATSAPP_SYNC_FULL_HISTORY
• GOTIFY_BASE_URL
• GOTIFY_EVENTS_APP_TOKEN
• GOTIFY_OUTBOX_TOKEN
• GOTIFY_OUTBOX_APPLICATION_ID
• GOTIFY_POLL_INTERVAL_MS
• GOTIFY_EVENTS_PRIORITY
• GOTIFY_RESULTS_PRIORITY
• WEBHOOK_URL
• WEBHOOK_BEARER_TOKEN
• WEBHOOK_TIMEOUT_MS
• WEBHOOK_DISCONNECTED_INTERVAL_MS
• RELAY_NAME

OpenClaw-side env concepts

On the OpenClaw side, the important configuration concepts are:

• Gotify base URL
• Gotify outbox application id
• Gotify outbox write token
• webhook shared secret or bearer token expected from the relay
• relay name if multiple relays exist

Keep the names OpenClaw already uses if they exist. Do not rename OpenClaw env vars just to match the relay.

Preferred tools

Prefer Unix tools and simple shell commands:

• rg
• sed -n
• npm test
• docker compose ps
• docker compose logs --tail=... connector
• docker compose up -d --build connector
• curl
• git status --short

Common operations

Run tests

npm test

Rebuild the relay

docker compose up -d --build connector

Follow relay logs

docker compose logs -f connector

Inspect the outbox queue

curl -sS "${GOTIFY_BASE_URL}/application/${GOTIFY_OUTBOX_APPLICATION_ID}/message?token=${GOTIFY_OUTBOX_TOKEN}&limit=10"

Post a manual outbox send

curl -sS \
  -H 'Content-Type: application/json' \
  -d '{"title":"smoke-test","message":"{\"type\":\"send\",\"to\":\"447550002572\",\"text\":\"smoke test\"}","priority":5}' \
  "${GOTIFY_BASE_URL}/message?token=${GOTIFY_OUTBOX_APP_TOKEN}"

GOTIFY_OUTBOX_APP_TOKEN is an operator-side token for manually writing to the outbox app. It is not required by the relay runtime.

Guardrails

• Keep Gotify and webhook payloads lean.
• Do not dump raw Baileys payloads into Gotify.
• Keep webhook and Gotify contracts aligned.
• Update .env.example, README.md, and tests together when the contract changes.