> ## Documentation Index
> Fetch the complete documentation index at: https://docs.60db.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp assistant

> Configure native AI replies, review drafts and hand conversations to a teammate

The assistant uses the existing 60db SLM, Memory, STT, TTS and Judge services. Customer connection tokens and service credentials remain on the backend. Paths are relative to `https://api.60db.ai`.

The dashboard provides the same settings under **WhatsApp → Assistant** and review actions in **Inbox**. [Dashboard workflow](https://docs.60db.ai/features/whatsapp.md#configure-the-assistant).

## Configure a number

`PUT /whatsapp/numbers/{number_uuid}/assistant` requires an owner, admin or developer on an active Starter, Creator or Pro **platform** plan. Authenticate with a dashboard session or a 60db API key with `whatsapp` scope.

```json theme={null}
{
  "enabled": true,
  "mode": "draft",
  "instructions": "Answer support questions using the selected knowledge. Ask a teammate to help when information is missing.",
  "collections": ["support"],
  "transcribe_audio": true,
  "voice_replies": false,
  "voice_id": "",
  "judge_enabled": true,
  "min_confidence": 0.8
}
```

`enabled`, `mode` and `instructions` are required. Instructions may contain up to 16,000 characters. `collections` defaults to an empty list and accepts up to ten accessible collection IDs in this workspace. Changing settings cancels pending generation, drafts and queued assistant replies. New settings apply to future inbound messages; existing history is not automatically processed or charged.

| Option | Behavior |
| - | - |
| `mode: "draft"` | Generates a reply for explicit review; does not send automatically |
| `mode: "automatic"` | Sends eligible replies in conversations with `mode: "ai"` |
| `collections` | Retrieves context from these exact workspace collections; removed or inaccessible knowledge causes a visible failure |
| `transcribe_audio` | Defaults to `true`; transcribes supported inbound audio before generating a reply |
| `voice_replies` | Defaults to `false`; when enabled, requires `voice_id` and generates a mono Ogg/Opus voice note |
| `judge_enabled` | Defaults to `true`; evaluates the reply before drafting or automatic dispatch |
| `min_confidence` | Defaults to `0.8`, between 0 and 1; lower-confidence or handoff decisions pause the conversation for a teammate |

Native service permissions are checked independently. An API key needs `llm` or `slm` for generation, `memory` or legacy `llm` for selected knowledge, `stt` for audio transcription, `tts` for voice replies, and `judge`, `slm` or legacy `llm` for Judge. The configured user's live membership and the configured key's activity/scopes are checked again during generation. Revoking them stops future assistant work.

Voice selection accepts a public catalog voice or a local voice accessible in this workspace. The worker checks private voice ownership through Cerbos. Inbound voice notes are limited to 30 minutes. Transcripts longer than the assistant's 16,000-character limit are retained as a partial transcript and handed to a teammate; the assistant does not answer from a silently truncated question. Images, documents and unsupported messages also hand off to a teammate.

## Review a run

`GET /whatsapp/conversations/{conversation_uuid}/assistant-runs` lists runs newest first, with the standard `limit`/`offset` pagination. Read access follows the conversation's workspace and WhatsApp scope. Each run exposes its `state`, `reply_text`, `error_code`, `cost_usd`, stage cost breakdown, optional `transcript`, `transcript_truncated` flag, optional `voice_media_id`, and linked `outbound_message_id`. Private instructions and retrieved knowledge are not returned by this endpoint.

`GET /whatsapp/conversations/{conversation_uuid}/messages` includes `transcript` and `transcript_truncated` on inbound messages with a saved assistant transcription, including older message pages. The dashboard shows the latest assistant attempt and up to 19 earlier attempts; the run API supports full pagination.

| State | Meaning |
| - | - |
| `pending` / `processing` | Waiting for generation or generating |
| `draft` | Ready for explicit review |
| `queued` | Accepted into the outbound queue; check the linked message for sent/delivered/read/failed/unconfirmed status |
| `handoff` | A teammate must respond; automatic replies are paused |
| `failed` | Generation failed; `error_code` identifies the reason |
| `cancelled` | A newer customer message, takeover, discard or settings change superseded the run |

Members with paid sending access can use these endpoints:

| Method | Path | Behavior |
| - | - | - |
| POST | `/whatsapp/assistant-runs/{run_uuid}/approve` | Queues a current `draft`; returns the accepted message with HTTP 202 |
| POST | `/whatsapp/assistant-runs/{run_uuid}/discard` | Cancels a `draft` |
| POST | `/whatsapp/assistant-runs/{run_uuid}/retry` | Explicitly retries a current `failed` run, preserving already saved and billed stages |

Bodies and `Idempotency-Key` headers are not required for these run actions. Repeating an accepted approval returns its existing message. A superseded draft or a handoff cannot be approved through this endpoint. Generation is not retried automatically after a worker interruption or an upstream failure.

## Take over or resume

`PATCH /whatsapp/conversations/{conversation_uuid}` with `{"mode":"manual"}` pauses the assistant and cancels pending generation, drafts and queued assistant messages. Sending an ordinary console/API message also takes over the conversation. Saved, billed generation stages remain in the audit record.

For an enabled automatic assistant, resume with `{"mode":"ai"}`. For an enabled draft assistant, resume draft generation with `{"assistant_paused":false}`. Resumption applies to future customer messages. A new conversation uses AI mode when the number's assistant is automatic; existing manual conversations stay manual until explicitly resumed.

The worker rechecks the current settings, latest customer turn, consent, workspace access and 24-hour reply window immediately before dispatch. A newer inbound message cancels stale drafts and queued assistant replies. A message already submitted to Meta cannot be recalled.

Resolving a conversation cancels its current generation, drafts and queued assistant replies. A future customer message reopens it; the existing assistant mode and pause setting still apply.

## Credits and failures

WhatsApp access is included in the paid platform plans. AI stages consume existing workspace credits at their existing service rates; Meta fees remain separate. Each successful stage is saved and billed in the same database transaction. An insufficient balance prevents saving or using that stage's result. Retrying a later failure reuses previously saved stages without charging them again.

Completed stages remain billable when a later stage fails or a teammate takes over. Low-SNR audio that STT reports as dropped is nonbillable and hands off. Unavailable selected knowledge, invalid model usage, invalid Judge decisions and interrupted generation fail visibly rather than sending an unchecked reply. Subscribe to [`assistant.failed` webhook events](https://docs.60db.ai/api-reference/whatsapp/webhook-events) for failures, including interrupted workers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.