# whatsapp-autoresponder

Adopt this skill: https://proskills.md/skills/other/initechsoftware-openclaw-whatsapp-skills-skills-whatsapp-autoresponder

Page: https://proskills.md/skills/other/initechsoftware-openclaw-whatsapp-skills-skills-whatsapp-autoresponder
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/whatsapp-autoresponder/SKILL.md
size: 4600
upstream: https://github.com/initechsoftware/openclaw-whatsapp-skills/blob/main/skills/whatsapp-autoresponder/SKILL.md

````text
---
name: whatsapp-autoresponder
description: |
  Reply to an inbound WhatsApp message routed through the TimelinesAI webhook.
  Triggers on payloads shaped like {chat_id, text, sender_phone, sender_name}
  from the TimelinesAI webhook receiver. Verifies the chat belongs to the
  allowed sender JID before sending, and honors stop-reply labels
  (needs-human / escalate / pause-bot) so a human can pause the bot on any
  chat with one tag.
env:
  TIMELINES_AI_API_KEY: required
  ALLOWED_SENDER_JID: required
---

# WhatsApp autoresponder

You receive an invocation from the webhook receiver with a payload like:

```json
{
  "chat_id": 12345678,
  "text": "do you support Shopify?",
  "sender_phone": "+15550200",
  "sender_name": "Customer",
  "message_uid": "c9054496-c8d2-4596-9786-aa872da4b743",
  "allowed_sender_jid": "15550100@s.whatsapp.net"
}
```

Your job: compose a reply to the incoming `text` and send it back into the same chat. But before you send, check two guardrails.

## Step 1 — Verify chat ownership (multi-number safety)

If your workspace has more than one WhatsApp number connected, the chat's `whatsapp_account_id` determines who the reply will come from. You must confirm that matches the sender JID this skill is allowed to speak as, or you will leak persona — replying to a sales chat from the support number is a hard mistake to explain.

```bash
CHAT_JID=$(curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  "https://app.timelines.ai/integrations/api/chats/$CHAT_ID" \
  | jq -r '.data.whatsapp_account_id')

if [ "$CHAT_JID" != "$ALLOWED_SENDER_JID" ]; then
  echo "chat $CHAT_ID owned by $CHAT_JID, not $ALLOWED_SENDER_JID — skipping"
  exit 0
fi
```

Single-number workspaces can skip this check — there's only one possible sender.

## Step 2 — Check for stop-reply labels

If a human teammate has tagged the chat with `needs-human`, `escalate`, or `pause-bot`, the bot must exit silently without sending anything. This is how humans take over without confusing the customer with an overlapping agent reply.

```bash
LABELS=$(curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  "https://app.timelines.ai/integrations/api/chats/$CHAT_ID/labels" \
  | jq -r '.data.labels[]? // empty')

case "$LABELS" in
  *needs-human*|*escalate*|*pause-bot*)
    echo "stop-reply label present — exiting without reply"
    exit 0
    ;;
esac
```

## Step 3 — Reply

Compose your reply text (one short paragraph; if you need conversation history for context, fetch it with `GET /chats/$CHAT_ID/messages?limit=20`). Write the payload to a file with explicit UTF-8 encoding — never use inline `-d "..."` with anything that might contain em-dashes, smart quotes, or emoji, because shell encoding will mangle the bytes and the JSON parser will reject the whole request.

```bash
REPLY_TEXT="Your composed reply here."

python3 -c "import json,sys; json.dump({'text': sys.argv[1]}, open('/tmp/wa_reply.json','w'), ensure_ascii=False)" \
  "$REPLY_TEXT"

curl -sS -X POST \
  -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/wa_reply.json \
  "https://app.timelines.ai/integrations/api/chats/$CHAT_ID/messages"
```

A successful send returns:

```json
{"status":"ok","data":{"message_uid":"<new-uid>"}}
```

Capture that `message_uid` and return it in your skill output — downstream skills can use it to poll delivery status via `GET /messages/{uid}/status_history`.

## Error responses to watch for

- `{"status":"error","message":"Bad JSON format: 'utf-8' codec can't decode byte 0x97..."}` — your payload isn't valid UTF-8. Go back to step 3 and make sure you're writing the file with `ensure_ascii=False` and reading it with `--data-binary`.
- `{"status":"error","message":"Not authenticated"}` — the token is wrong or missing. Check `$TIMELINES_AI_API_KEY`.
- `{"status":"error","message":"Whatsapp chat_id ... not found"}` — either the chat doesn't exist, or your token's workspace doesn't own it. Either way, don't retry.
- An HTML 404 page instead of JSON — you probably have a trailing slash on the path. Remove it.

## What this skill deliberately does NOT do

- It does not reply if the chat is owned by a different WhatsApp number in a multi-number workspace.
- It does not reply if any stop-reply label is present.
- It does not retry on failure — if the send 5xx's, let the caller decide.
- It does not send unsolicited first-touch messages to people who haven't messaged you — for outbound, use the `whatsapp-send` skill and read the compliance notes first.
````

## File: README.md
upstream: https://github.com/initechsoftware/openclaw-whatsapp-skills/blob/main/README.md

````text
# whatsapp-autoresponder

Reply to every inbound WhatsApp message that arrives through the TimelinesAI webhook, with two hard guardrails: only reply if the chat belongs to your allowed sender JID, and only reply if there are no stop-reply labels on the chat.

## When to use

- You want a 24/7 autoresponder for customer questions on WhatsApp.
- You want an after-hours responder that answers FAQs during off-hours and lets humans handle the rest during business hours.
- You're running an FAQ bot that can hand off to a teammate by adding a label.

## How it's wired

```
Customer sends a message
    ↓
TimelinesAI fires "message:received:new" webhook to your receiver
    ↓
Receiver (examples/vercel-webhook-receiver/) POSTs to your OpenClaw host
    ↓
OpenClaw invokes whatsapp-autoresponder with the payload
    ↓
Skill: (1) verify chat JID (2) check stop labels (3) compose + send reply
    ↓
Customer sees the reply in the same thread
```

## Environment

- `TIMELINES_AI_API_KEY` — Bearer token from `app.timelines.ai → Integrations → Public API`.
- `ALLOWED_SENDER_JID` — the WhatsApp JID this skill is allowed to reply from, e.g. `15550100@s.whatsapp.net`. Required if your workspace has multiple numbers connected.

## Install

Clone this repo into your OpenClaw workspace and symlink the skill directory into your OpenClaw `skills/` path:

```bash
cd ~/.openclaw/workspace
git clone https://github.com/InitechSoftware/openclaw-whatsapp-skills.git
ln -s $(pwd)/openclaw-whatsapp-skills/skills/whatsapp-autoresponder ~/.openclaw/skills/
```

Then restart OpenClaw or trigger a skill reload so the skill description gets indexed for intent routing.

## Stop-reply labels

The skill looks for these labels on the chat and exits silently if any are present:

- `needs-human` — FAQ handler couldn't answer; a teammate should take over
- `escalate` — the customer explicitly asked for a human
- `pause-bot` — generic pause, human teammate can set this manually

This is the cleanest handoff pattern: humans don't need to unplug the bot, they just tag the chat. Clearing the tag resumes the bot.

## Composing replies — implementation detail

For the simplest version (single canned reply for every message), hard-code the text in step 3 of `SKILL.md`. For an FAQ-matching version, fetch the last ~20 messages from the chat for context and let OpenClaw's reasoning pick the right response. For an LLM-backed full autoresponder, pipe the full history into the model and let it compose.

The skill is the same in all three cases — only step 3's "compose the reply text" line changes.

## Testing

```bash
# Dry-run: invoke the skill with a synthetic payload without actually sending
export TIMELINES_AI_API_KEY=sk-...
export ALLOWED_SENDER_JID=15550100@s.whatsapp.net
export CHAT_ID=12345678
export DRY_RUN=1

# Then watch the skill output for the verify + label steps without the send
```

(`DRY_RUN` isn't built into the SKILL.md by default — add it as a conditional around the final `curl` if you want a safer test harness.)

## What it doesn't do

- Doesn't initiate conversations (use `whatsapp-send` for that, and read [`../../docs/compliance.md`](../../docs/compliance.md) first).
- Doesn't retry on failure — if a send returns 5xx, let the caller decide.
- Doesn't deduplicate — if TimelinesAI retries the webhook, the skill runs twice. Use `message_uid` in your receiver to deduplicate before invoking the skill.
````
