docs: autoRejectCall option and client.rejectCall() (unofficial-only)

Author: zeative

docs/content/api-reference.mdx

@@ -53,6 +53,7 @@ client.on('text', (ctx) => {
 | `pin(key, opts?)` | `(key, opts?: { duration?: number }): Promise<WAMessageKey>` | Pin a message (`duration` seconds; defaults 86400). |
 | `unpin(key)` | `(key): Promise<WAMessageKey>` | Unpin a message. |
 | `setDisappearing(jid, seconds)` | `(jid: string, seconds: number): Promise<void>` | Set the chat's disappearing-message timer. |
+| `rejectCall(call \| callId, from?)` | `(call: CallPayload \| string, from?: string): Promise<void>` | 🔗 Reject an incoming call. Accepts the `call-incoming` payload or raw `callId` + caller jid. Throws `UNSUPPORTED_ON_CLOUD` on the cloud provider. See [`autoRejectCall`](/configuration#autorejectcall). |
 | `lidToPn(lid)` | `(lid: string): Promise<string \| null>` | Resolve a `@lid` JID to its phone-number JID (`null` if unknown). Needs a connected socket. |
 | `pnToLid(pn)` | `(pn: string): Promise<string \| null>` | Resolve a phone-number JID to its `@lid` JID (`null` if unknown). Needs a connected socket. |
 | `broadcast(jids, build, opts?)` | `(jids: string[], build, opts?): Promise<BroadcastResult>` | Send to many recipients. See [Broadcast & Schedule](/automation). |

docs/content/configuration.mdx

@@ -42,6 +42,7 @@ const client = new Client({ sessionId: 'default' })
 | `operationGuard` | `OperationGuardOptions` | on (spaces group/community/newsletter ops) | Serializes and rate-limits sensitive group / community / newsletter operations per category so rapid bulk actions don't trip a ban. |
 | `presence` | `PresenceThrottleOptions` | on (drops duplicate presence) | Drops repeated presence updates (typing / recording / online) for the same chat within a short window. |
 | `scheduleRateLimitPerSec` | `number` | `1` (`0` disables) | Max scheduled messages dispatched per second, smoothing out a backlog of overdue jobs so they don't all fire at once. |
+| `autoRejectCall` | `boolean \| AutoRejectCallOptions` | `false` (off) | 🔗 **Unofficial only.** Auto-reject incoming WhatsApp calls. `true` rejects every call; pass an object for an allow-list and an `onReject` hook. |
 | `autoDelete` | `AutoDeleteOptions \| false` | `on (1-month retention)` | Periodically prune old messages from the local store. See [Auto-Delete](/auto-delete). |
 | `plugins` | `PluginsOptions` | `undefined` | Load and hot-reload plugins from a folder. See [Plugins](/plugins). |
 | `autoConnect` | `boolean` | `true` | When `true`, the constructor calls `connect()` on the next microtask. Set `false` to connect manually. |
@@ -527,6 +528,59 @@ const client = new Client({
   and `qrTimeout` are merely internal defaults you *can* override here if you really need to.
 </Callout>
 
+## `autoRejectCall`
+
+<Callout type="info">
+🔗 **Unofficial provider only.** The official [Cloud API](/official) has no call events — calling
+`client.rejectCall()` there throws `ZaileysProviderError('UNSUPPORTED_ON_CLOUD')`, and this option is
+never wired.
+</Callout>
+
+Auto-reject incoming voice/video calls. **Off by default** — rejecting calls is opt-in.
+
+```typescript
+// reject every incoming call
+const client = new Client({ autoRejectCall: true })
+```
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Turn auto-rejecting on. Passing `autoRejectCall: true` is shorthand for `{ enabled: true }`. |
+| `allow` | `string[] \| (jid: string) => boolean \| Promise<boolean>` | `undefined` | Callers to let ring. Array entries match the full jid **or** its digits. A predicate may be async. |
+| `onReject` | `(call) => void \| Promise<void>` | `undefined` | Runs **after** a call was successfully rejected — e.g. to tell the caller why. |
+
+```typescript
+const client = new Client({
+  autoRejectCall: {
+    enabled: true,
+    allow: ['628owner@s.whatsapp.net'],            // owner may still call
+    onReject: async (call) => {
+      await client.send(call.from).text('Maaf, nomor ini tidak menerima telepon 🙏')
+    },
+  },
+})
+```
+
+The `call` passed to `onReject` is the same `call-incoming` payload:
+`{ kind, callId, from, isGroup, isVideo, timestamp, status }` — so you can branch on `isVideo` /
+`isGroup` inside your hook or inside `allow`.
+
+### Rejecting manually
+
+Leave the option off and drive it yourself from the [`call-incoming`](/events) event:
+
+```typescript
+client.on('call-incoming', async (call) => {
+  if (call.isVideo) await client.rejectCall(call)   // pass the payload…
+  else await client.rejectCall(call.callId, call.from) // …or the raw ids
+})
+```
+
+<Callout type="default">
+`onReject` and `allow` failures are caught and logged — a throwing hook never crashes the client.
+`client.rejectCall()` **does** throw (e.g. `NOT_CONNECTED`) so you can handle it.
+</Callout>
+
 ## `autoDelete`
 
 `autoDelete` periodically prunes old messages from the local store to keep memory usage bounded. It is

docs/content/events.mdx

@@ -112,6 +112,12 @@ See [Interactive Messages](/interactive) for how to send buttons, lists, templat
 | --- | --- | --- |
 | `call-incoming` | `CallPayload` (`kind: 'incoming'`) | An incoming call. `{ callId, from, isGroup, isVideo, timestamp, status?, kind }`. |
 | `call-ended` | `CallPayload` (`kind: 'ended'`) | A call ended. Same shape as above with `kind: 'ended'`. |
+
+<Callout type="info">
+🔗 Calls are **unofficial-provider only**. To hang up automatically, set
+[`autoRejectCall`](/configuration#autorejectcall); to do it yourself, call
+`client.rejectCall(call)` (or `client.rejectCall(callId, from)`) from a `call-incoming` handler.
+</Callout>
 | `presence` | `PresencePayload` | A contact's presence changed. `{ jid, participant?, status }` where `status` is `available \| unavailable \| composing \| recording \| paused`. |
 | `history-sync` | `HistorySyncPayload` | A history sync batch progressed. `{ syncType, status: 'complete' \| 'paused', explicit }`. |
 | `newsletter` | `NewsletterPayload` | A newsletter/channel event (reaction, view, participants, settings). `{ newsletterId, timestamp, action, ... }`. |

docs/content/official/limits.mdx

@@ -214,6 +214,7 @@ No amount of config unlocks these — they're not in the Cloud API:
 | AIRich rich bubble (`rich: true`), rendered tables | ❌ WhatsApp-Web-only proto | Send plain text (see below); `rich: true` throws a clear error on cloud |
 | Edit / delete / pin / disappearing | ❌ | Send a correction message |
 | Presence (others' online/typing) | ❌ | — |
+| Calls / auto-reject calls | ❌ no call events in the Cloud API | Use the [unofficial provider](/unofficial) (`autoRejectCall`, `client.rejectCall()`) |
 | Status / stories | ❌ | Unofficial provider |
 | Read arbitrary chat history | ❌ | Persist inbound to your own [store](/storage) |
 

docs/content/providers.mdx

@@ -114,6 +114,7 @@ Legend — ✅ supported · ❌ not available · ⚠️ conditional.
 | Communities | ✅ | ❌ |
 | Newsletters (channels) | ✅ | ❌ |
 | Presence subscribe (online/typing of others) | ✅ | ❌ |
+| Calls (`call-incoming`, `rejectCall`, `autoRejectCall`) | ✅ | ❌ |
 | Status / stories | ✅ | ❌ |
 | Privacy settings | ✅ | ❌ |