# Account and security
Source: https://docs.verba.ink/guides/account-and-security

Magic-link login, 2FA, API keys, connected services, and account safety.

## Questions this guide answers

* How does passwordless magic-link login work?
* How do I enable and verify 2FA?
* How many API keys can I create?
* What happens when I revoke a key?
* Can I disconnect Patreon anytime?

## Passwordless login (magic link)

Verba supports passwordless email auth.

Flow:

1. Request a magic link with your email.
2. Open the email and click the link.
3. Verba verifies the token and signs you in.

Important behavior:

* Magic links expire after `20 minutes`.
* You can request a resend.
* Invalid/expired links must be requested again.

## Two-factor authentication (2FA)

### Setup

* Open settings security section.
* Generate QR/secret.
* Confirm with a valid authenticator code.
* Save backup codes.

### Login verification

During protected login flows, Verba may require:

* 6-digit authenticator token
* Or 8-character backup code

Backup codes are one-time use and removed after successful verification.

### Disable 2FA

* Requires valid 2FA verification to disable.

## API keys

### Key format and limits

* Keys use prefix: `vka_`
* Active key limit: up to `3` keys

### Key lifecycle

* Create from Settings -> Security -> API Keys.
* Full key value is shown once on creation.
* Revoke any key instantly from dashboard.
* Revoked keys stop authenticating immediately.

### Authentication headers

Use one of:

* `Authorization: Bearer vka_...`
* `x-api-key: vka_...`

<Note>
  API keys are only shown in full once when you create them. Verba stores the
  verification form of API keys, not a reusable plaintext copy.
</Note>

## How Verba stores sensitive data

Verba applies extra protection to sensitive secrets before they are written to
storage.

Examples include:

* 2FA secrets
* 2FA backup codes
* Connected-service access/refresh tokens
* Bot/service tokens that must be reused later by the platform
* Owner-provided Slack client secrets and signing secrets
* Twitch broadcaster and dedicated bot-account OAuth refresh tokens

This means raw database access alone should not expose those values in their
original usable form.

## Connected services

### Slack

Slack is dedicated-only. Each Verb owner creates an app and provides its Client
ID, Client Secret, and Signing Secret. Verba encrypts those credentials and the
OAuth bot token. Never paste them into a chat or knowledge entry.

### Twitch

Twitch owners authorize a broadcaster account and a different bot account by
OAuth. Verba stores and refreshes the resulting tokens; it never needs either
account's password or a manually pasted bot token.

### Email

Verb owners do not receive mailbox credentials. Postmark SMTP and webhook
credentials belong to the Verba deployment. Contact consent and unsubscribe
state are scoped to one Verb and sender address.

### Patreon linking

* Patreon can be linked from settings.
* Tier/benefits sync with account profile.

### Patreon disconnect guard

Disconnect may be blocked while an active Patreon subscription is still attached.

## Abuse protection and temporary IP bans

Verba uses Cloudflare edge protection plus smaller endpoint-specific backend
limits to prevent request bursts, scraping loops, and automated flooding.

If an IP repeatedly trips those protections, Verba can place it into a temporary
ban ladder:

* Three Cloudflare block events within `24 hours` can promote an address to a
  `24-hour` temporary ban.
* A later repeat-offender promotion can extend that ban to `30 days`.

Active bans are stored by Verba and synchronized with Cloudflare. Blocked
requests receive an HTTP `403` response while the ban is active. Sensitive
endpoints such as magic-link requests keep their own smaller limits even when
an address is not banned.

If you hit a temporary ban unexpectedly during normal use, stop rapid retries,
wait for the window to expire, and contact support with:

* Exact timestamp
* Your public IP if known
* The page or action you were using
* A screenshot or error message

## Profile asset uploads

From settings:

* Avatar/banner image uploads are validated and moderated.
* Keep files under dashboard limits (commonly `10MB` for profile uploads).

## Deleting your account

Account deletion removes your account data and associated records.

Behavior includes cleanup for:

* Verbs and related references
* Group/DM associations
* Messages and conversation records tied to deleted entities

Group ownership handling:

* If other members exist, ownership can transfer.
* If no replacement exists, owned groups may be removed.

<Warning>
  Account deletion is destructive. Export or copy anything you need before
  confirming deletion.
</Warning>

<CardGroup>
  <Card title="Public API v1" icon="code" href="/guides/api">
    Full endpoint docs for authentication, requests, streaming, and errors.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Fix login, 2FA, and API key issues quickly.
  </Card>
</CardGroup>


# AI engine settings
Source: https://docs.verba.ink/guides/ai-engine

Tune model behavior, response length, context, and search.

## Questions this guide answers

* Which settings affect creativity vs consistency?
* Why are responses short or long?
* How much context and max tokens can my plan use?
* What does web search actually do?
* How do streaming and social state change platform replies?

## Core controls

| Setting            | Range                | What it changes                                             |
| ------------------ | -------------------- | ----------------------------------------------------------- |
| Temperature        | `0..2`               | Randomness and creativity                                   |
| Top-p              | `0..1`               | Diversity of token selection                                |
| Model Context      | plan-limited         | Number of recent messages included                          |
| Reply Style        | preset               | Voice/format tendency                                       |
| Multi-message      | on/off + delay       | Sends split follow-up replies                               |
| Response Streaming | on/off               | Sends an early partial platform reply and edits it in place |
| Web search         | on/off               | Allows live web-grounded replies                            |
| Social state       | `-5..5`, step `0.25` | Temporary mood and conversation posture                     |

## System instructions (behavior prompt)

System instructions are your verb's persistent behavior rules.

Where to set:

* Dashboard -> Bot -> AI Engine -> Behavior
* Field name: `systemInstructions`

Limit:

* Up to `8000` characters

How they interact with other layers:

* `systemInstructions`: behavior/rules/tone constraints
* Training examples: style shaping and response pattern hints
* Long-term memory: durable facts/preferences
* Knowledge entries: factual/reference content
* Conversation context: recent turns in current chat/thread/session

Practical rule:

* Put "how to behave" in system instructions.
* Put "facts to remember" in knowledge/memory.
* Put "how to phrase outputs" in training examples.

## Plan-based limits

Current default limits:

| Plan  | Max model context | Max response tokens |
| ----- | ----------------- | ------------------- |
| Free  | `50`              | `4096`              |
| Plus  | `75`              | `8192`              |
| Pro   | `100`             | `16384`             |
| Ultra | Unlimited         | `32768`             |

<Note>
  If you request settings above your tier limits, they are clamped or rejected
  depending on the endpoint.
</Note>

## Premium AI model access

AI model availability is plan-based.

If you open the AI Engine and choose a model that is outside your current tier,
Verba shows an upgrade prompt with the number of additional premium AI models
available above your current plan.

That upgrade hint is dynamic, so the exact count can differ depending on:

* Your current plan
* The active model catalog
* Whether new premium models have been added since your last visit

<Card title="Valley 3" icon="sparkles" href="/guides/valley-3">
  Learn about Verba's free roleplay, storytelling, and vision model.
</Card>

## Recommended presets

<CardGroup>
  <Card title="Reliable support" icon="shield">
    Temperature `0.4-0.7`, top-p `0.7-0.9`, moderate context.
  </Card>

  <Card title="Creative roleplay" icon="sparkles">
    Temperature `0.8-1.1`, top-p `0.9-1.0`, higher context.
  </Card>

  <Card title="Cost-aware" icon="wallet">
    Lower context, web search off, shorter reply style.
  </Card>

  <Card title="Fast troubleshooting" icon="bolt">
    Lower context + deterministic settings to reduce latency variance.
  </Card>
</CardGroup>

## Multi-message behavior

When enabled:

* Verba can split a response into multiple shorter messages.
* Delay between parts is configurable (`0..10000ms`).

Use this for natural chat pacing; disable if you want one compact answer.

## Response streaming

On Ultra, Discord, WhatsApp, and Telegram can show the beginning of a response
early and edit that message into the complete answer. This is separate from the
public API SSE path, which is also Ultra-only.

Use it for better perceived speed on long answers. Turn it off when your style
depends on several intentionally separate messages.

<Card title="Response streaming" icon="bolt" href="/guides/response-streaming">
  See supported surfaces, fallback behavior, and API differences.
</Card>

## Social state

The **Social** tab adds eight temporary sliders for willingness to talk,
irritation, focus, energy, confidence, affection, playfulness, and curiosity.
Set them manually or enable Auto mode so recent exchanges can move them
gradually. This layer influences delivery without replacing personality,
knowledge, memory, or safety rules.

<Card title="Social and emotional state" icon="heart" href="/guides/social-and-emotional-state">
  Learn the ranges, auto-mode behavior, and memory interaction.
</Card>

## Web search behavior

When enabled, Verba may perform model-driven search planning before the final answer.
This improves freshness, but can increase:

* Latency
* Token usage
* Cost

Use web search for:

* News
* Live pricing
* Fast-changing product details

Keep it off for:

* Roleplay
* Stable canon/lore
* Deterministic support flows

## System instructions best practices

* Keep instructions concrete and scoped.
* Avoid contradictory rules.
* Prefer short imperative bullets over long prose.
* Include failure policy (what to do when unknown).
* Specify output format explicitly (headings, bullets, steps, code blocks).

## Quick diagnostics

<AccordionGroup>
  <Accordion title="Replies are too generic">
    Lower temperature, tighten system instructions, and add targeted training examples.
  </Accordion>

  <Accordion title="Bot forgets recent details">
    Increase model context (within your plan limit).
  </Accordion>

  <Accordion title="Replies are too short">
    Increase max tokens and use a fuller reply style.
  </Accordion>

  <Accordion title="Replies are too slow">
    Reduce context and disable web search unless needed. Response Streaming can
    make the reply appear sooner, but does not reduce total generation time.
  </Accordion>
</AccordionGroup>

<Card title="Bot Settings Reference" icon="book" href="/guides/bot-settings-reference">
  See all AI-related fields and limits in one place.
</Card>


# Public API v1
Source: https://docs.verba.ink/guides/api

Use API keys to integrate Verba characters into your own apps and workflows.

## Base URL

`https://api.verba.ink`

<Note>
  Selecting **API** in Verba's integration switcher opens this page directly.
  API is a documentation link rather than a connectable provider, so it does
  not run OAuth or count as a connected integration.
</Note>

## How the API works (short answer)

1. Create an API key in Dashboard -> Settings -> Security -> API Keys (Pro and Ultra plans).
2. Call `POST /v1/response` with `character` + `messages`.
3. Save the returned `session_id` and reuse it for follow-up requests.
4. Use `stream: true` for SSE streaming on Ultra plans.
5. Use `POST /v1/image` when you need image generation.

Minimal text request:

```json theme={null}
{
  "character": "mycharacter_abc",
  "messages": [
    { "role": "user", "content": "How does the API work?" }
  ]
}
```

## Fast answers

* Base URL: `https://api.verba.ink`
* Text endpoint: `POST /v1/response`
* Image endpoint: `POST /v1/image`
* Auth: `Authorization: Bearer vka_...` or `x-api-key: vka_...`
* Session memory: reuse `session_id` on later calls to continue context
* API access: Pro and Ultra plans
* Streaming: `stream: true` on `/v1/response` (Ultra)
* Image generation allowance: Free `20/mo`, Plus `50/mo`, Pro `100/mo`, Ultra unlimited
* Message count limit: up to `60` items in `messages`
* Message size limits: each message text up to `4000` chars, total up to `20000` chars
* Session ID format: optional, max `128` chars, allowed chars `A-Z a-z 0-9 : _ -`
* Image URL limit: up to `4` combined URLs
* Tool limits: up to `8` tool definitions, up to `2` executed tool calls per request

<Note>
  API SSE is separate from the AI Engine's Response Streaming toggle for
  Discord, WhatsApp, and Telegram. Both currently require Ultra, but the
  platform toggle does not enable API SSE.
</Note>

## Request limits (fast reference)

| Field                        | Limit                     |
| ---------------------------- | ------------------------- |
| `messages` length            | `60` max                  |
| Per-message text             | `4000` chars max          |
| Total text across `messages` | `20000` chars max         |
| `session_id`                 | optional, `128` chars max |
| `image_urls` (combined)      | `4` max                   |
| `tools` definitions          | `8` max                   |
| Executed tool calls          | `2` max per request       |
| `/v1/image` prompt           | `1500` chars max          |
| `/v1/image` size             | only `1024x1024`          |

## Quick start

<Steps>
  <Step title="Create an API key">
    Go to Verba <strong>Settings -> Security -> API Keys</strong> and create a key. API keys are available on Pro and Ultra plans.
  </Step>

  <Step title="Pick a character">
    Use your character vanity slug or vanity URL (for example `mycharacter_abc` or `https://verba.ink/v/mycharacter_abc`).
  </Step>

  <Step title="Call an endpoint">
    Use `POST /v1/response` for text replies, or `POST /v1/image` for image generation.
  </Step>
</Steps>

## Authentication

Send your API key in either header:

* `Authorization: Bearer vka_...`
* `x-api-key: vka_...`

If no key is provided, or the key is invalid/revoked, the API returns `401`.

## API key quick facts

* API key prefix is `vka_`.
* Maximum active keys per account: `3`.
* Key revocation is immediate.

## Character identifier

Both endpoints use `character` (not `verb_id`).

Accepted formats:

* Vanity slug: `mycharacter_abc`
* Vanity path: `/v/mycharacter_abc`
* Full vanity URL: `https://verba.ink/v/mycharacter_abc`

## Endpoints

* `POST /v1/response` for text chat completions
* `POST /v1/image` for image generation

## POST `/v1/response`

Text completion endpoint. You can optionally attach image URLs for vision-enabled prompting.

<Note>
  Supports both standard JSON and streaming. Set `stream: true` to receive Server-Sent Events (SSE) chunks.
</Note>

<Note>
  Streaming on `/v1/response` is available on Ultra plans.
</Note>

Required:

* `character` string (vanity URL or vanity slug)
* `messages` array (`role` + `content`)

Optional:

* `session_id` string
* `temperature` number (`0..2`)
* `top_p` number (`0..1`)
* `max_tokens` number
* `stream` boolean (`true` for SSE stream, default `false`)
* `image_urls` array of image URLs (`http/https`, max 4)
* `tools` array (OpenAI-style function tools, max 8)
* `tool_choice` (`"auto"` or `"none"`)
* `debug` object (`{ "tools": true }` to include tool traces)

### Session memory on `/v1/response`

How it works:

1. Send your first request with or without `session_id`.
2. If omitted, the API generates one and returns it in the response.
3. Reuse that same `session_id` in later requests to keep context for that caller + character.

If you use a new `session_id`, you start a new conversation state.

`messages[].content` supports:

* String text content
* Array parts with:
  * `{ "type": "text", "text": "..." }`
  * `{ "type": "image_url", "image_url": { "url": "https://..." } }`

You can pass image URLs either in `messages[].content` or top-level `image_urls` (both are merged, max 4 total).
You cannot pass custom `system` messages on `/v1/response`; character personality + system instructions are applied automatically.
Tool configuration is request-scoped only (not stored on your character/dashboard).

### Request examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.verba.ink/v1/response \
    -X POST \
    -H "Authorization: Bearer $VERBA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "character": "mycharacter_abc",
      "messages": [
        { "role": "user", "content": "Tell me a short story about space pirates." }
      ],
      "stream": false
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.verba.ink/v1/response", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VERBA_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      character: "mycharacter_abc",
      messages: [
        { role: "user", content: "Tell me a short story about space pirates." }
      ],
      stream: false
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.verba.ink/v1/response",
      headers={
          "Authorization": f"Bearer {os.environ['VERBA_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "character": "mycharacter_abc",
          "messages": [
              {"role": "user", "content": "Tell me a short story about space pirates."}
          ],
          "stream": False,
      },
      timeout=60,
  )

  print(response.status_code)
  print(response.json())
  ```

  ```powershell PowerShell theme={null}
  $headers = @{
    Authorization = "Bearer $env:VERBA_API_KEY"
    "Content-Type" = "application/json"
  }

  $body = @{
    character = "mycharacter_abc"
    messages = @(
      @{
        role = "user"
        content = "Tell me a short story about space pirates."
      }
    )
    stream = $false
  } | ConvertTo-Json -Depth 10

  Invoke-RestMethod `
    -Method Post `
    -Uri "https://api.verba.ink/v1/response" `
    -Headers $headers `
    -Body $body
  ```
</CodeGroup>

### Session memory example

First call:

```json theme={null}
{
  "character": "mycharacter_abc",
  "messages": [
    { "role": "user", "content": "My name is Sam. Remember that." }
  ]
}
```

Response includes `session_id`:

```json theme={null}
{
  "session_id": "sess_abc123",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Got it, Sam."
      }
    }
  ]
}
```

Follow-up call (same session):

```json theme={null}
{
  "character": "mycharacter_abc",
  "session_id": "sess_abc123",
  "messages": [
    { "role": "user", "content": "What's my name?" }
  ]
}
```

### Vision input example

```json theme={null}
{
  "character": "mycharacter_abc",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe what is happening here." },
        { "type": "image_url", "image_url": { "url": "https://example.com/city.jpg" } }
      ]
    }
  ],
  "stream": false
}
```

### Request-scoped tool calling

`/v1/response` supports server-executed HTTP function tools passed in the request.

* Tools are not persisted.
* Allowed methods: `GET`, `POST`.
* Tool URLs support only `http/https` on ports `80` or `443`.
* Local/private network targets are blocked.
* Tool responses must be `application/json` (or `+json`) or `text/plain`.
* Max executed tool calls per request: `2`.
* Tool requests execute through Verba-managed outbound egress.
* Built-in character `webSearch` remains separate and unchanged.

Tool object shape:

```json theme={null}
{
  "type": "function",
  "function": {
    "name": "search_web",
    "description": "Search latest web results",
    "parameters": {
      "type": "object",
      "properties": {
        "query": { "type": "string" }
      },
      "required": ["query"]
    },
    "x_verba_http": {
      "url": "https://example.com/search",
      "method": "GET",
      "query_param": "q",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      },
      "timeout_ms": 8000
    }
  }
}
```

`tool_choice` supports:

* `"auto"` (default model decides)
* `"none"` (disable tool calls for this request)

How `auto` works:

* Verba first lets the model decide natively (provider `tool_calls` if supported).
* If the provider does not emit native `tool_calls`, Verba runs an internal model planner step to decide whether one tool should be used.
* This preserves model-driven behavior while improving compatibility across providers.

When `debug.tools=true`:

* Non-stream response includes `debug.tool_runs[]`.
* Stream response emits extra SSE frames with `object: "chat.completion.tool_trace"`.

### Tool example (`GET` web search)

```json theme={null}
{
  "character": "mycharacter_abc",
  "messages": [
    { "role": "user", "content": "What happened in AI this week?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_web",
        "description": "Search web headlines",
        "parameters": {
          "type": "object",
          "properties": {
            "query": { "type": "string" }
          },
          "required": ["query"]
        },
        "x_verba_http": {
          "url": "https://example-search-api.com/search",
          "method": "GET",
          "query_param": "q",
          "headers": {
            "Authorization": "Bearer sk_live_..."
          }
        }
      }
    }
  ],
  "tool_choice": "auto",
  "debug": { "tools": true }
}
```

### Tool example (`POST` JSON)

```json theme={null}
{
  "character": "mycharacter_abc",
  "messages": [
    { "role": "user", "content": "Fetch weather for Paris and summarize it." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "weather_lookup",
        "description": "Return weather by city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        },
        "x_verba_http": {
          "url": "https://example.com/weather",
          "method": "POST",
          "headers": {
            "Authorization": "Bearer sk_live_..."
          },
          "body_mode": "json"
        }
      }
    }
  ]
}
```

### Example response

```json theme={null}
{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "created": 1739730000,
  "model": "m_free_a",
  "character": "mycharacter_abc",
  "session_id": "sess_...",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

Example response addition when `debug.tools=true`:

```json theme={null}
{
  "debug": {
    "tool_runs": [
      {
        "tool_name": "search_web",
        "method": "GET",
        "url": "https://example-search-api.com/search?q=ai",
        "status": "success",
        "http_status": 200,
        "duration_ms": 412,
        "request_preview": { "query": { "q": "ai" } },
        "response_preview": { "results": [{ "title": "..." }] }
      }
    ]
  }
}
```

### Streaming (`stream: true`)

With `stream: true`, `/v1/response` returns `text/event-stream` and emits `data:` events.

* Each event is an OpenAI-style `chat.completion.chunk` payload.
* If `debug.tools=true` and tools run, extra events use `object: "chat.completion.tool_trace"`.
* The final event is `data: [DONE]`.
* You should concatenate `choices[0].delta.content` chunks to build the assistant message.
* Free, Plus, and Pro plans return `403 stream_plan_upgrade_required` when `stream: true` is used.

Example chunk:

```json theme={null}
{
  "id": "chatcmpl_...",
  "object": "chat.completion.chunk",
  "created": 1739730000,
  "model": "m_free_a",
  "character": "mycharacter_abc",
  "session_id": "sess_...",
  "choices": [
    {
      "index": 0,
      "delta": { "content": "Hello" },
      "finish_reason": null
    }
  ]
}
```

Final chunk:

```json theme={null}
{
  "id": "chatcmpl_...",
  "object": "chat.completion.chunk",
  "created": 1739730000,
  "model": "m_free_a",
  "character": "mycharacter_abc",
  "session_id": "sess_...",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

Then:

```text theme={null}
data: [DONE]
```

### Streaming request examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -N https://api.verba.ink/v1/response \
    -X POST \
    -H "Authorization: Bearer $VERBA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "character": "mycharacter_abc",
      "messages": [
        { "role": "user", "content": "Give me a short greeting." }
      ],
      "stream": true
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.verba.ink/v1/response", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VERBA_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      character: "mycharacter_abc",
      messages: [{ role: "user", content: "Give me a short greeting." }],
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const events = buffer.split("\\n\\n");
    buffer = events.pop() || "";

    for (const event of events) {
      if (!event.startsWith("data:")) continue;
      const data = event.slice(5).trim();
      if (data === "[DONE]") {
        process.stdout.write("\\n");
        continue;
      }
      const chunk = JSON.parse(data);
      const delta = chunk.choices?.[0]?.delta?.content;
      if (delta) process.stdout.write(delta);
    }
  }
  ```

  ```python Python theme={null}
  import json
  import os
  import requests

  response = requests.post(
      "https://api.verba.ink/v1/response",
      headers={
          "Authorization": f"Bearer {os.environ['VERBA_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "character": "mycharacter_abc",
          "messages": [{"role": "user", "content": "Give me a short greeting."}],
          "stream": True,
      },
      stream=True,
      timeout=120,
  )

  for line in response.iter_lines(decode_unicode=True):
      if not line or not line.startswith("data:"):
          continue
      data = line[5:].strip()
      if data == "[DONE]":
          print()
          break
      chunk = json.loads(data)
      delta = (((chunk.get("choices") or [{}])[0].get("delta") or {}).get("content"))
      if delta:
          print(delta, end="", flush=True)
  ```

  ```powershell PowerShell theme={null}
  $json = @{
    character = "mycharacter_abc"
    messages = @(
      @{
        role = "user"
        content = "Give me a short greeting."
      }
    )
    stream = $true
  } | ConvertTo-Json -Depth 10

  $http = [System.Net.Http.HttpClient]::new()
  $request = New-Object System.Net.Http.HttpRequestMessage([System.Net.Http.HttpMethod]::Post, "https://api.verba.ink/v1/response")
  $request.Headers.Authorization = [System.Net.Http.Headers.AuthenticationHeaderValue]::new("Bearer", $env:VERBA_API_KEY)
  $request.Content = New-Object System.Net.Http.StringContent($json, [System.Text.Encoding]::UTF8, "application/json")

  $response = $http.SendAsync($request, [System.Net.Http.HttpCompletionOption]::ResponseHeadersRead).Result
  $stream = $response.Content.ReadAsStreamAsync().Result
  $reader = New-Object System.IO.StreamReader($stream)

  while (-not $reader.EndOfStream) {
    $line = $reader.ReadLine()
    if (-not $line -or -not $line.StartsWith("data:")) { continue }
    $data = $line.Substring(5).Trim()
    if ($data -eq "[DONE]") { break }
    $chunk = $data | ConvertFrom-Json
    $delta = $chunk.choices[0].delta.content
    if ($delta) { Write-Host -NoNewline $delta }
  }
  Write-Host ""
  ```
</CodeGroup>

Streaming with tools works the same way: the API executes tool calls server-side first, then streams final assistant text chunks.

```json theme={null}
{
  "character": "mycharacter_abc",
  "messages": [{ "role": "user", "content": "Find and summarize today's top AI headline." }],
  "stream": true,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_web",
        "parameters": {
          "type": "object",
          "properties": { "query": { "type": "string" } },
          "required": ["query"]
        },
        "x_verba_http": {
          "url": "https://example-search-api.com/search",
          "method": "GET",
          "query_param": "q"
        }
      }
    }
  ],
  "debug": { "tools": true }
}
```

## POST `/v1/image`

Generates one image URL.

<Note>
  Image generation is limited monthly by the character owner's plan: Free `20`, Plus `50`, Pro `100`, and Ultra unlimited.
</Note>

Required:

* `character` string (vanity URL or vanity slug)
* `prompt` string

Optional:

* `session_id` string
* `image_urls` string array (reference images)
* `size` (`1024x1024` only)
* `response_format` (`url` only)

### Request examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.verba.ink/v1/image \
    -X POST \
    -H "Authorization: Bearer $VERBA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "character": "mycharacter_abc",
      "prompt": "A cinematic portrait of a cyberpunk fox detective",
      "size": "1024x1024",
      "response_format": "url"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.verba.ink/v1/image", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VERBA_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      character: "mycharacter_abc",
      prompt: "A cinematic portrait of a cyberpunk fox detective",
      size: "1024x1024",
      response_format: "url"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.verba.ink/v1/image",
      headers={
          "Authorization": f"Bearer {os.environ['VERBA_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "character": "mycharacter_abc",
          "prompt": "A cinematic portrait of a cyberpunk fox detective",
          "size": "1024x1024",
          "response_format": "url",
      },
      timeout=120,
  )

  print(response.status_code)
  print(response.json())
  ```

  ```powershell PowerShell theme={null}
  $headers = @{
    Authorization = "Bearer $env:VERBA_API_KEY"
    "Content-Type" = "application/json"
  }

  $body = @{
    character = "mycharacter_abc"
    prompt = "A cinematic portrait of a cyberpunk fox detective"
    size = "1024x1024"
    response_format = "url"
  } | ConvertTo-Json -Depth 10

  Invoke-RestMethod `
    -Method Post `
    -Uri "https://api.verba.ink/v1/image" `
    -Headers $headers `
    -Body $body
  ```
</CodeGroup>

### Example response

```json theme={null}
{
  "created": 1739730000,
  "character": "mycharacter_abc",
  "session_id": "sess_...",
  "model": "m_free_a",
  "revised_prompt": "A cinematic portrait of a cyberpunk fox detective",
  "data": [
    {
      "url": "https://api.verba.ink/uploads/generated-images/img_...png"
    }
  ]
}
```

## Sessions and memory

* `session_id` is optional.
* If omitted, Verba generates one and returns it.
* Reusing the same `session_id` preserves API conversation context for that caller + verb pair.
* API memory is stored in conversation history only (not DM or message logs).

## Access, billing, and limits

* API access is available on Pro and Ultra plans.
* Verb privacy still applies:
  * Private characters: owner only
  * Public characters: any API caller
* Billing and tier/model enforcement are applied to the **character owner account**.
* `/v1/*` uses account rate limits via the same per-user limiter model.

## Message format (`/v1/response`)

* `messages` must be an array.
* Include at least one `user` message.
* Allowed roles: `user`, `assistant` (`assistant` maps internally to model role).
* `system` role is blocked on `/v1/response` to prevent overriding character instructions.
* `messages[].content` supports text and `image_url` parts.
* Top-level `image_urls` is also supported.
* Combined image URL limit is 4.
* `tools` is optional and request-scoped (max 8 per request).
* `tool_choice` is optional (`auto` or `none`).

## Error model

Errors return JSON with a top-level `message` and an `error` object.

```json theme={null}
{
  "message": "stream must be a boolean",
  "error": {
    "message": "stream must be a boolean",
    "type": "invalid_stream",
    "code": 400
  }
}
```

* `error.type`: stable machine-readable error type (for program logic)
* `error.code`: HTTP status code

Common error cases:

* `401 invalid_api_key` for missing/invalid/revoked API key
* `403 verb_access_denied` for private character access by non-owner
* `403 api_plan_upgrade_required` when the API key owner is not on Pro or Ultra
* `403 stream_plan_upgrade_required` when a non-Ultra plan requests `stream: true`
* `403 insufficient_credits` when the character owner has no credits for the selected model
* `403 image_limit_reached` when the character owner has reached their monthly image generation allowance
* `400 invalid_message_role` when `system` role is provided in `messages`
* `400 invalid_stream` when `stream` is not a boolean
* `400 invalid_tools` for malformed tool schema/config
* `400 invalid_tool_choice` for invalid `tool_choice`
* `400 blocked_tool_url` when tool URL targets local/private hosts
* `400 tool_call_limit_exceeded` when model attempts more than 2 tool calls
* `400 invalid_image_urls` when image URL payload format is invalid
* `400 blocked_image_url` when image URL targets local/private network hosts
* `400 too_many_image_urls` when more than 4 image URLs are provided
* `502 tool_proxy_unavailable` when managed outbound tool egress is unavailable
* `502 tool_execution_failed` when upstream tool execution fails
* `400 invalid_size` when `/v1/image` size is not `1024x1024`


# How the API works
Source: https://docs.verba.ink/guides/api-how-it-works

Direct answer to how api.verba.ink works, with minimal request flow and limits.

## Short answer

Verba API works by authenticating with a Pro or Ultra API key, selecting a character, sending chat messages to `/v1/response`, and reusing `session_id` to keep memory between calls.

<Note>
  The **API** item in Verba's integration switcher is a direct link to the
  [full API guide](/guides/api). It does not run OAuth, create a provider
  connection, or count toward the connected-integration total.
</Note>

## 5-step flow

1. Create an API key (`vka_...`) in Dashboard -> Settings -> Security -> API Keys on a Pro or Ultra plan.
2. Send `POST https://api.verba.ink/v1/response`.
3. Include `character` (slug/path/URL) and `messages`.
4. Read the returned response and store `session_id`.
5. Reuse that same `session_id` in future calls for ongoing context.

## Minimal request

```json theme={null}
{
  "character": "mycharacter_abc",
  "messages": [
    { "role": "user", "content": "How does the API work?" }
  ]
}
```

## Required headers

* `Authorization: Bearer vka_...`
* or `x-api-key: vka_...`

## Important limits

* `messages`: max `60`
* message text: `4000` chars each
* total text across messages: `20000` chars
* `session_id`: optional, max `128` chars
* combined image URLs: max `4`
* `/v1/image` prompt: max `1500` chars

## Streaming

Set `stream: true` on `/v1/response` to receive SSE chunks.
Streaming is available on Ultra plans.

This is separate from the Ultra per-verb Response Streaming toggle that edits
messages in place on Discord, WhatsApp, and Telegram.

## Related

* [Public API v1](/guides/api)
* [Plans and limits](/guides/plans-and-limits)
* [Question bank](/guides/question-bank)


# Best practices
Source: https://docs.verba.ink/guides/best-practices

Small habits that make verbs feel great.

## Build in layers

* Start with a short personality.
* Test in chat.
* Add depth only after the voice feels right.

## Keep prompts clean

* Use clear, direct language.
* Avoid conflicting instructions.
* Remove redundant details.

## Tune with intention

* Lower temperature for consistency.
* Increase context when you need continuity.
* Turn off web search unless it is required.

## Ask for feedback

Share your verb with friends or the community. Fresh eyes spot drift fast.

<Card title="Community" icon="users" href="/guides/community">
  Get quick feedback from other creators.
</Card>


# Billing and refunds
Source: https://docs.verba.ink/guides/billing-and-refunds

Purchases, invoices, and what to do if something looks off.

## Buying credits

Credits power text, image, and voice features. Buy a pack when you need more
headroom, and keep an eye on usage for big tests.

Daily Verb email limits are plan entitlements rather than credit purchases.
They reset at `00:00 UTC` and are shared by all Email-enabled Verbs on the
account: Free `10`, Plus `50`, Pro `100`, and Ultra `500` deliveries per day.
Buying extra credits does not raise this email quota.

## Refunds and issues

If a purchase looks wrong:

1. Check your billing history.
2. Grab the transaction ID.
3. Contact support with the details.

<Note>
  Refunds are handled through support. Keep receipts handy to speed things up.
</Note>

<CardGroup>
  <Card title="Billing page" icon="credit-card" href="https://verba.ink/billing">
    See purchases and current balance.
  </Card>

  <Card title="Support" icon="envelope" href="https://verba.ink/contact">
    Reach the team with billing questions.
  </Card>
</CardGroup>


# Bot settings reference
Source: https://docs.verba.ink/guides/bot-settings-reference

Field-by-field guide to AI, social state, memory, media, and platform settings.

## Why this page exists

This is a practical reference for all major bot configuration panels in the dashboard.
Use it when you need exact ranges, limits, and behavior implications.

## AI engine settings

| Field                      | Range / Limit | Notes                                                                                          |
| -------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| `temperature`              | `0..2`        | Creativity/randomness                                                                          |
| `top_p`                    | `0..1`        | Diversity control                                                                              |
| `modelContext`             | plan-capped   | Number of history messages considered                                                          |
| `replyStyle`               | preset enum   | `default`, `short`, `roleplay`, `crazy`, `human` (`creative` is a legacy alias for `roleplay`) |
| `webSearch`                | boolean       | Enables web-grounded answers                                                                   |
| `multiMessageEnabled`      | boolean       | Split response into multiple messages                                                          |
| `multiMessageDelayMs`      | `0..10000` ms | Delay between split parts                                                                      |
| `responseStreamingEnabled` | boolean       | Edit-in-place partial replies on Discord, WhatsApp, and Telegram                               |

### Plan caps

| Plan  | maxModelContext | maxTokens |
| ----- | --------------- | --------- |
| Free  | 50              | 4096      |
| Plus  | 75              | 8192      |
| Pro   | 100             | 16384     |
| Ultra | Unlimited       | 32768     |

Plan-level messages per minute are unlimited for all four tiers. Response
Streaming is available on Ultra.

## Behavior settings

| Field                 | Limit                                   | Notes                                                          |
| --------------------- | --------------------------------------- | -------------------------------------------------------------- |
| `systemInstructions`  | `8000` chars                            | Extra behavior control                                         |
| `autonomousMode`      | boolean                                 | Enables autonomous behavior paths where supported              |
| `autonomousFrequency` | `human`, `default`, `active`, `chaotic` | Tunes how often autonomous mode speaks without a direct prompt |

Autonomous frequency intent:

* `human`: calmer, more natural timing
* `default`: occasional low-key chime-ins
* `active`: joins more often without turning everything into spam
* `chaotic`: loosest filter, most willing to stir up banter

## Social state settings

`socialState.autoEnabled` lets Verba update temporary mood from recent
conversations. `socialState.context` accepts up to `500` characters.

All eight numeric values use `-5..5` with `0.25` steps:

* `willingnessToTalk`
* `irritation`
* `focus`
* `energy`
* `confidence`
* `affection`
* `playfulness`
* `curiosity`

Auto mode applies gradual, rate-limited changes and may consider a small set of
high-importance memories. It does not override system instructions or safety.

## Training settings

Per example:

* `input`: max `500` chars
* `expected`: max `2000` chars
* `importance`: `1..10`
* `keywords[]`: optional relevance hints

Keyword matches can prioritize specific examples during generation.

## Memory settings

Per memory entry:

* `content`: max `2000` chars
* `context`: max `500` chars
* `importance`: `1..10`

Global memory toggles:

* `autoMemoryEnabled`: boolean
* `autoMemoryInstructions`: max `2000` chars

## Knowledge settings

Per knowledge entry:

* `title`: max `100` chars
* `content`: max `8000` chars
* `category`: max `50` chars
* `importance`: `1..10`

Per verb:

* max `50` knowledge entries

URL scrape helper:

* Can auto-draft title/content/category from a provided URL.

## Voice engine settings

Common fields:

* `voiceEnabled`
* `voiceResponseFrequency` (`0..100`)
* `selectedVoice`
* `voiceLanguage`
* `voiceModel`
* `voiceReferenceText`

Voice cloning:

* Up to `3` clones per verb

Voice reply behavior:

* Generated audio is optional and accompanies the normal AI reply.
* `voiceResponseFrequency` controls how often eligible replies get an audio
  sidecar.
* A clear natural-language voice-message request can trigger the sidecar while
  Voice Engine is enabled.
* Slack and Twitch do not expose a standalone voice command.
* Native live calling is currently available only through Discord voice
  channels.

## Image engine settings

* `imageGeneration` toggle controls whether image commands/flows are active.
* `imageModel` selection is tier-aware.
* Non-eligible model selections can be automatically downgraded to allowed tiers.
* **Verba Free Image** is currently backed by GPT Image 1.
* Interactive generation supports square, portrait, landscape, banner, and
  explicit aspect-ratio presets.

## Discord module settings

Main controls:

* Connect/disconnect bot token
* Status/presence profile
* Discord Expression Controls
* Slash command toggles
* AI channel management
* Server list/leave server tools

Discord Expression Controls:

* `discordEmojiReactionsEnabled`
* `discordGifResponsesEnabled`
* `discordStickerResponsesEnabled`
* `discordCustomEmojisEnabled`
* `discordPollsEnabled`

GIFs and stickers are relevance-checked. Polls are selected for explicit
requests or strong group-choice moments and use cooldown and duplicate guards.

`multiMessageEnabled` belongs to the AI Engine and can affect multiple
supported surfaces; it is not a Discord Expression Control.

Current defaults:

* Emoji reactions: on
* GIF follow-ups: on
* Server stickers: on
* Custom emojis: on
* Poll creation: on

Core profile defaults include:

* Presence values: `online`, `idle`, `dnd`, `offline`
* Default status text behavior if unset

Conversation scope notes:

* Discord DM text history is scoped to that user DM with the bot
* Discord server text history is scoped to the current channel, not the whole guild
* Discord voice chat uses the active connected voice session/channel context

## WhatsApp module settings

* The shared Verba number uses a secure authorization link to choose a verb.
* Text, images, voice, reply context, image generation, memory, and platform
  response streaming are supported.
* `/help`, `/ping`, `/generate`, `/status`, `/switch`, and `/disconnect` are
  supported.

## Telegram module settings

* Connect a BotFather token; Verba validates and encrypts it.
* DMs always address the verb. Groups require a mention/reply unless activated.
* `/activate_channel`, `/remove_channel`, `/reset`, `/generate`, `/dashboard`,
  `/ping`, and `/help` are registered.
* Photos/vision, memory, web search, social state, image generation, and
  edit-in-place response streaming are supported.
* Telegram Expression Controls cover emoji reactions, relevant GIF follow-ups,
  stickers, custom emoji, and native polls.

## Slack module settings

* Slack is dedicated-only: one owner-created Slack app is assigned to one Verb.
* Setup requires the app's Client ID, Client Secret, and Signing Secret, then a
  generated manifest and Slack OAuth authorization.
* Mentions and DMs work after installation; autonomous replies are limited to
  channels selected in **Active channels**.
* Expression Controls cover emoji reactions, relevant GIF uploads, known
  workspace emojis, interactive Block Kit polls, thread routing, and scheduled
  messages.
* Slash command toggles cover `/activate-channel`, `/remove-channel`, `/reset`,
  `/generate`, `/dashboard`, and `/ping`.
* Content and workspace capability bundles request additional Slack scopes when
  enabled.
* The old all-in-one selector command and a standalone Slack voice command are
  not installed.

## Twitch module settings

* One OAuth flow first authorizes the broadcaster and then requires a different
  Twitch account for the visible bot identity.
* Expression Controls cover chat-native tone, exact native emotes, eligible
  channel polls, live EventSub reactions, announcements, and shoutouts.
* Chat command toggles cover `!reset`, `!generate`, `!poll`, `!announce`,
  `!clip`, `!shield`, `!dashboard`, and `!ping`.
* Twitch reserves slash commands; custom Verb commands therefore use `!`.
* Moderation, stream, content, and engagement bundles expose only tools backed
  by the current OAuth scopes.
* Generated images and audio appear as public links because Twitch chat has no
  general media-upload API. Twitch GIF uploads and native bot calling are not
  exposed.

## Email module settings

* The module shows `{vanity}@verba.ink`; no owner OAuth or mailbox password is
  required.
* Owners can pause/resume the inbox and see account-wide daily usage.
* Daily outbound limits are Free `10`, Plus `50`, Pro `100`, and Ultra `500` per
  UTC day.
* Natural-language image requests can add an inline generated image. Voice
  Engine can add an audio attachment alongside the normal reply.
* Postmark handles SMTP delivery and inbound webhooks. Threading, per-Verb
  consent, unsubscribe, hard-bounce, and complaint suppression are enforced by
  the backend.
* Email does not expose expression or slash-command toggles.

## Custom messages settings

Customizable response strings include:

* Rate limit
* Reset success/empty messages (DM + server)
* AI/processing/image errors
* Channel management messages
* Permission and server-only errors
* Voice join/leave messages

Per custom message field:

* Max length: `500` chars at schema level

<Note>
  UI may show stricter editing caps for some textareas to keep messages concise.
</Note>

## Validation and save failures

Common save rejection reasons:

* Out-of-range numeric values
* Context/model limit above plan cap
* Oversized memory/knowledge/training content
* Invalid types for structured fields

If a save fails, check browser console + response payload first, then compare against limits on this page.

<CardGroup>
  <Card title="AI Engine Settings" icon="sliders" href="/guides/ai-engine">
    Practical tuning guidance for model behavior.
  </Card>

  <Card title="Memory and Knowledge" icon="database" href="/guides/memory-and-knowledge">
    How persistence layers interact in real usage.
  </Card>

  <Card title="Telegram Module" icon="paper-plane" href="/guides/telegram">
    Connect and operate a Telegram bot.
  </Card>

  <Card title="Social State" icon="heart" href="/guides/social-and-emotional-state">
    Configure temporary mood and Auto mode.
  </Card>
</CardGroup>


# Chat and groups
Source: https://docs.verba.ink/guides/chat-and-groups

How conversations, groups, DMs, and live updates work in Verba.

## Questions this guide answers

* When does a verb auto-reply in chats?
* What is the difference between a Group chat and a DM?
* Why did a message get blocked?
* What are the message and upload limits?
* How do invites, members, and permissions work?
* How does real-time syncing work across tabs/devices?

## Chat modes at a glance

| Mode  | Who can participate            | Typical use                                    |
| ----- | ------------------------------ | ---------------------------------------------- |
| Group | Multiple users + verbs         | Community rooms, roleplay, collaborative chats |
| DM    | 1:1 user + user or user + verb | Focused private conversations                  |

<Note>
  Group and DM conversations keep their own history, so context stays scoped to
  the current conversation.
</Note>

## Group basics

* Group owners can create up to `15` groups.
* New groups start with a `general` text channel.
* Invite links are generated per group and can be refreshed.
* Group roles are intentionally simple: `owner` and `member`.

### Ownership rules

* Only the owner can rename/update/delete the group.
* Only the owner can add/remove members directly.
* Only the owner can add/remove verbs in the group.
* Owners cannot leave their own group without transferring ownership first.

## Members and verbs

### Adding members

* Members added through invite codes join with member permissions.
* Inviting/joining triggers system events visible to the group.

### Adding verbs

You can add:

* Your own verbs.
* Public verbs from other users.

You cannot add:

* Private verbs you do not own.

## DMs

You can start DMs with:

* Another user.
* A verb.

For verb DMs:

* Public verbs are available to everyone.
* Private verbs are only available to the owner.

## Message flow and limits

### History pagination

When loading messages:

* Default fetch size: `50`
* Max fetch size: `200`

### Message requirements

A message must include at least one of:

* Text content
* A valid URL-style content body
* At least one attachment

### Anti-spam protection

Messages can be blocked when they look abusive, including:

* Mention flood
* Excessive zero-width character usage

<Warning>
  If users report random send failures, check for copied invisible characters
  and heavy mention payloads first.
</Warning>

### Upload limits

* General chat attachments: up to `30MB` per uploaded file
* Document text extraction: up to `20MB` per document
* Up to `4` attachments are analyzed for one model turn
* Supported uploads include images, video, audio, PDF, Word documents, and
  common text/code formats

For model understanding, Verba caps extracted text to `7000` characters per
attachment and `16000` characters total. Video understanding can sample up to
four frames per attachment and transcribe available audio. Very large or
unsupported media may still be stored as a normal file without full AI analysis.

<Note>
  Legacy image-only upload routes still use a `5MB` image limit. The paperclip
  file uploader in current app chat uses the broader `30MB` attachment path.
</Note>

## Reactions, edits, and deletes

* Users can edit/delete their own messages.
* Group owners (or users with manage message permissions) can moderate group messages.
* Reactions are supported for both group and DM messages.

## Real-time behavior (WebSocket)

Verba live chat uses WebSocket channels for:

* New message events
* Message edits/deletes
* Typing indicators
* Group/DM subscription updates

This is why messages appear instantly across open sessions when everything is healthy.

## Why a verb did not reply

Common causes:

* The verb was not configured to auto-respond in that context.
* The message was blocked by anti-spam rules.
* The sender does not have permission to post in the group.
* The verb or channel settings limit responses.

See [Troubleshooting](/guides/troubleshooting) for quick fixes.

<CardGroup>
  <Card title="Discord Deployment" icon="message" href="/guides/discord">
    Connect your verb to Discord with command controls and server settings.
  </Card>

  <Card title="Memory and Knowledge" icon="database" href="/guides/memory-and-knowledge">
    Understand how context and long-term memory affect response quality.
  </Card>
</CardGroup>


# Community
Source: https://docs.verba.ink/guides/community

Find help, share verbs, and get feedback.

## Join the Discord

The fastest way to get help is the community Discord.

* Invite link: [https://discord.gg/verba](https://discord.gg/verba)
* Ask questions in help channels
* Share your verbs in showcase

## Share and learn

* Post screenshots and chat logs
* Ask for feedback on personality
* Swap tips for prompts and settings

<Info>
  Be kind, be clear, and include screenshots when you report bugs.
</Info>

<Card title="Contact" icon="envelope" href="https://verba.ink/contact">
  Reach support if you need a private channel.
</Card>


# Credits and billing
Source: https://docs.verba.ink/guides/credits

Understand how credits work and plan usage.

## Credits in plain language

Credits are used for text, image, and voice generation. Bigger models, longer
outputs, and search-enabled workflows typically consume more.

## Plan-aware limits that affect credit usage

| Plan  | Monthly included allowance | Max context | Max tokens |
| ----- | -------------------------- | ----------- | ---------- |
| Free  | `0`                        | `50`        | `4096`     |
| Plus  | `2.5`                      | `75`        | `8192`     |
| Pro   | `5`                        | `100`       | `16384`    |
| Ultra | `10`                       | Unlimited   | `32768`    |

<Note>
  Included monthly allowance comes from your active tier. You can still top up
  credits separately.
</Note>

## Usage strategy

* Keep web search off for stable topics.
* Use smaller context for routine support replies.
* Reserve larger token limits for long-form answers.
* Use deterministic settings for troubleshooting to reduce retries.

## Expiring promotional credits

Some temporary campaigns grant credits with their own expiry. While active,
those promotional credits are spent before an equivalent amount of regular
balance and are tracked separately so a failed request can refund the correct
bucket. Unused promotional credit is removed at the campaign expiry shown in
the dashboard.

The current Discord token-rotation campaign, when offered, grants `0.17`
temporary credits and two days of effective Plus access for a verified token
reset on the same Discord application. It can be claimed once and is not an
ongoing monthly allowance.

## Common billing questions

<AccordionGroup>
  <Accordion title="Why did usage spike?">
    Typical causes are higher context, longer max tokens, web search, or a more expensive model selection.
  </Accordion>

  <Accordion title="Why does a model disappear?">
    Model access is tier-based. If tier or mapping changed, unavailable models are removed or remapped.
  </Accordion>

  <Accordion title="Do I lose access if Patreon is disconnected?">
    Active premium subscriptions can block Patreon disconnect until status is consistent.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Billing" icon="credit-card" href="https://verba.ink/billing">
    Buy credits and review purchase history.
  </Card>

  <Card title="Pricing" icon="tag" href="https://verba.ink/pricing">
    Compare plans and pricing.
  </Card>
</CardGroup>

<Info>
  If a model is unavailable, your current tier may not include it.
</Info>

<Card title="Billing and refunds" icon="receipt" href="/guides/billing-and-refunds">
  What to do if something looks off.
</Card>

<Card title="Plans and limits" icon="gauge" href="/guides/plans-and-limits">
  Full premium matrix: verbs, limits, streaming, and allowances.
</Card>


# Discord custom builder
Source: https://docs.verba.ink/guides/custom-builder

Build slash commands, events, timed automations, webhooks, tickets, modmail, and message flows with Verba's Discord builder.

## What the custom builder is

The **Discord Custom Builder** is Verba's no-code Discord workflow builder for:

* Slash commands
* Interaction events like buttons, selects, and modals
* Timed automations
* Webhook-driven flows
* Variables and reusable message templates
* Ticketing, modmail, welcome flows, and other Discord automations

It is designed for people who want BotGhost-style bot building inside Verba, but tied directly to their connected Verba Discord bot.

## What you can build right now

Current practical use cases:

* Ticket systems
* Thread-based modmail systems
* Welcome messages
* Reaction and button flows
* Channel and thread automations
* Role and moderation automations
* Logging and transcript flows
* Webhook intake flows
* Status and utility commands

Examples that are realistic with the current runtime:

* `Open Ticket` button -> create ticket channel -> post intro -> log it
* `Open Modmail` button -> create support thread -> escalate to case channel -> close with transcript
* `guild_member_add` event -> send welcome message into a configured channel
* Webhook POST -> create thread -> post intake details -> notify staff

## Builder project types

Every builder project is one of these:

* `Command`
* `Event`
* `Timed Event`

### Commands

Use command projects for slash commands like:

* `/ticket-panel`
* `/modmail-panel`
* `/rank`
* `/apply`

Command roots support:

* Chat input commands
* Guild/server-only commands
* DM/all-context command targets
* Command options like text, number, user, channel, role, boolean, attachment

### Events

Use event projects for Discord and builder-driven triggers like:

* `guild_member_add`
* `message_create`
* `message_reaction_add`
* `interaction_button`
* `interaction_select_menu`
* `interaction_modal_submit`
* `webhook_receive`

Best practice:

* Keep one event project focused on one job
* For advanced systems, use multiple event projects with the same trigger
* Example: duplicate guard project + open project + close project

### Timed Events

Use timed events for:

* Intervals
* Daily automations
* Weekly automations
* One-time scheduled runs

Examples:

* Sticky message refresh
* Scheduled announcements
* Daily reminders
* Cleanup jobs

## How saving works

The builder is **manual save**, not autosave.

That means:

* Changes on the canvas are local until you press save
* The bot uses the **last saved** version
* Unsaved edits do not go live

This is intentional so you can experiment without publishing partial logic.

## Core builder building blocks

The current builder supports three major block families:

* `Options`
* `Actions`
* `Conditions`

### Options

Options define slash command inputs:

* Text
* Number
* User
* Channel
* Role
* Choice / boolean
* Attachment

### Actions

Important action categories currently available:

* Advanced Message
* Message Actions
* Custom Variable Actions
* HTTP / Webhooks
* Loop Actions
* Other Actions
* Voice Actions
* Role Actions
* Channel Actions
* Thread and Forum Actions
* Server Actions

Examples:

* `Send or Edit a Message`
* `Set Variable`
* `Send an API Request`
* `Create a Channel`
* `Find a Channel`
* `Create a Thread`
* `Delete a Thread`
* `Create Transcript`
* `Add Roles`
* `Create Server Invite`

### Conditions

Current condition blocks include:

* `Comparison Condition`
* `Chance Condition`
* `Permissions Condition`
* `Role Condition`
* `Channel Condition`
* `Channel Exists`
* `User Condition`
* `Premium Check`
* `Switch`
* `For Each`

## Message builder

The message builder is used by message blocks like **Send or Edit a Message**.

It supports:

* Main message content
* Up to 10 embeds
* Embed title, description, author, footer, images, thumbnail
* Embed fields
* Buttons
* Saved message templates
* Live Discord-style preview

Use message templates when:

* The same panel should be reused in multiple projects
* You want one place to update a ticket/modmail panel
* You want consistent intros, logs, or prompts

## Variables

There are two kinds of values in the builder:

* **Custom variables** you define
* **Built-in runtime variables** the builder exposes automatically

### Custom variables

Custom variables can be scoped as:

* `global`
* `server`
* `channel`
* `user`

Examples:

* `VAR_modmail_hub_channel_id`
* `VAR_ticket_log_channel_id`
* `VAR_sticky_last_message_id`

### Built-in runtime variables

Built-in values are available automatically and do not need to be created in Data Storage.

Common examples:

* `{user}`
* `{user_name}`
* `{user_displayName}`
* `{user_id}`
* `{user_tag}`
* `{server}`
* `{server_id}`
* `{channel}`
* `{current_channel_id}`
* `{current_channel_name}`
* `{message_id}`
* `{interaction_custom_id}`
* `{button_custom_id}`
* `{select_values}`
* `{DEFAULT_SERVER}`
* `{last_bot_message_id}`
* `{created_channel_id}`
* `{created_thread_id}`
* `{created_role_id}`
* `{invite_url}`

### Channel lookup built-ins

When using `Find a Channel` or `Channel Exists`, these become available:

* `{channel_exists}`
* `{last_found_channel_id}`
* `{last_found_channel_name}`
* `{last_found_channel_mention}`

These are especially useful for:

* Duplicate ticket prevention
* Duplicate modmail prevention
* Existing case-channel checks

## Webhooks and HTTP requests

The builder supports two related capabilities:

* outbound HTTP requests
* inbound webhook events

### Outbound HTTP requests

The **Send an API Request** block goes through Verba's backend proxy layer.

That means:

* The bot/browser is not making the request directly
* Your frontend users are not exposing your backend IP through the builder UI
* Response values are returned to the builder runtime

Useful runtime values after a request:

* `{http_status}`
* `{http_body}`
* `{http_json}`

### Incoming webhook events

Use the `webhook_receive` event type for inbound automation.

A webhook event project can define:

* `webhookPath`
* `webhookSecret`
* `defaultServerId`

Webhook secrets can be provided as:

* `x-verba-builder-secret`
* `x-builder-secret`
* `Authorization: Bearer <secret>`

Webhook runtime values include:

* `{webhook_method}`
* `{webhook_path}`
* `{webhook_headers_json}`
* `{webhook_query_json}`
* `{webhook_body_json}`
* `{webhook_raw_body}`
* `{webhook_secret_valid}`

## Builder patterns that work well

The builder runtime is strongest when you structure flows as small focused projects.

### Good pattern: split advanced logic into multiple projects

For a ticket or modmail system, use:

* one command project to post the panel
* one event project as duplicate guard
* one event project to open the ticket/thread
* one event project to close it
* one event project to escalate or hand off

This is cleaner and matches how the current runtime executes best.

### Example: advanced modmail

A working thread-based modmail system typically looks like:

1. `/modmail-panel` command posts a panel
2. `interaction_button` with `modmail_open`
3. duplicate guard checks whether `modmail-{user_id}` already exists
4. open flow creates a thread in the configured hub channel
5. intro message posts buttons for close or escalation
6. escalation creates a dedicated case channel
7. close flow creates transcript -> logs -> deletes thread/channel
8. webhook flow can create a new modmail thread from external intake

## Starter systems

The builder includes starter systems so users do not have to begin from an empty canvas.

Current starter systems include:

* Advanced Ticketing
* Welcome System
* Leveling System

These are intended as starting points you can customize, not fixed templates.

## Current runtime behavior and limitations

This matters if you are building advanced bots.

### Anti-nuke authorization

The runtime marks expected Custom Builder actions as authorized before it asks
Discord to perform them. This lets saved workflows moderate members, create or
delete channels, update roles, send messages, and perform other configured
actions without triggering Verba's anti-nuke containment.

Actions performed with the same bot token outside Verba are not automatically
trusted. Review the [Discord anti-nuke guide](/guides/discord-safety) before
granting broad permissions.

### Important limitation: execution is still linear

The current compiler/runtime still executes projects in a **linear sequence**.

That means:

* It does not yet provide full arbitrary BotGhost-style branch routing by handles
* It is better to split complex flows across multiple projects instead of trying to force one huge graph

So if you need advanced ticketing, modmail, or escalation systems, prefer:

* duplicate guard project
* open project
* close project
* webhook intake project
* timed cleanup project

instead of one giant `if/else` tree

### Multiple incoming edges are blocked

The builder currently prevents multiple blocks from connecting into one target block.

This is intentional because the current execution model would become ambiguous and break logic.

### Unsaved edits are not live

If the bot still acts like old logic:

* make sure the project was saved
* confirm the correct command/event project is enabled
* wait briefly for Discord slash command registration if you changed command definitions

## Practical advanced systems you can build now

With the current runtime, these are realistic:

* Advanced ticketing
* Thread-based modmail
* Welcome systems
* Sticky messages
* Logging systems
* Case escalation systems
* Button-driven support systems
* Webhook intake systems

These are **not** full parity yet:

* Complex visual branching with arbitrary graph joins
* Fully general "build anything at all" logic graphs
* Full DM relay modmail out of the box

## Troubleshooting custom builder issues

<AccordionGroup>
  <Accordion title="The bot still uses old command content">
    The builder is manual-save. The live bot only uses the last saved project state.
  </Accordion>

  <Accordion title="The command appears in Discord but says the application did not respond">
    Make sure the connected bot runtime is actually online and the command project is enabled.
  </Accordion>

  <Accordion title="My button does nothing">
    Confirm the button `customId` matches the `interaction_button` event project's trigger `customId`.
  </Accordion>

  <Accordion title="A duplicate ticket/modmail check is not working">
    Use `Channel Exists` or `Find a Channel`, and make sure the naming pattern matches the created channel or thread name exactly.
  </Accordion>

  <Accordion title="My webhook event is not firing">
    Check the route, secret header, and whether the webhook event project is enabled.
  </Accordion>

  <Accordion title="Why can't I connect two blocks into one block?">
    The current runtime does not support multi-parent execution safely, so the builder blocks that connection.
  </Accordion>
</AccordionGroup>

## Recommended workflow

For reliable advanced systems:

1. Configure variables first
2. Build and save reusable message templates
3. Keep each event project focused on one job
4. Use explicit channel/thread naming conventions
5. Use `Channel Exists` before `Create Channel` or `Create Thread`
6. Save often and test with a live connected bot
7. Add logging blocks so failures are visible

## Related guides

<CardGroup>
  <Card title="Discord Deployment" icon="message" href="/guides/discord">
    Connect your Discord bot, configure intents, and understand routing.
  </Card>

  <Card title="Discord Command Reference" icon="terminal" href="/guides/discord-command-reference">
    Default built-in Verba slash commands and permission behavior.
  </Card>

  <Card title="Discord Anti-Nuke" icon="shield-halved" href="/guides/discord-safety">
    Learn how builder actions are authorized and external actions are contained.
  </Card>
</CardGroup>


# Discord deployment
Source: https://docs.verba.ink/guides/discord

Connect a verb to Discord and configure how, where, and when it responds.

## Questions this guide answers

* Why does my bot show "connection failed"?
* Why does the bot ignore messages in some channels?
* How do mention mode and AI-channel mode differ?
* How do Discord expression controls affect emoji, GIF, sticker, and poll behavior?
* How do I make bots talk to each other?
* Why does `/reset` work in DMs but fail in servers?
* Why does the bot say "application did not respond"?
* How does anti-nuke protection handle unauthorized bot-token actions?

## Before you connect

You need:

* A Discord application + bot user
* A valid bot token
* Privileged intents enabled in Discord Developer Portal

<Warning>
  Missing privileged intents is the most common cause of a bot that connects in
  dashboard UI but does not respond in Discord.
</Warning>

## Connect flow

<Steps>
  <Step title="Create bot in Discord">
    Use the Discord Developer Portal and create an app/bot.
  </Step>

  <Step title="Enable required intents">
    Enable Message Content and other required privileged intents in the bot settings.
  </Step>

  <Step title="Paste token in Verba">
    Open your verb's Discord module and connect with your token.
  </Step>

  <Step title="Invite the bot">
    Use the generated OAuth link to add it to your server.
  </Step>
</Steps>

<Note>
  Connected Discord bot tokens are protected in storage after connection. If a
  token is already attached to another verb, Verba will reject the duplicate
  link attempt until it is removed or re-linked correctly.
</Note>

### Temporary token-rotation reward

When the promotion is visible in the Discord module, an eligible account can
claim it once by resetting the token for the **same Discord application** and
reconnecting the new token. The current campaign grants two days of effective
Plus access and `0.17` temporary credits. The reward and any unused promotional
credits expire after two days; connecting a different bot does not qualify.

This is a temporary campaign. If the module no longer shows the offer, do not
assume it is still available.

## How response routing works

In server channels, a connected verb responds when at least one condition is true:

* The verb is directly mentioned
* The channel is marked as an AI channel
* A training keyword match is detected
* The bot is continuing an already-active bot-to-bot/autonomous exchange in that
  same channel

It does not respond when:

* Message includes `@everyone`/`@here`
* Message role-pings the bot's role directly
* User is on ignore/ban controls

Most unrelated bot messages are ignored. Bot-to-bot replies only continue when
the conversation is already active in that channel.

## Discord-native behavior

Recent Discord behavior is more native than basic text replies:

* Bots can prefer current-server custom emoji in replies and reactions
* If Discord allows external emoji in that channel, bots can also use custom
  emoji from other guilds they are in
* Bots can post server stickers when the moment fits
* Bots can send Tenor GIF follow-ups
* Bots can understand Discord polls, react to vote activity, and start native
  Discord polls when the situation fits

## Discord Expression Controls

The Discord module now includes a dedicated **Discord Expression Controls**
panel.

Current controls:

* Emoji Reactions
* GIF Follow-ups
* Server Stickers
* Custom Emojis
* Poll Creation

All of these are enabled by default for new bots and are Discord-specific.
Multi-message behavior is configured in the AI Engine and can also affect
supported non-Discord surfaces; it is not an expression control.

GIF and sticker follow-ups are relevance-checked before sending. Polls are
reserved for direct requests or a strong, active group-choice moment. Poll
discussion, capability questions, and ordinary one-line messages do not create
a poll, and cooldown plus duplicate checks prevent repeated polls.

## Mention mode vs AI-channel mode

### Mention mode

* Best for shared channels where bot noise should stay low
* Users ping the bot to trigger responses

### AI-channel mode (`/activate-channel`)

* Bot can respond without mentions in that channel
* Best for support/help channels or dedicated AI rooms

Use `/remove-channel` to disable AI-channel behavior.

## Autonomous and bot-to-bot behavior

When autonomous mode is enabled, Discord bots can:

* Chime into active conversations without a direct mention
* Reply to other bots in the same channel instead of only replying to humans
* React to messages and poll activity more naturally

Best results come from either:

* Enabling autonomous mode on both bots, or
* Mentioning both bots in the same channel to start the exchange

Autonomous frequency options are:

* `Human`
* `Default`
* `Active`
* `Chaotic`

## Slash commands available

Default command set:

* `/activate-channel`
* `/remove-channel`
* `/reset`
* `/generate`
* `/dashboard`
* `/vc-join`
* `/vc-leave`
* `/ping`

You can enable/disable each command in Discord module settings.

<Note>
  Discord activity/presence editing is available on all plans. You can keep
  `/vc-join` and `/vc-leave` enabled on any plan, but live voice-channel
  speaking still requires `Ultra`. On lower tiers, the bot answers with an
  in-character upgrade message instead of joining VC. Normal generated voice
  messages remain free.
</Note>

## Voice join without slash commands

Verbs do not always need `/vc-join`. If the bot is mentioned in a server and
the message is clearly asking it to join VC/call, it can use the same
voice-join path from normal chat.

Live VC speaking still requires `Ultra`. On lower tiers, the bot uses the same
personality-based upgrade response that the slash command path uses.

## Channel awareness

Discord replies are not blind to the room anymore.

* The bot gets the exact current channel as prompt context
* In servers, it only sees the channels it currently has permission to view
* Immediate recent conversation from the same channel is prioritized over older
  saved history

This helps replies, reactions, stickers, GIFs, and polls fit the current room
instead of sounding detached from the channel.

## Response streaming

On Ultra, turn on **Response Streaming** in the AI Engine to send a useful
partial reply early and edit the same Discord message until the answer is
complete. This is independent of multi-message mode: streaming updates one
in-progress message, while multi-message mode intentionally creates separate
final messages.

## Permissions behavior

* `/activate-channel` and `/remove-channel` require Administrator permission.
* `/reset` in server requires Administrator, server owner, or bot owner.
* `/reset` in DM is user-scoped and available without server permissions.
* Voice commands require Voice Engine enabled for the verb.
* Live voice-channel speaking requires `Ultra`. If a lower-tier bot gets
  `/vc-join`, `/vc-leave`, or a natural-language VC join request without an
  active voice session, it returns an in-character upgrade message instead of
  joining.

## Profile and presence settings

You can configure:

* Activity type (playing/listening/watching/custom)
* Activity text
* Presence (`online`, `idle`, `dnd`, `offline`)
* Slash command toggles

<Note>
  Activity text over dashboard limits is rejected or clamped. Keep status text short.
</Note>

## Server management tools

In the Discord module you can:

* View current server count
* Refresh profile/server data
* Leave specific servers
* Copy invite link quickly

## Custom builder

Verba also includes a dedicated **Discord Custom Builder** for creating:

* Slash commands
* Buttons, select menus, and modal flows
* Timed automations
* Webhook intake flows
* Ticketing and modmail systems
* Welcome and logging systems

Use the custom builder when you want your connected Verba bot to behave more like a purpose-built automation bot instead of only a conversational AI bot.

<Note>
  The builder is manual-save. Unsaved canvas changes are local and do not go live until you save.
</Note>

## Anti-nuke protection

Connected bots monitor their own privileged actions. Verba and saved Custom
Builder flows authorize expected actions before execution. An unexplained
administrative or moderation action is blocked where possible and causes the
bot to leave the affected server; lower-risk unauthorized messages or reactions
are removed or reverted where Discord permits.

This also covers relevant actions detected through Discord audit logs when the
same bot token is used outside Verba. Keep permissions minimal and rotate any
token that may have been exposed.

<Card title="Discord anti-nuke protection" icon="shield-halved" href="/guides/discord-safety">
  See guarded action categories, containment behavior, and limitations.
</Card>

## Typical failure patterns

<AccordionGroup>
  <Accordion title="Connection failed during token setup">
    Usually invalid token format, token already linked to another verb, or Discord rate limiting. Retry with a fresh token and verify it is not already attached elsewhere.
  </Accordion>

  <Accordion title="The application did not respond">
    Most often command timeout or missing Discord permissions in that channel. Check command toggle, channel permissions, and voice/image settings for the invoked command.
  </Accordion>

  <Accordion title="Bot won't create a poll">
    Poll Creation must be enabled in Discord Expression Controls, and the bot
    also needs Discord's native poll permission in that channel. If the channel
    does not allow polls, the bot falls back to normal text instead. Polls are
    only selected for a clear request or a strong group-choice moment, not every
    mention of the word "poll."
  </Accordion>

  <Accordion title="Bot keeps using plain emoji instead of server emoji">
    Turn on Custom Emojis in Discord Expression Controls and make sure the bot
    is allowed to use server or external emojis in that channel. When enabled,
    Verba prefers fitting custom emojis over plain Unicode.
  </Accordion>

  <Accordion title="Bot is online but does not answer messages">
    Check whether the message was a mention, in an AI channel, or matched training keywords. Also verify intents and that the sender is not ignored/banned.
  </Accordion>

  <Accordion title="/reset fails in server">
    Server reset requires elevated permissions (admin/server owner/bot owner). DM reset does not.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Discord Custom Builder" icon="wand-magic-sparkles" href="/guides/custom-builder">
    Build commands, buttons, webhook flows, tickets, modmail, and timed automations.
  </Card>

  <Card title="Discord Command Reference" icon="terminal" href="/guides/discord-command-reference">
    Exact behavior and permission rules for each slash command.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Fast fix checklist for connection failures, timeouts, and no-response bugs.
  </Card>

  <Card title="Discord Anti-Nuke" icon="shield-halved" href="/guides/discord-safety">
    Understand containment for unauthorized token actions.
  </Card>
</CardGroup>


# Discord command reference
Source: https://docs.verba.ink/guides/discord-command-reference

Exact slash command behavior, permissions, and expected responses.

## Command availability

Verba can register these slash commands:

* `/activate-channel`
* `/remove-channel`
* `/reset`
* `/generate`
* `/dashboard`
* `/vc-join`
* `/vc-leave`
* `/ping`

Each command can be toggled on/off in your Discord module settings.

<Note>
  This page covers Verba's built-in Discord slash commands. Custom-builder slash
  commands are documented separately in the
  [Discord Custom Builder](/guides/custom-builder) guide.
</Note>

<Note>
  Discord activity and presence editing are not plan-locked. `/vc-join` and
  `/vc-leave` can stay enabled on any plan, but live voice-channel speaking
  still requires `Ultra`. On lower tiers, the bot returns an in-character
  upgrade response instead of joining VC. Normal generated voice messages
  remain free.
</Note>

## Permission matrix

| Command             | Where     | Permission requirement                                                                                                 |
| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `/activate-channel` | Server    | Administrator                                                                                                          |
| `/remove-channel`   | Server    | Administrator                                                                                                          |
| `/reset`            | DM        | None (user-scoped DM reset)                                                                                            |
| `/reset`            | Server    | Administrator, server owner, or bot owner                                                                              |
| `/generate`         | Server/DM | Command enabled + image generation enabled                                                                             |
| `/dashboard`        | Server/DM | Command enabled                                                                                                        |
| `/vc-join`          | Server    | Command enabled + voice engine enabled + voice channel access. Live VC speaking requires `Ultra`                       |
| `/vc-leave`         | Server    | Command enabled + voice engine enabled. Disconnecting live VC still depends on the active voice session / `Ultra` path |
| `/ping`             | Server/DM | Command enabled                                                                                                        |

## Command behavior details

### `/activate-channel`

* Marks the current channel as AI-enabled.
* In AI-enabled channels, bot can reply without mentions.

### `/remove-channel`

* Removes the current channel from AI-enabled list.

### `/reset`

* In DM: clears DM conversation memory for that user context.
* In server: clears the current bot/server/channel conversation context, not
  every channel in the guild.

### `/generate`

* Generates an image from prompt.
* Optional reference image is supported.
* Optional aspect-ratio choices include `1:1`, `16:9`, `9:16`, `4:3`, `3:4`,
  `3:2`, `2:3`, `4:5`, `3:1`, and `21:9`.
* If image generation is disabled on the bot, command returns a disabled message.

### `/dashboard`

* Returns the dashboard URL.

### `/vc-join`

* Joins the requester's voice channel (or selected voice channel parameter).
* Fails if bot lacks voice permissions or voice runtime dependencies.
* Live VC speaking requires the `Ultra` plan.
* On lower tiers, the bot responds in personality that voice-channel speaking
  requires `Ultra`, that voice messages are still free, and that billing is at
  `https://verba.ink/billing`.

### Natural-language voice join

* Bots can also receive the same request from a normal mention message when the
  message is clearly asking them to join VC/call.
* This uses the same join rules as `/vc-join`; plan, permissions, and channel
  access still apply.

### `/vc-leave`

* Leaves current voice channel if connected.
* If there is no active voice session and the bot is not on `Ultra`, it returns
  the same in-character upgrade response instead.

### `/ping`

* Health/status check command with latency output.

## Command toggle behavior

When a command is disabled in dashboard:

* Invocation returns a disabled-command response.
* Command registration may take a short delay to reflect in Discord command picker.

Slash command toggles are separate from **Discord Expression Controls**. Turning
off a slash command does not disable reactions, GIFs, stickers, custom emojis,
polls, or multi-message Discord replies.

## Common command errors

<AccordionGroup>
  <Accordion title="This command is disabled for this bot">
    Re-enable the command in Discord module -> Slash Command Toggles.
  </Accordion>

  <Accordion title="You need Administrator permission">
    Server-only administrative commands require admin privileges in that guild.
  </Accordion>

  <Accordion title="This command can only be used in a server channel">
    Channel-management commands are server scoped and not available in DMs.
  </Accordion>

  <Accordion title="Image provider unavailable">
    Temporary upstream issue. Retry shortly or simplify prompt/reference image.
  </Accordion>

  <Accordion title="Voice runtime unavailable">
    Worker/runtime dependency issue. Restart worker and verify voice deps.
  </Accordion>
</AccordionGroup>

## Custom message templates

You can customize command/error text in the **Custom Messages** page.

Frequently used template variables:

* `{messagesPerMinute}`
* `{contextLabel}`
* `{channelMention}`
* `{verb}`
* `{user}`

<CardGroup>
  <Card title="Discord Deployment" icon="message" href="/guides/discord">
    Setup guide for connection, intents, profiles, and server routing.
  </Card>

  <Card title="Discord Custom Builder" icon="wand-magic-sparkles" href="/guides/custom-builder">
    Build custom slash commands, buttons, events, timed automations, and webhooks.
  </Card>

  <Card title="Image Generation" icon="image" href="/guides/image-generation">
    Compare image models, prices, references, and ratios.
  </Card>
</CardGroup>


# Discord anti-nuke protection
Source: https://docs.verba.ink/guides/discord-safety

How Verba contains unauthorized actions performed with a connected Discord bot token.

## What it protects against

Verba monitors actions performed by the connected bot account, including
actions initiated outside Verba with the same token. The goal is to prevent a
stolen or misused token from turning a hosted verb into a server-nuking bot.

## Privileged actions

For unexplained administrative or moderation actions, protection is
fail-closed: Verba blocks the in-process request where possible and leaves the
Discord server on the first detected unauthorized action.

Guarded categories include:

* Channel, thread, role, and guild changes
* Bans, kicks, prunes, timeouts, and member-role changes
* Permission overwrites, invites, and webhooks
* Emoji, sticker, soundboard, scheduled-event, stage, AutoMod, and onboarding changes
* Message deletion, pinning, integrations, and application-command permission changes

Audit-log monitoring also detects relevant actions performed with the bot token
outside the normal Verba runtime.

## Lower-risk actions

Unauthorized lower-risk self-actions, such as messages, edits, or reactions,
are removed or reverted where Discord permits instead of immediately making the
bot leave the server.

<Note>
  A message may be deleted after detection, but recipients may already have
  seen it. Discord does not provide a universal way to undo that exposure.
</Note>

## Command Builder actions

Verba and the Discord Custom Builder mark expected actions as authorized before
executing them. Legitimate workflows can therefore create channels, moderate
members, send messages, and perform other configured actions without triggering
anti-nuke containment.

## What this does not replace

Anti-nuke is defense in depth, not a reason to over-permission a bot.

* Grant only the Discord permissions the verb needs.
* Never share or commit a bot token.
* Rotate a token immediately if it may be exposed.
* Review Discord audit logs after suspicious activity.

<CardGroup>
  <Card title="Discord deployment" icon="discord" href="/guides/discord">
    Connect and permission a Discord bot safely.
  </Card>

  <Card title="Custom Builder" icon="wand-magic-sparkles" href="/guides/custom-builder">
    Build authorized commands and automations.
  </Card>
</CardGroup>


# Use a Verb by email
Source: https://docs.verba.ink/guides/email

Give your Verb a private email address for natural, threaded conversations.

## Your Verb's email address

Every eligible Verb can have an address based on its vanity:

```text theme={null}
{vanity}@verba.ink
```

For example, `lunaveyne_8wa` becomes:

```text theme={null}
lunaveyne_8wa@verba.ink
```

There is no mailbox password or OAuth connection to complete. The Email page
shows the address, whether it is active, and your account's daily usage.

## How it works

1. Send an email to the Verb's address.
2. The Verb reads the message and replies in the same conversation.
3. Future replies stay connected to that email thread.

The Verb uses its normal personality, knowledge, memory, and character settings.

## Sender name and profile picture

Replies use the Verb's name and address, for example:

```text theme={null}
Luna Veyne <lunaveyne_8wa@verba.ink>
```

Email providers decide which sender picture appears in an inbox. Verba cannot
force Gmail, Outlook, Apple Mail, or another provider to display a custom avatar
for one message, but the message still uses the Verb's name and address.

## Enable or pause email

* Choose **Resume inbox** to let the Verb receive and answer mail.
* Choose **Pause inbox** to stop the Verb from generating email replies.
* Changing a Verb's vanity changes its active email address.
* Reserved addresses such as `support@verba.ink` and `no-reply@verba.ink` are
  not assigned to Verbs.

## Consent and unsubscribe

The first email you send opts you in only for that Verb. It does not give every
Verb permission to email you.

You can stop future messages at any time by:

* Selecting the unsubscribe link in an email
* Replying with `STOP`, `UNSUBSCRIBE`, or `REMOVE ME`
* Marking the message as spam

Hard bounces and spam complaints also stop future proactive messages. Normal
incoming mail does not automatically re-enable someone who unsubscribed.

## Daily limits

The limit is shared across all email-enabled Verbs on your account and resets
each UTC day.

| Plan  | Emails per day |
| ----- | -------------: |
| Free  |           `10` |
| Plus  |           `50` |
| Pro   |          `100` |
| Ultra |          `500` |

Each delivered recipient uses one email. When the limit is reached, Verba keeps
the incoming message but does not generate or send a reply.

## Images and voice messages

Email uses natural language instead of commands:

* Ask the Verb to generate an image and it can attach the result inline below
  the normal reply when Image Engine is enabled.
* Ask for a voice message, or enable Voice Engine, and an audio attachment may
  be sent alongside the normal text reply.
* If you ask about the Verb's appearance, Verba can use its profile picture and
  banner as visual references.

There is no standalone voice command and email does not support native calling.

## Attachments and safety

* Generated email attachments are limited to 7 MB.
* Unsafe executable attachments are rejected.
* Incoming attachments are only shown to the AI after they pass the configured
  safety checks.
* Messages from automated systems are filtered to help prevent email loops.

## Privacy and conversation context

Email context is kept separate by sender, Verb, and thread. It is not shared
with every person who contacts the Verb. When Auto Memory is enabled, useful
details from eligible conversations can become long-term memories.

## Important limitations

* Email is not a full mailbox or webmail application.
* Email does not support reactions, live typing, native polls, or native calls.
* The receiving email provider controls the inbox sender picture.
* Verba cannot automatically change DNS or mail-server settings for your domain.
* Proactive emails can only be sent to contacts who have active consent for that
  Verb.

<CardGroup>
  <Card title="Plans and limits" icon="gauge" href="/guides/plans-and-limits">
    Compare account limits, including daily email quotas.
  </Card>

  <Card title="Image generation" icon="image" href="/guides/image-generation">
    Learn how generated images work.
  </Card>

  <Card title="Voice and audio" icon="microphone" href="/guides/voice-and-audio">
    Configure optional audio attachments.
  </Card>

  <Card title="Memory and knowledge" icon="database" href="/guides/memory-and-knowledge">
    Keep your character consistent everywhere.
  </Card>
</CardGroup>


# FAQ
Source: https://docs.verba.ink/guides/faq

High-frequency questions across API, Discord, memory, billing, and account settings.

## Top support answers

* How does the API work: create API key -> call `POST /v1/response` with `character` + `messages` -> reuse `session_id`.
* Where to set system instructions: Dashboard -> Bot -> AI Engine -> Behavior (`systemInstructions`, max `8000` chars).
* Plan limits: Free `50/4096`, Plus `75/8192`, Pro `100/16384`, Ultra `unlimited/32768` (short-term memory/max tokens).
* Messages per minute are unlimited on every plan. Verbs by plan: Free `5`,
  Plus `10`, Pro `20`, Ultra `40`.

## Product basics

<AccordionGroup>
  <Accordion title="Can I keep a verb private?">
    Yes. Private verbs are only accessible by the owner. Public verbs can be discovered and used by others.
  </Accordion>

  <Accordion title="Why do replies consume credits?">
    Credits cover model inference and processing. Longer context and larger outputs consume more.
  </Accordion>

  <Accordion title="Can I use Verba outside Discord?">
    Yes. Use Verba app chat, the shared WhatsApp module, or a connected Telegram
    bot. Pro and Ultra accounts can also use the public API at `api.verba.ink`.
  </Accordion>

  <Accordion title="Do I need a paid plan to use the API?">
    Yes. Public API access is available on Pro and Ultra plans.
  </Accordion>
</AccordionGroup>

## Discord FAQ

<AccordionGroup>
  <Accordion title="Why does the bot not answer unless pinged?">
    In server channels, the bot replies when mentioned, when channel is marked AI-enabled, or when a training keyword rule triggers.
  </Accordion>

  <Accordion title="How do I make it answer without mention in one channel?">
    Use `/activate-channel` in that channel.
  </Accordion>

  <Accordion title="How do I stop auto replies in a channel?">
    Use `/remove-channel`.
  </Accordion>

  <Accordion title="Can bots talk to each other?">
    Yes. The cleanest setup is to mention both bots in the same channel or
    enable autonomous mode on both so they can keep the exchange going.
  </Accordion>

  <Accordion title="Can bots use server emojis, stickers, GIFs, and polls?">
    Yes, through Discord Expression Controls. Those controls are enabled by
    default, but Discord permissions in that channel still matter.
  </Accordion>

  <Accordion title="Why did the bot send text instead of making a poll?">
    The bot can only create native Discord polls in channels where it has poll
    permission. If polls are disabled or the channel blocks them, it falls back
    to a normal text reply. It also reserves polls for a direct request or a
    strong group-choice moment, with cooldown and duplicate protection.
  </Accordion>

  <Accordion title="Do I need /vc-join every time?">
    No. Ultra bots can also join voice chat from a clear normal message asking
    them to join VC/call.
  </Accordion>

  <Accordion title="Why does /reset fail in server?">
    Server reset requires admin/server-owner/bot-owner permission.
  </Accordion>

  <Accordion title="What happens if somebody misuses my connected bot token?">
    Verba monitors privileged actions by the bot account. Unexplained admin or
    moderation actions trigger fail-closed containment and the bot leaves the
    affected server; lower-risk messages/reactions are removed where possible.
    Rotate any exposed token immediately.
  </Accordion>
</AccordionGroup>

## WhatsApp and Telegram FAQ

<AccordionGroup>
  <Accordion title="Does WhatsApp need to be relinked after every restart?">
    No. The shared gateway's linked-device state persists across normal server
    restarts. Relink only after logout, device revocation, or session invalidation.
  </Accordion>

  <Accordion title="How do I connect Telegram?">
    Create a bot with `@BotFather`, paste its token in the Telegram module, and
    add it to a group or open its DM. Verba validates the token, sets a secure
    webhook, and registers its commands.
  </Accordion>

  <Accordion title="Why does Telegram answer in DMs but not my group?">
    Mention it, reply to one of its messages, or have a group admin run
    `/activate_channel`.
  </Accordion>

  <Accordion title="Which WhatsApp commands are available?">
    `/help`, `/ping`, `/generate &lt;prompt&gt;`, `/status`, `/switch`, and
    `/disconnect`.
  </Accordion>

  <Accordion title="Does Telegram support expression controls?">
    Yes. You can independently control reactions, relevant GIF follow-ups,
    stickers, custom emoji, and native polls. Multi-message replies are set in
    the AI Engine.
  </Accordion>
</AccordionGroup>

## Slack, Twitch, and Email FAQ

<AccordionGroup>
  <Accordion title="Why do I have to create a Slack app for each Verb?">
    Slack cannot make one installed bot appear as unrelated identities on each
    message. Verba therefore uses one dedicated owner-created Slack app per
    Verb. Paste its three app credentials, apply Verba's generated manifest,
    and finish with Slack OAuth.
  </Accordion>

  <Accordion title="Why does Twitch show two OAuth screens?">
    The first grant belongs to the broadcaster channel. The second grant must
    use a different Twitch account that becomes the visible bot username and
    profile picture in chat. No password or pasted bot token is required.
  </Accordion>

  <Accordion title="Why do Twitch commands start with an exclamation mark?">
    Twitch reserves slash commands for the platform. Verba's custom Twitch
    commands therefore use names such as `!generate`, `!poll`, and `!ping`.
  </Accordion>

  <Accordion title="Can Slack and Twitch send voice replies?">
    Yes, when Voice Engine is enabled, but there is no standalone voice
    command. Audio accompanies the normal AI reply: Slack uploads an audio
    file, while Twitch posts a playable link. Neither integration supports bot
    calling.
  </Accordion>

  <Accordion title="How do I use a Verb email address?">
    Enable the Email module and send mail to `{vanity}@verba.ink`. There is no
    owner OAuth flow. The deployment administrator must configure Postmark SMTP,
    inbound forwarding, and authenticated webhooks first.
  </Accordion>

  <Accordion title="What are the daily email limits?">
    Free `10`, Plus `50`, Pro `100`, and Ultra `500` outbound deliveries per UTC
    day. The quota is shared by all of the account owner's Email-enabled Verbs.
  </Accordion>
</AccordionGroup>

## Streaming and social-state FAQ

<AccordionGroup>
  <Accordion title="Is platform response streaming Ultra-only?">
    Yes. Edit-in-place replies on Discord, WhatsApp, and Telegram require Ultra.
    Public API SSE with `stream: true` is a separate Ultra feature.
  </Accordion>

  <Accordion title="Does social state rewrite personality or memory?">
    No. It is a temporary mood layer. Auto mode can consider important memories,
    but saved personality, facts, system instructions, and safety remain authoritative.
  </Accordion>
</AccordionGroup>

## Memory and knowledge FAQ

<AccordionGroup>
  <Accordion title="What is the difference between memory and knowledge?">
    Memory is compact persistent facts; knowledge entries are richer structured references/lore.
  </Accordion>

  <Accordion title="How many knowledge entries can one verb store?">
    Up to `50` entries.
  </Accordion>

  <Accordion title="Can Verba auto-save memory from chats?">
    Yes, with Auto Memory enabled and instructions configured.
  </Accordion>

  <Accordion title="Why has Auto Memory not saved anything recently?">
    It does not write on every turn. It waits for enough recent conversation,
    skips temporary or duplicate facts, and only sometimes attempts a memory.
    At 50 automatic entries it rolls out the oldest automatic entry instead of
    freezing; manual entries are preserved.
  </Accordion>

  <Accordion title="Why is it not using my docs correctly?">
    Improve knowledge entry quality (clear title/category/content), reduce ambiguity, and add training examples for recurring question patterns.
  </Accordion>
</AccordionGroup>

## API FAQ

<AccordionGroup>
  <Accordion title="How does the API work?">
    Create an API key, call `POST /v1/response` for text (or `POST /v1/image` for images), and reuse `session_id` for follow-up context.
  </Accordion>

  <Accordion title="How do I authenticate API requests?">
    Use `Authorization: Bearer vka_...` or `x-api-key`.
  </Accordion>

  <Accordion title="How does session memory work in API calls?">
    Reuse `session_id` to preserve context for the same caller + character.
  </Accordion>

  <Accordion title="Can I stream responses?">
    Yes with `stream: true` on `/v1/response` if the API key owner is on Ultra.
  </Accordion>

  <Accordion title="Can I pass system messages directly in /v1/response?">
    No. Character system/personality is applied automatically.
  </Accordion>

  <Accordion title="What are the main /v1/response limits?">
    Max `60` messages, max `4000` chars per message, max `20000` total chars, max `4` image URLs, and max `128` chars for `session_id`.
  </Accordion>

  <Accordion title="How many API keys can I keep active?">
    Up to `3` active API keys per account.
  </Accordion>
</AccordionGroup>

## Plans and premium FAQ

<AccordionGroup>
  <Accordion title="Which plans support streaming on /v1/response?">
    Streaming is available on Ultra. Free, Plus, and Pro streaming requests are rejected.
  </Accordion>

  <Accordion title="How many verbs can I create per plan?">
    Free: 5, Plus: 10, Pro: 20, Ultra: 40.
  </Accordion>

  <Accordion title="Do plans affect context and token limits?">
    Yes. Plan tier sets short-term memory and max response tokens. Ultra has
    unlimited short-term memory and a `32768` max-token limit.
  </Accordion>

  <Accordion title="Are messages per minute limited by plan?">
    No. Plan-level messages per minute are unlimited on Free, Plus, Pro, and
    Ultra. Endpoint-specific safety limits can still apply to sensitive actions.
  </Accordion>

  <Accordion title="Does buying credits increase the daily email quota?">
    No. Email delivery limits come from the account plan and reset daily at
    `00:00 UTC`; they are separate from the credit balance.
  </Accordion>

  <Accordion title="Where can I see the full plan matrix?">
    See the Plans and limits guide for complete tier-by-tier details.
  </Accordion>
</AccordionGroup>

## Account and security FAQ

<AccordionGroup>
  <Accordion title="How many API keys can I keep active?">
    Up to `3` active keys per account by default.
  </Accordion>

  <Accordion title="How long is a magic-link login valid?">
    Magic links expire after `20` minutes.
  </Accordion>

  <Accordion title="Can I disable 2FA later?">
    Yes. You can disable it from settings after verification.
  </Accordion>

  <Accordion title="Can I disconnect Patreon anytime?">
    Not while an active paid Patreon subscription is still linked.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Fix connection, timeout, and no-response issues.
  </Card>

  <Card title="Question Bank" icon="book-open" href="/guides/question-bank">
    Larger question-driven reference generated from backend/frontend behavior.
  </Card>

  <Card title="Telegram Module" icon="paper-plane" href="/guides/telegram">
    Connect Telegram and understand its commands and group routing.
  </Card>

  <Card title="Response Streaming" icon="bolt" href="/guides/response-streaming">
    Compare platform streaming with public API SSE.
  </Card>
</CardGroup>

<Card title="Plans and limits" icon="gauge" href="/guides/plans-and-limits">
  Premium tiers, usage limits, streaming, and allowances.
</Card>


# Create your first verb
Source: https://docs.verba.ink/guides/first-verb

Design personality, visuals, and behavior in one flow.

## 1. Define the essentials

Start with the basics: name, description, age, and language. These fields shape
how your verb is introduced and how it speaks.

<Info>
  Keep the description short and concrete. Focus on tone, role, and what the
  verb helps with.
</Info>

### Magic Builder or manual creation

Magic Builder accepts a plain-language description (up to `500` characters)
and creates a draft asynchronously. You can optionally let it use web search
and generate visuals. Use **Refine Prompt** or a suggestion chip if you want
help making the request more specific.

Choose manual creation when you already know the exact field values you want.
Both paths create a normal verb that you can edit afterward.

## 2. Build a visual identity

Upload an avatar and banner that match the personality you want users to feel.

<Note>
  In the create flow, inline avatar and banner uploads should be kept at
  `1MB` or smaller each. Larger files can trigger a create-request size error
  before the verb is saved.
</Note>

<Columns>
  <div>
    **Avatar**

    * Clear, centered subject
    * Works at small sizes
    * Consistent style with your banner
  </div>

  <div>
    **Banner**

    * Wider framing, more context
    * Reinforce the theme or mood
    * Optional but impactful
  </div>
</Columns>

## 3. Write the personality

Fill in core personality, backstory, beliefs, likes, and dislikes. This is the
primary source of behavior.

<CardGroup>
  <Card title="Core personality" icon="star">
    The non-negotiable traits and quirks.
  </Card>

  <Card title="Backstory" icon="book">
    Motivations that explain the personality.
  </Card>

  <Card title="Beliefs" icon="compass">
    Opinions and values that guide responses.
  </Card>

  <Card title="Likes and dislikes" icon="heart">
    Quick hooks for natural conversation.
  </Card>
</CardGroup>

## 4. Tune behavior

Set your AI engine controls to balance creativity and consistency. Start with
defaults, then iterate while chatting.

<Tip>
  If responses feel too generic, raise temperature slightly. If they drift off
  topic, lower it and reduce top-p.
</Tip>

The AI Engine also contains:

* **Response Streaming** on Ultra for edit-in-place replies on messaging platforms.
* **Social** controls for mood and conversation posture.
* Web search, reply style, multi-message timing, and context controls.

## 5. Test and iterate

Run live chats, adjust prompts, and refine until the personality holds under
real usage.

<Card title="AI engine guide" icon="sliders" href="/guides/ai-engine">
  Learn how each control changes behavior.
</Card>


# Getting around
Source: https://docs.verba.ink/guides/getting-around

A quick tour of where things live in Verba.

## The basics

Think of Verba like a studio. You have a dashboard, a creation space, and a
chat room. Most of what you need is two clicks away.

<CardGroup>
  <Card title="Dashboard" icon="house">
    Your home base for verbs, stats, and quick actions.
  </Card>

  <Card title="Create" icon="plus">
    Magic Builder for a prompt-driven draft, plus the full manual creation flow.
  </Card>

  <Card title="Chat" icon="comments">
    Test your verb and tweak it fast.
  </Card>

  <Card title="Settings" icon="gear">
    Profile, billing, and account preferences.
  </Card>

  <Card title="Explore" icon="compass">
    Discover public verbs and open their profiles or chats.
  </Card>

  <Card title="Modules" icon="puzzle-piece">
    Connect a verb to Discord, WhatsApp, Telegram, Slack, Twitch, or Email, or
    open the API documentation.
  </Card>
</CardGroup>

## Useful shortcuts

* Use search to jump to a verb fast.
* Pin the verbs you use the most.
* Keep a test chat open while editing personality.

<Tip>
  If you feel lost, open Quickstart again. It mirrors the creation flow.
</Tip>

## What to click first

1. Create a verb.
2. Open chat and test a few prompts.
3. Adjust personality and AI engine settings.
4. Add visuals, memory, and social state when the voice feels right.
5. Open Modules to deploy it to a messaging platform or use its API.

## Integration switcher behavior

The integration switcher lists Discord, WhatsApp, Telegram, Slack, Twitch,
Email, API, and Minecraft. API is a documentation shortcut: selecting it opens
`https://docs.verba.ink/guides/api` directly. It is not a provider connection
and does not count as a connected integration.

<Card title="Quickstart" icon="rocket" href="/quickstart">
  Run the full setup in a few minutes.
</Card>


# Image generation
Source: https://docs.verba.ink/guides/image-generation

Choose an image model, use reference images, and generate the right aspect ratio.

## Turn it on

Open **Dashboard -> Verb -> Image Engine** and enable image generation. The
selected model is used by app chat and supported platform commands such as
Discord `/generate`, Telegram `/generate`, Slack `/generate`, and Twitch
`!generate`. WhatsApp and Email can invoke generation from a clear
natural-language request.

Verba's image generation catalog is Puter-backed. Users do not need to provide
an Airforce account, an image-provider API key, or a separate provider login.

## Free model

**Verba Free Image** is the permanent user-facing name of the free option. It
is currently backed by **GPT Image 1** and is listed at `0` credits per image.

<Note>
  Provider mappings and the premium catalog can change over time. The Image
  Engine in the dashboard is the source of truth for models currently available
  to your account.
</Note>

## Aspect ratios

Ask for a named orientation such as `square`, `landscape`, `portrait`,
`banner`, or `ultrawide`, or choose an explicit ratio.

| Ratio  | Working size | Good for                     |
| ------ | ------------ | ---------------------------- |
| `1:1`  | `1024x1024`  | Avatars, square posts        |
| `16:9` | `1344x768`   | Landscape and widescreen     |
| `9:16` | `768x1344`   | Stories and phone wallpapers |
| `4:3`  | `1152x896`   | Classic landscape            |
| `3:4`  | `896x1152`   | Classic portrait             |
| `3:2`  | `1216x832`   | Photo landscape              |
| `2:3`  | `832x1216`   | Photo portrait               |
| `5:4`  | `1152x896`   | Compact landscape            |
| `4:5`  | `896x1152`   | Social portrait              |
| `2:1`  | `1408x704`   | Wide banners                 |
| `1:2`  | `704x1408`   | Tall posters                 |
| `3:1`  | `1536x512`   | Extra-wide banners           |
| `21:9` | `1536x640`   | Ultrawide scenes             |

Model providers may round or adapt a requested size to the nearest supported
resolution while preserving the intended orientation.

## Commands and provider delivery

Discord `/generate` accepts a required prompt, an optional aspect-ratio choice,
and an optional reference attachment. Telegram accepts `/generate <prompt>` and
uses the configured image model. Slack `/generate <prompt>` creates a native
Slack file upload. Twitch `!generate <prompt>` posts a public image link because
Twitch chat has no general image-upload endpoint. Email embeds the generated
image inline in the reply.

| Surface  | How the generated image is delivered         |
| -------- | -------------------------------------------- |
| Discord  | Native Discord attachment                    |
| WhatsApp | WhatsApp image message                       |
| Telegram | Native Telegram photo/media message          |
| Slack    | Native Slack file upload                     |
| Twitch   | Public image link in chat                    |
| Email    | Inline image attachment below the text reply |

Conversational instructions can provide ratio context where supported.

Verba can use up to four reference images internally. Use one clear reference
when likeness or composition matters; more references can make the instruction
ambiguous.

## Character appearance awareness

When a prompt explicitly refers to the Verb's own appearance, Verba can add the
Verb's current avatar and banner as visual references and include its visual
profile context in the generation prompt. Ordinary image requests that do not
refer to the character do not automatically force those references.

GIF follow-ups are separate from AI image generation. Discord, Telegram, and
Slack can use relevance-checked GIF expression controls. Twitch has no general
GIF upload control, and Email does not turn normal replies into GIF searches.

## Prompt tips

* Lead with the subject and action.
* Add medium/style, lighting, composition, and mood.
* State the intended ratio or destination.
* Say what must remain from a reference image.
* Remove conflicting styles if results drift.

<AccordionGroup>
  <Accordion title="Example prompts">
    - `Moody neon alley in rain, cinematic cyberpunk, 16:9`
    - `Soft watercolor mountain sunrise, warm tones, 3:2`
    - `Minimal flat logo mark, centered, transparent-looking background, 1:1`
  </Accordion>

  <Accordion title="Why generation can fail">
    The monthly allowance may be exhausted, the selected model may require a
    higher plan, the prompt/reference may be rejected, or the upstream provider
    may be temporarily unavailable. Retry once with a shorter prompt and no
    reference image to isolate the cause.
  </Accordion>
</AccordionGroup>

## Monthly allowances

| Plan  | Image generations per month |
| ----- | --------------------------- |
| Free  | `20`                        |
| Plus  | `50`                        |
| Pro   | `100`                       |
| Ultra | Unlimited                   |

Allowances reset with the monthly cycle. Per-image credit charges are separate
from the monthly count and depend on the selected model.

## Current model catalog and unit prices

Prices below are dashboard credit units **per image**. The catalog is sorted by
minimum plan and price; check the Image Engine before relying on a model in an
automated workflow.

| Minimum plan | Model                          | Credits/image |
| ------------ | ------------------------------ | ------------: |
| Free         | Verba Free Image (GPT Image 1) |           `0` |
| Plus         | DreamShaper                    |      `0.0006` |
| Plus         | Juggernaut Lightning FLUX      |      `0.0017` |
| Plus         | Stable Diffusion 3 Medium      |      `0.0019` |
| Plus         | Stable Diffusion XL 1.0        |      `0.0019` |
| Plus         | FLUX Schnell                   |      `0.0027` |
| Plus         | HiDream I1 Fast                |      `0.0032` |
| Plus         | HiDream I1 Dev                 |      `0.0045` |
| Plus         | Juggernaut Pro FLUX            |      `0.0049` |
| Plus         | GPT Image 1 Mini               |      `0.0050` |
| Plus         | Qwen Image                     |      `0.0058` |
| Plus         | GPT Image 2                    |      `0.0059` |
| Plus         | HiDream I1 Full                |      `0.0090` |
| Plus         | GPT Image 1.5                  |      `0.0090` |
| Pro          | Leonardo Lucid Origin          |      `0.0167` |
| Pro          | Seedream 3.0                   |       `0.018` |
| Pro          | Grok Imagine Image             |       `0.020` |
| Pro          | Imagen 4 Fast                  |       `0.020` |
| Pro          | FLUX.1 Krea Dev                |       `0.025` |
| Pro          | FLUX 2 Klein 4B                |       `0.030` |
| Pro          | FLUX 2 Klein 9B Base           |       `0.030` |
| Pro          | Wan 2.6 Image                  |       `0.030` |
| Pro          | Seedream 4.0                   |       `0.030` |
| Pro          | FLUX 2 Flex                    |       `0.030` |
| Pro          | FLUX 2 Pro                     |       `0.030` |
| Pro          | FLUX 2 Dev                     |       `0.030` |
| Pro          | Leonardo Phoenix 1.0           |       `0.038` |
| Pro          | Gemini 2.5 Flash Image         |       `0.039` |
| Pro          | Qwen Image 2.0                 |       `0.040` |
| Pro          | FLUX 1.1 Pro                   |       `0.040` |
| Pro          | FLUX.1 Kontext Pro             |       `0.040` |
| Pro          | Imagen 4                       |       `0.040` |
| Pro          | Imagen 4 Preview               |       `0.040` |
| Ultra        | Grok Imagine Image Quality     |       `0.050` |
| Ultra        | Imagen 4 Ultra                 |      `0.0602` |
| Ultra        | Ideogram 3.0                   |      `0.0602` |
| Ultra        | Gemini 3.1 Flash Image Preview |       `0.067` |
| Ultra        | FLUX 2 Max                     |       `0.070` |
| Ultra        | Qwen Image 2.0 Pro             |       `0.080` |
| Ultra        | FLUX.1 Kontext Max             |       `0.080` |
| Ultra        | Gemini 3 Pro Image Preview     |      `0.1351` |

## Public API limitation

`POST /v1/image` is intentionally narrower than the interactive Image Engine:
it currently accepts `1024x1024`, a prompt up to `1500` characters, `url`
response format, and up to four image URLs. Do not send the platform ratio
presets to that endpoint unless its API reference is updated to support them.

<CardGroup>
  <Card title="Plans and limits" icon="gauge" href="/guides/plans-and-limits">
    Compare monthly allowances and model access tiers.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Diagnose model, allowance, provider, and attachment failures.
  </Card>
</CardGroup>


# Magic Builder
Source: https://docs.verba.ink/guides/magic-builder

Create an editable verb draft from a short plain-language prompt.

## When to use it

Magic Builder is the fastest creation path when you know the concept but do not
want to fill every personality field manually. Open **Create** and choose the
Magic Builder method. Manual creation remains available for exact field control.

## Build a useful prompt

The prompt accepts up to `500` characters. Include:

* The character's role and goal
* Two or three defining traits
* Speaking style or vocabulary
* Important setting or backstory
* The audience or use case

Use a suggestion chip for a starting point or **Refine Prompt** to make an
existing idea more specific.

## Optional tools

* **Web Search** can ground the draft in fresh public information when the
  concept depends on current facts.
* **Image Generation** can create visual assets as part of the build.

Keep Web Search off for original characters and static lore. Turn Image
Generation off if you already have the correct avatar/banner or want to choose
a specific premium model later.

## What happens after submission

Creation runs as an asynchronous dashboard job. You can return to the dashboard
while Verba builds the result. When the job finishes, the new verb is a normal,
editable verb: review its personality, system instructions, visuals, model,
memory, and visibility before sharing it.

<Warning>
  Magic Builder produces a draft, not an unchangeable source of truth. Check
  generated factual claims and remove contradictory personality rules.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The builder rejected my request">
    Keep the prompt under `500` characters, remove unsafe or contradictory
    requirements, and try without optional web/image tools to isolate the failure.
  </Accordion>

  <Accordion title="The job takes longer than expected">
    Web search and image generation add external work. Check the dashboard job
    state before submitting the same request again.
  </Accordion>

  <Accordion title="The result feels generic">
    Add concrete traits, a speaking pattern, one motivation, and one constraint,
    then edit the generated personality or create a more specific draft.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Create your first verb" icon="user" href="/guides/first-verb">
    Review every part of the resulting verb.
  </Card>

  <Card title="Personality playbook" icon="star" href="/guides/personality-playbook">
    Turn a draft into a consistent personality.
  </Card>
</CardGroup>


# Memory and knowledge
Source: https://docs.verba.ink/guides/memory-and-knowledge

How context, long-term memory, training examples, and knowledge entries work together.

## Questions this guide answers

* Why does my verb forget details between messages?
* What is short-term context vs long-term memory?
* What should go into knowledge entries vs memory entries?
* How does URL scraping fill knowledge automatically?
* How do training examples and keywords influence replies?

## The four memory layers

### 1. Conversation context (short-term)

* Uses recent messages from the active conversation.
* Controlled by your `Model Context` setting.
* Higher context improves continuity but costs more tokens.

### 2. Long-term memory

* Manual memory items your verb can keep using over time.
* Best for durable facts and preferences.

### 3. Knowledge entries

* Structured lore/reference entries (title, category, content, importance).
* Best for world facts, policies, product facts, and evergreen docs.

### 4. Training examples

* Input/output examples for style and behavior shaping.
* Keyword matching can prioritize specific examples when relevant.

## Where system instructions fit

System instructions are not a memory entry type. They are the persistent
behavior policy prompt for the verb.

Where to configure:

* Dashboard -> Bot -> AI Engine -> Behavior
* Field: `systemInstructions`

Limit:

* `systemInstructions`: up to `8000` chars

Recommended split of responsibilities:

* System instructions: behavior rules, format constraints, refusal/uncertainty policy
* Knowledge entries: factual source material and documentation
* Long-term memory: durable user/world facts
* Training examples: preferred phrasing and style patterns

## Long-term memory limits

Per memory entry:

* `content`: up to `2000` chars
* `context`: up to `500` chars
* `importance`: `1..10`

Auto-memory settings:

* `autoMemoryEnabled`: on/off
* `autoMemoryInstructions`: up to `2000` chars

<Note>
  Auto-memory is selective, not guaranteed on every turn. The system saves when
  it detects durable information worth retaining.
</Note>

Current auto-memory behavior:

* It evaluates a recent window after eligible exchanges rather than writing on
  every message.
* It needs enough recent user-and-bot conversation to form a useful memory.
* It skips short, temporary, duplicate, or low-value information.
* Automatic memories are capped at `50`; before adding another, Verba removes
  the oldest automatic entry. Manually created entries are not pruned by this
  automatic rollover.
* Similarity checks prevent near-duplicate memories from consuming the list.

This means several normal conversations can pass without a new entry. A full
automatic list should continue rolling forward instead of becoming permanently
stuck.

## Knowledge entry limits

Per entry:

* `title`: up to `100` chars
* `content`: up to `8000` chars
* `category`: up to `50` chars
* `importance`: `1..10`

Per verb:

* Maximum knowledge entries: `50`

## Training data limits

Per example:

* `input`: up to `500` chars
* `expected`: up to `2000` chars
* Optional keywords: used for relevance matching

When a user message matches example keywords, those examples are prioritized in
prompt construction.

## URL scraping into knowledge

The knowledge page can scrape a URL and generate a draft entry.

Expected result:

* `title`
* `content`
* `category`

If AI structuring fails, Verba still attempts a basic extraction fallback so you
can edit and save manually.

## Session memory by surface

| Surface             | Memory keying behavior                                       |
| ------------------- | ------------------------------------------------------------ |
| Public API v1       | Uses `session_id` per caller + character                     |
| Discord DM          | Scoped to user-DM context                                    |
| Discord server text | Scoped to bot + guild + channel context                      |
| Discord voice chat  | Scoped to the active voice session/channel                   |
| App group/DM chat   | Scoped to group/DM conversation                              |
| WhatsApp            | Scoped to the active WhatsApp conversation or group          |
| Telegram            | Scoped to the current Telegram DM or group chat              |
| Slack               | Scoped to the dedicated connection + channel + thread + Verb |
| Twitch              | Scoped to the connected broadcaster channel + Verb           |
| Email               | Scoped to the sender + vanity recipient + email thread       |

When Auto Memory is enabled, eligible exchanges from Slack, Twitch, and Email
run through the same selective memory-contribution pipeline as other Verba
conversations. A new memory is still not guaranteed on every turn: temporary,
duplicate, and low-value details are skipped.

## Memory and social state

Memory and social state solve different problems. Memory stores durable facts;
social state records how the verb feels or behaves right now. When Social Auto
mode is enabled, it can consider up to a small set of the most important
long-term memories while adjusting the sliders gradually.

Do not encode permanent facts only in social-state context. Put the fact in
memory or knowledge, then use social state for the temporary reaction.

## What to store where

### Put this in long-term memory

* Stable personal preferences
* Ongoing commitments
* Persistent roleplay relationships

### Put this in knowledge entries

* Product facts and policies
* Rulebooks
* Canon lore
* Documentation snippets you want the bot to cite reliably

### Put this in training examples

* Desired phrasing style
* Tone and boundary examples
* Repeated Q/A patterns

## Common mistakes

<AccordionGroup>
  <Accordion title="Dumping full chats into memory">
    Store compact facts, not raw transcripts. Long noisy entries reduce retrieval quality.
  </Accordion>

  <Accordion title="Using knowledge for temporary plans">
    Time-sensitive details belong in conversation context, not permanent knowledge.
  </Accordion>

  <Accordion title="No keywords in training examples">
    Add targeted keywords so examples are picked when users ask matching questions.
  </Accordion>

  <Accordion title="Oversized auto-memory instructions">
    Keep instructions strict and concise. Long broad prompts increase noisy memory writes.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="AI Engine Settings" icon="sliders" href="/guides/ai-engine">
    Tune model context, creativity, and response behavior.
  </Card>

  <Card title="Bot Settings Reference" icon="book" href="/guides/bot-settings-reference">
    Field-by-field guide for all dashboard settings and limits.
  </Card>

  <Card title="Social and Emotional State" icon="heart" href="/guides/social-and-emotional-state">
    Add temporary mood without rewriting memory.
  </Card>
</CardGroup>


# Content moderation
Source: https://docs.verba.ink/guides/moderation

What Verba checks when you create or update a verb, group, or profile asset.

## Where moderation runs

Verba validates character text during creation and relevant profile updates.
The combined check can include the name, description, age, personality,
backstory, beliefs, preferences, system instructions, tags, knowledge entries,
and training examples.

Image moderation runs on uploaded verb avatars and banners, account profile
assets, and group avatars/banners. File type and size validation happens before
or alongside content analysis.

## Main blocked categories

* Sexual or exploitative content involving minors
* Hate speech, protected-group violence, and extremist promotion
* Characters designed to provide operational illegal-activity assistance
* Extreme graphic violence, hate symbols, or other prohibited image content

The checks are designed to preserve normal creative, fantasy, historical,
prevention, reporting, and survivor-support contexts where they do not promote
the prohibited behavior.

## Age-aware rules

Characters can represent different ages, but minors have stricter content
rules. A character under `18` cannot contain sexualized content, and a character
under `16` cannot be configured to use profanity/slang.

## Supported profile-image formats

Use JPG/JPEG, PNG, GIF, or WEBP. Dashboard upload routes also enforce their
surface-specific size limits before saving the final asset.

## If content is blocked

1. Read the returned reason; it usually identifies the affected category.
2. Remove ambiguous phrasing or imagery and try a simpler safe version.
3. Keep prevention/reporting context explicit when discussing sensitive topics.
4. Contact support with the timestamp and screenshot if safe content is still blocked.

<Warning>
  Do not repeatedly submit prohibited material to probe the filters. Serious or
  repeated violations may be logged for platform-safety review.
</Warning>

<CardGroup>
  <Card title="Visual identity" icon="image" href="/guides/visual-identity">
    Prepare avatars and banners that pass format and layout checks.
  </Card>

  <Card title="Account and security" icon="lock" href="/guides/account-and-security">
    Review privacy, uploads, and account protections.
  </Card>
</CardGroup>


# Notifications and privacy
Source: https://docs.verba.ink/guides/notifications-and-privacy

Understand verb visibility, community updates, and browser chat alerts.

## Verb visibility

* **Public** verbs can appear in Explore and can be used by other people.
* **Private** verbs are accessible only to their owner, including in app DMs
  and group selection.

Review visibility before adding personal knowledge, memories, or media to a
verb. A public profile is discoverable even though private account credentials
and connected-service tokens are not shown.

## In-app notification bell

The notification bell currently shows Verba product/community updates sourced
from the official Discord update feed. Read and dismissed state is stored per
account so it can remain consistent across devices. The list refreshes
periodically while the app is open.

The older general-purpose notification creation system is deprecated; do not
expect every chat reply, billing event, or character event to appear in the
notification bell.

## Chat alerts

App chat tracks unread activity for groups and DMs. Group mentions and replies
increment their alert badges even when other chat activity is quiet.

If the browser grants notification permission, a direct group mention can also
create a native browser notification. Browser settings control whether that
notification is displayed.

## Privacy basics

* Never paste Discord/Telegram bot tokens, Slack app secrets, Twitch tokens, or
  Postmark credentials into chats or knowledge entries.
* Revoke and rotate a token immediately if it is exposed.
* Use separate conversations when context should not carry across users or rooms.
* Keep a verb private while testing sensitive personality, memory, or knowledge.
* Delete or revise long-term memory that should no longer influence replies.
* Remember that Auto Memory can contribute durable facts from supported Slack,
  Twitch, and Email conversations when it is enabled.

<CardGroup>
  <Card title="Account and security" icon="lock" href="/guides/account-and-security">
    Protect sign-in, API keys, and connected services.
  </Card>

  <Card title="Memory and knowledge" icon="database" href="/guides/memory-and-knowledge">
    Decide what information should persist.
  </Card>
</CardGroup>


# Personality playbook
Source: https://docs.verba.ink/guides/personality-playbook

Make your verb sound consistent and alive.

## Start with a simple core

Pick 3 to 5 traits and write them like bullet points. Keep it short and clear.
Then expand with examples. You can always add depth later.

<Info>
  Great personalities are specific. "Helpful" is fine. "Helpful with dry
  humor" is better.
</Info>

## Write with examples

Give the model samples of how the verb should respond. Short examples are
perfect.

```txt theme={null}
User: Can you explain this like I am five?
Verb: Sure. Think of it like building with blocks...
```

## Balance tone and boundaries

* If the verb is playful, say where it should still be serious.
* If the verb is sarcastic, say when to avoid it.
* If the verb is formal, say when it can relax.

<AccordionGroup>
  <Accordion title="Do this">
    - Use concrete behaviors.
    - Add phrases the verb loves to use.
    - Describe how it reacts when confused.
  </Accordion>

  <Accordion title="Avoid this">
    * Contradicting traits.
    * Huge walls of text with no examples.
    * Instructions that fight the system prompt.
  </Accordion>
</AccordionGroup>

## Keep it consistent

If the voice feels off, reduce complexity before adding more. A tight core
beats a giant block of lore every time.

<Card title="AI engine" icon="sliders" href="/guides/ai-engine">
  Tune creativity after the personality feels stable.
</Card>


# Plans and limits
Source: https://docs.verba.ink/guides/plans-and-limits

Complete plan matrix for premium features, usage limits, and API behavior.

## Premium quick answers

* API access is available on Pro and Ultra plans (`/v1/response`, `/v1/image`).
* Monthly prices: Free `$0`, Plus `$5.99`, Pro `$10.99`, Ultra `$20.99`.
* Messages per minute are unlimited on every plan.
* Full matrix (`verbs/short-term-memory/max-tokens`): Free `5/50/4096`, Plus
  `10/75/8192`, Pro `20/100/16384`, Ultra `40/unlimited/32768`.
* Public API SSE (`stream: true`) and the separate AI Engine platform-streaming
  toggle are currently available on Ultra.
* Image generation monthly allowance: Free `20`, Plus `50`, Pro `100`, Ultra unlimited.
* Account-wide outbound Email allowance per UTC day: Free `10`, Plus `50`, Pro
  `100`, Ultra `500`.
* AI/Image/Voice engine model pickers show dynamic upgrade prompts when premium
  models are outside your current plan.
* Discord `/vc-join` and `/vc-leave` are currently `Ultra` features.

## Plan tiers

Verba currently supports four tiers:

* `free`
* `plus`
* `pro`
* `ultra`

Quick reference (context/tokens):

* Free: `50` / `4096`
* Plus: `75` / `8192`
* Pro: `100` / `16384`
* Ultra: Unlimited / `32768`

## Feature matrix

| Feature                                            | Free      | Plus        | Pro               | Ultra                     |
| -------------------------------------------------- | --------- | ----------- | ----------------- | ------------------------- |
| Monthly price                                      | `$0`      | `$5.99`     | `$10.99`          | `$20.99`                  |
| Monthly credit allowance                           | `0`       | `2.5`       | `5`               | `10`                      |
| Max verbs                                          | `5`       | `10`        | `20`              | `40`                      |
| Messages per minute                                | Unlimited | Unlimited   | Unlimited         | Unlimited                 |
| Short-term memory (model context)                  | `50`      | `75`        | `100`             | Unlimited                 |
| Max response tokens                                | `4096`    | `8192`      | `16384`           | `32768`                   |
| API access (`/v1/response`, `/v1/image`)           | No        | No          | Yes               | Yes                       |
| API streaming (`/v1/response` with `stream: true`) | No        | No          | No                | Yes                       |
| Platform edit-in-place streaming                   | No        | No          | No                | Yes                       |
| Default model tier access                          | Free      | Free + Plus | Free + Plus + Pro | Free + Plus + Pro + Ultra |
| Premium model pickers in AI/Image/Voice engines    | Limited   | Expanded    | Expanded more     | Full catalog access       |
| Watermark removal                                  | No        | Yes         | Yes               | Yes                       |
| Advanced AI flag                                   | No        | No          | Yes               | Yes                       |
| Discord `/vc-join` + `/vc-leave`                   | No        | No          | No                | Yes                       |
| VIP support                                        | No        | No          | No                | Yes                       |
| Image generations per month                        | `20`      | `50`        | `100`             | Unlimited                 |
| Outbound Verb emails per UTC day                   | `10`      | `50`        | `100`             | `500`                     |

<Note>
  These values are enforced by backend tier feature controls and can be updated
  over time.
</Note>

## What each limit changes

* `Max verbs`: how many verbs you can create on your account.
* `Messages per minute`: plan-level conversation throughput is unlimited. Smaller
  endpoint-specific safety limits can still protect sensitive actions.
* `Short-term memory`: max recent-message window your verb can use.
* `Max response tokens`: cap for generated response length.
* `Monthly credit allowance`: recurring included credit amount tied to tier.
* `Outbound Verb emails`: deliveries shared by all Email-enabled Verbs on the
  account and reset at the start of each UTC day.

## Behavior when you exceed limits

* Verb creation over your tier cap is rejected.
* Short-term memory above your plan cap is clamped or rejected depending on endpoint.
* Public API requests from Free or Plus accounts return a plan-upgrade error.
* Streaming requests from non-Ultra accounts return a plan-upgrade error.
* Platform response streaming and public API SSE are separate paths, but both
  currently require Ultra.
* Image generation stops when the account reaches its monthly allowance.
* Email replies stop before model generation when the account has no daily
  email units remaining.
* Endpoint-specific abuse controls can still return rate-limit responses even
  though every plan has unlimited messages per minute.

## Model access and tiering

Model availability is tier-controlled. If a selected model is not available for
your current tier, the system may remap/fallback to an allowed model.

In the dashboard, the AI Engine, Image Engine, and Voice Engine also show an
upgrade prompt with the number of additional premium models available above your
current plan.

## Patreon and plan sync

Premium tier is synced from Patreon membership data. On tier changes:

* Your account tier is updated.
* Model access can be adjusted.
* Monthly allowance logic follows tier/cycle rules.

If you unlink Patreon while a premium subscription is active, disconnection may
be blocked for account safety/billing consistency.

## Related guides

* [Credits and billing](/guides/credits)
* [Billing and refunds](/guides/billing-and-refunds)
* [AI engine settings](/guides/ai-engine)
* [Troubleshooting](/guides/troubleshooting)


# Plans quick reference
Source: https://docs.verba.ink/guides/plans-quick-reference

Current prices and limits for verbs, messages, memory, tokens, images, and email.

## One-line matrix

Format: `verbs/short-term-memory/max-tokens`

* Free: `5/50/4096`
* Plus: `10/75/8192`
* Pro: `20/100/16384`
* Ultra: `40/unlimited/32768`

## Expanded matrix

| Plan  | Price       | Verbs | Messages/min | Short-term memory | Max tokens | Image generations | Emails/day |
| ----- | ----------- | ----- | ------------ | ----------------- | ---------- | ----------------- | ---------- |
| Free  | `$0/mo`     | `5`   | Unlimited    | `50`              | `4096`     | `20/mo`           | `10`       |
| Plus  | `$5.99/mo`  | `10`  | Unlimited    | `75`              | `8192`     | `50/mo`           | `50`       |
| Pro   | `$10.99/mo` | `20`  | Unlimited    | `100`             | `16384`    | `100/mo`          | `100`      |
| Ultra | `$20.99/mo` | `40`  | Unlimited    | Unlimited         | `32768`    | Unlimited         | `500`      |

## Notes

* `stream: true` in the public API is Ultra-only.
* The per-verb Response Streaming toggle is separate from public API SSE and is
  also currently Ultra-only.
* API access is available on Pro and Ultra.
* Native Discord voice-channel calling is available on Ultra. Calling remains
  unavailable on integrations without native bot calling support.
* Monthly included credits are Free `0`, Plus `2.5`, Pro `5`, and Ultra `10`.
* Daily email limits are account-wide, count one unit per recipient delivery,
  and reset at `00:00 UTC`.

## Related

* [Plans and limits](/guides/plans-and-limits)
* [Credits and billing](/guides/credits)


# Question bank
Source: https://docs.verba.ink/guides/question-bank

Large question-driven reference checked against backend routes and frontend settings flows.

## About this page

This page is a high-volume Q\&A index built from real product behavior in the
backend and frontend codepaths.

Use it when users ask operational questions and you need fast, practical
answers.

## Quick high-signal answers

* API flow: create a Pro or Ultra API key -> call `POST /v1/response` -> reuse returned `session_id` for follow-ups.
* System instructions: set in Dashboard -> Bot -> AI Engine -> Behavior (`systemInstructions`, max `8000` chars).
* `/v1/response` auth: `Authorization: Bearer vka_...` or `x-api-key: vka_...`.
* Session memory: reuse `session_id` for follow-up calls.
* Plan limits (short-term memory/tokens): Free `50/4096`, Plus `75/8192`, Pro
  `100/16384`, Ultra `unlimited/32768`.
* Plan-level messages per minute are unlimited on every tier. Verb limits are
  Free `5`, Plus `10`, Pro `20`, and Ultra `40`.
* Platform streaming: AI Engine toggle for Discord, WhatsApp, and Telegram;
  available on Ultra and separate from Ultra API SSE.
* Telegram: connect a BotFather token; DMs always address the verb, while groups
  use mention/reply routing or `/activate_channel`.

## API questions

<AccordionGroup>
  <Accordion title="How does the API work?">
    Create a Pro or Ultra API key, call `POST /v1/response` with `character` + `messages`, then reuse the returned `session_id` to keep conversation memory. Use `stream: true` for SSE on Ultra.
  </Accordion>

  <Accordion title="How do I authenticate requests to api.verba.ink?">
    Send `Authorization: Bearer vka_...` or `x-api-key: vka_...`.
  </Accordion>

  <Accordion title="How do I call the text endpoint?">
    Use `POST /v1/response` with `character` and `messages`.
  </Accordion>

  <Accordion title="How do I call /v1/response with API key auth and session memory?">
    Use `Authorization: Bearer vka_...` (or `x-api-key`), send `character` + `messages`, and reuse `session_id` across calls. If omitted on first call, API returns a generated `session_id` you can keep using.
  </Accordion>

  <Accordion title="How do I generate images through API?">
    Use `POST /v1/image` with `character` and `prompt`.
  </Accordion>

  <Accordion title="What value goes in character?">
    A vanity slug/path/URL (for example `/v/my_slug`).
  </Accordion>

  <Accordion title="Does API support streaming?">
    Yes, `/v1/response` supports SSE when `stream: true` on Ultra.
  </Accordion>

  <Accordion title="Why does streaming return forbidden?">
    Streaming is Ultra-only; Free, Plus, and Pro requests return upgrade-required errors.
  </Accordion>

  <Accordion title="Does API keep session memory?">
    Yes, reuse `session_id` to continue context.
  </Accordion>

  <Accordion title="Can I pass system role messages?">
    No, system role is blocked on `/v1/response`.
  </Accordion>

  <Accordion title="Can I send images in /v1/response?">
    Yes, via `messages[].content` image parts or top-level `image_urls`.
  </Accordion>

  <Accordion title="How many image URLs can I attach?">
    Up to 4 combined per request.
  </Accordion>

  <Accordion title="Can I use tools/function calls?">
    Yes, request-scoped HTTP tools are supported with validation and limits.
  </Accordion>

  <Accordion title="What are /v1/response hard payload limits?">
    `messages`: max `60`; each message text max `4000` chars; total text max `20000` chars; combined `image_urls` max `4`; `session_id` max `128` chars; tools max `8` definitions and `2` executed calls per request.
  </Accordion>

  <Accordion title="How many API keys can I keep active?">
    Up to `3` active API keys per account.
  </Accordion>

  <Accordion title="Why do I get payload too large errors?">
    Request bodies have size guards; oversized JSON payloads are rejected.
  </Accordion>
</AccordionGroup>

## Plans and limits questions

<AccordionGroup>
  <Accordion title="What are Free/Plus/Pro/Ultra limits for memory, max tokens, verbs, and message rate?">
    Short-term memory/max tokens/verbs are Free `50/4096/5`, Plus
    `75/8192/10`, Pro `100/16384/20`, and Ultra
    `unlimited/32768/40`. Plan-level messages per minute are unlimited on all
    four tiers.
  </Accordion>

  <Accordion title="What are max model context and max response tokens by plan?">
    Free: `50` short-term memory, `4096` max tokens. Plus: `75`, `8192`.
    Pro: `100`, `16384`. Ultra: unlimited, `32768`.
  </Accordion>

  <Accordion title="Which plans support streaming on /v1/response?">
    Ultra supports `stream: true`. Free, Plus, and Pro do not.
  </Accordion>

  <Accordion title="How many verbs can I create per plan?">
    Free `5`, Plus `10`, Pro `20`, Ultra `40`.
  </Accordion>
</AccordionGroup>

## Discord questions

<AccordionGroup>
  <Accordion title="Why does my bot connect but not respond?">
    Most often missing intents, wrong routing mode, or command/channel permission issues.
  </Accordion>

  <Accordion title="How do I make it respond without pinging in one channel?">
    Use `/activate-channel` there.
  </Accordion>

  <Accordion title="How do I stop auto-replies in that channel?">
    Use `/remove-channel`.
  </Accordion>

  <Accordion title="Can the bot reply to other bots?">
    Most unrelated bot messages are ignored. An already-active bot-to-bot or
    autonomous exchange can continue in the same channel.
  </Accordion>

  <Accordion title="Why does /reset fail for regular members in a server?">
    Server reset requires elevated permissions.
  </Accordion>

  <Accordion title="Does /reset work in DMs?">
    Yes, DM reset is user-scoped.
  </Accordion>

  <Accordion title="Why does /generate fail?">
    Image generation may be disabled, prompt invalid, or provider temporarily unavailable.
  </Accordion>

  <Accordion title="Which aspect ratios does Discord /generate support?">
    `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `4:5`, `3:1`, and `21:9`, plus an optional reference attachment.
  </Accordion>

  <Accordion title="Why does 'The application did not respond' appear?">
    Usually command timeout or permission/runtime failure.
  </Accordion>

  <Accordion title="Can I hide/disable specific slash commands?">
    Yes, via command toggles in Discord module settings.
  </Accordion>

  <Accordion title="Can I update bot status/presence from dashboard?">
    Yes, status type/text/presence are configurable.
  </Accordion>

  <Accordion title="How do I remove bot from a specific server?">
    Use the server list in Discord module and leave server action.
  </Accordion>

  <Accordion title="Why do only some pings get a reply when many bots are tagged?">
    Multi-bot mention handling intentionally limits responding bots for stability.
  </Accordion>

  <Accordion title="Why did the bot leave after a privileged action?">
    Anti-nuke containment detected an unexplained bot-account admin/moderation
    action. Review audit logs and token access before inviting it back.
  </Accordion>
</AccordionGroup>

## WhatsApp and Telegram questions

<AccordionGroup>
  <Accordion title="Does WhatsApp survive normal Verba restarts?">
    Yes. Linked-device credentials are stored durably. Relink only after logout,
    device revocation, or session invalidation.
  </Accordion>

  <Accordion title="How do I connect Telegram?">
    Create a bot with `@BotFather`, paste the token into the Telegram module,
    and let Verba validate it, configure the webhook, and register commands.
  </Accordion>

  <Accordion title="What Telegram commands are available?">
    `/help`, `/ping`, `/dashboard`, `/generate`, `/reset`,
    `/activate_channel`, and `/remove_channel`.
  </Accordion>

  <Accordion title="What WhatsApp commands are available?">
    `/help`, `/ping`, `/generate &lt;prompt&gt;`, `/status`, `/switch`, and
    `/disconnect`.
  </Accordion>

  <Accordion title="What can Telegram Expression Controls enable or disable?">
    Emoji reactions, relevant GIF follow-ups, stickers, custom emoji, native
    polls can each be controlled from the Telegram module. Configure
    multi-message replies in the AI Engine.
  </Accordion>

  <Accordion title="Does platform response streaming require Ultra?">
    Yes. The AI Engine toggle edits a Discord, WhatsApp, or Telegram message in
    place on Ultra. Public API SSE with `stream: true` is separate and also
    Ultra-only.
  </Accordion>
</AccordionGroup>

## Slack, Twitch, and Email questions

<AccordionGroup>
  <Accordion title="What is the Slack dedicated-app flow?">
    Create one Slack app for the Verb, paste its Client ID, Client Secret, and
    Signing Secret into Verba, copy and apply the generated app manifest, then
    authorize the app with Slack OAuth and choose active channels.
  </Accordion>

  <Accordion title="Which Slack commands are installed?">
    `/activate-channel`, `/remove-channel`, `/reset`, `/generate`, `/dashboard`,
    and `/ping`. Voice audio is a normal-reply sidecar, not a Slack command.
  </Accordion>

  <Accordion title="How does Twitch connection work?">
    One OAuth flow authorizes the broadcaster first and a different, dedicated
    bot account second. The second account's Twitch profile is what viewers see
    in chat.
  </Accordion>

  <Accordion title="Which Twitch chat commands are available?">
    `!reset`, `!generate`, `!poll`, `!announce`, `!clip`, `!shield`,
    `!dashboard`, and `!ping`. Twitch does not allow third-party custom slash
    commands.
  </Accordion>

  <Accordion title="Can Twitch upload generated media directly into chat?">
    No. Generated images and audio are posted as public links. Twitch has no
    general chat file or GIF upload endpoint; native emote text is supported.
  </Accordion>

  <Accordion title="What does a Verb email look like?">
    The sender is `Persona Name <vanity@verba.ink>`. Generated images can be
    inline and generated voice can be attached alongside the normal text reply.
    The receiving inbox still controls the sender avatar it displays.
  </Accordion>

  <Accordion title="What limits Verb email?">
    The owner has one account-wide UTC-day quota: Free `10`, Plus `50`, Pro
    `100`, or Ultra `500`. Sending also requires per-Verb contact consent and a
    configured Postmark transport.
  </Accordion>
</AccordionGroup>

## Memory, knowledge, and training questions

<AccordionGroup>
  <Accordion title="How do system instructions work?">
    System instructions are persistent behavior rules for the verb. They define response policy and format, while knowledge/memory provide facts and training examples shape style.
  </Accordion>

  <Accordion title="Where do I set system instructions and what is the limit?">
    Set them in Dashboard -> Bot -> AI Engine -> Behavior (`systemInstructions`). Max length is `8000` characters.
  </Accordion>

  <Accordion title="How many knowledge entries can I store?">
    Up to 50 per verb.
  </Accordion>

  <Accordion title="How do I add docs quickly from a URL?">
    Use knowledge URL scrape to draft title/content/category.
  </Accordion>

  <Accordion title="What if URL scrape gives poor output?">
    Manually edit the draft entry and tighten structure before saving.
  </Accordion>

  <Accordion title="What is auto memory?">
    Optional automatic saving of durable facts from conversation history.
  </Accordion>

  <Accordion title="Why does auto memory not create an entry on every chat?">
    It is intentionally selective: it waits for enough recent user-and-bot
    context, runs probabilistically, skips duplicates, and can decide that no
    durable fact is worth storing.
  </Accordion>

  <Accordion title="What happens when automatic memory reaches 50 entries?">
    Verba removes the oldest automatic entry before adding a new one. Manual
    memories are not removed by that automatic rollover.
  </Accordion>

  <Accordion title="What should auto-memory instructions include?">
    Durable facts to keep; explicit exclusions for temporary/noisy details.
  </Accordion>

  <Accordion title="Why does my bot ignore training examples?">
    Add keywords and ensure examples match real user phrasing.
  </Accordion>

  <Accordion title="Can knowledge and memory conflict?">
    Yes. Keep one canonical source and remove outdated entries.
  </Accordion>

  <Accordion title="How does context size affect memory quality?">
    Larger context keeps recent flow better but costs more and can add noise.
  </Accordion>

  <Accordion title="Do memory entries have importance levels?">
    Yes, entries use importance scoring.
  </Accordion>

  <Accordion title="Should I store full transcripts in memory?">
    No. Store compact facts and reusable rules.
  </Accordion>
</AccordionGroup>

## Chat, groups, and realtime questions

<AccordionGroup>
  <Accordion title="How many groups can one user own?">
    Up to 15 owned groups.
  </Accordion>

  <Accordion title="Why did my message get blocked in group chat?">
    Anti-spam filters can block mention floods and invisible-character abuse.
  </Accordion>

  <Accordion title="What is the message history page size?">
    Default 50, capped at 200 per request.
  </Accordion>

  <Accordion title="Can I DM a private verb I do not own?">
    No, private verbs are owner-only.
  </Accordion>

  <Accordion title="Why are updates instant across tabs?">
    WebSocket subscriptions broadcast message/typing/update events in real time.
  </Accordion>

  <Accordion title="Can owner leave their own group?">
    No, owner must transfer ownership or delete the group.
  </Accordion>

  <Accordion title="Who can add/remove verbs in groups?">
    Group owner only.
  </Accordion>

  <Accordion title="Are message image uploads limited?">
    The current file uploader supports images, video, audio, PDF, Word, and
    common text/code formats up to `30MB` each. Document extraction is capped at
    `20MB`; legacy image-only controls retain a `5MB` limit.
  </Accordion>
</AccordionGroup>

## Social-state questions

<AccordionGroup>
  <Accordion title="What are the social sliders?">
    Willingness to talk, irritation, focus, energy, confidence, affection,
    playfulness, and curiosity. Each uses `-5..5` with `0.25` steps.
  </Accordion>

  <Accordion title="What does Social Auto mode do?">
    It gradually adjusts temporary mood from the recent exchange and a small
    set of important memories, without overriding personality or safety rules.
  </Accordion>
</AccordionGroup>

## Account, billing, and security questions

<AccordionGroup>
  <Accordion title="How many active API keys can I keep?">
    Up to 3 active keys.
  </Accordion>

  <Accordion title="Do revoked API keys keep working?">
    No, revocation is immediate.
  </Accordion>

  <Accordion title="How long does a magic link stay valid?">
    20 minutes.
  </Accordion>

  <Accordion title="Can I sign in with backup code for 2FA?">
    Yes. Backup codes are one-time use.
  </Accordion>

  <Accordion title="Can I disconnect Patreon anytime?">
    Active paid subscription linkage can block disconnect.
  </Accordion>

  <Accordion title="Why is a model missing in settings?">
    Tier gating: available model set depends on plan.
  </Accordion>

  <Accordion title="Why do requests fail with insufficient credits?">
    Credits are exhausted for the account/owner being billed for that request.
  </Accordion>

  <Accordion title="What happens when I delete my account?">
    Related entities and associations are cleaned up; some owned resources may transfer or be removed.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Bot Settings Reference" icon="book" href="/guides/bot-settings-reference">
    Full limits and field behavior for dashboard configuration.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Operational fix guide for the most common failures.
  </Card>
</CardGroup>


# Response streaming
Source: https://docs.verba.ink/guides/response-streaming

Send the beginning of a reply early, then edit it in place as generation continues.

## What the toggle does

On Ultra, turn on **Response Streaming** in **Dashboard -> Verb -> AI Engine**.
On Discord, WhatsApp, and Telegram, Verba sends the first useful part of a
reply as soon as it is available, then edits that same message until the final
text is complete.

This makes long replies feel faster without leaving duplicate partial messages
behind. The completed model response remains the authoritative final message.

## Supported surfaces

| Surface        | Behavior                                                               |
| -------------- | ---------------------------------------------------------------------- |
| Discord        | Sends one initial message, then edits it in place                      |
| WhatsApp       | Sends one initial message, then updates it as supported by the gateway |
| Telegram       | Sends one initial message, then edits it in place                      |
| Verba app chat | Uses its existing live chat/WebSocket response flow                    |
| Public API     | Uses separate SSE behavior described below                             |

## Platform streaming vs API streaming

These are two different features:

* The AI Engine toggle controls platform replies for the connected verb.
* `POST /v1/response` with `stream: true` uses Server-Sent Events (SSE) and is
  currently an Ultra API feature.

Both currently require Ultra, but enabling one does not enable the other.

## Reliability behavior

Verba waits for a useful partial sentence before showing the first update and
throttles later edits so it does not hammer platform APIs. If a provider cannot
stream before anything becomes visible, Verba falls back to the normal
single-message response path.

<Note>
  Streaming improves perceived speed; it does not make the model finish sooner.
  Web search, large context windows, and large outputs can still increase total latency.
</Note>

## When to turn it off

* You only want final, complete messages.
* A platform or proxy is aggressively rate limiting message edits.
* Your verb uses multi-message roleplay where separate messages are intentional.

<Card title="AI engine settings" icon="sliders" href="/guides/ai-engine">
  Configure response streaming, context, reply style, and web search together.
</Card>


# Connect Verba to Slack
Source: https://docs.verba.ink/guides/slack

Give one Verb its own Slack identity and choose where it can talk, react, and help.

## What Slack adds

Once connected, your Verb can:

* Reply to direct messages, mentions, channels, and threads
* Remember conversations using the same personality and memory as the rest of Verba
* Upload generated images, audio, files, and relevant GIFs
* React with emojis and use workspace emojis it actually knows
* Create interactive polls
* Schedule messages and use selected workspace tools when you allow them

## Each Verb gets its own Slack bot

Slack uses one app per Verb. This means two Verbs in the same workspace can have
different names, profile pictures, personalities, and permissions.

You create the app in Slack, then connect it to Verba. Verba never asks for your
Slack password or asks you to paste a bot token.

## Connect a Verb

<Steps>
  <Step title="Create a Slack app">
    Open [Your Apps in Slack](https://api.slack.com/apps?new_app=1), choose
    **Create New App**, then choose **From scratch**. Select the workspace where
    you want to use this Verb.
  </Step>

  <Step title="Copy the three values into Verba">
    In Slack's **Basic Information** page, copy the **Client ID**, **Client
    Secret**, and **Signing Secret** into the Verb's Slack page in Verba. Keep
    the two secret values private.
  </Step>

  <Step title="Copy the Verba setup into Slack">
    In Verba, select **Copy configured Slack manifest**. In your Slack app,
    open **App Manifest**, paste the setup, review it, and save it.
  </Step>

  <Step title="Choose the app's appearance">
    Set the Slack app's display name and upload the Verb's profile picture in
    Slack. Slack does not accept the picture directly inside the copied setup.
  </Step>

  <Step title="Connect and authorize">
    Return to Verba and select **Connect with Slack**. Approve the permissions
    in Slack. The app will then appear as its own bot in the workspace.
  </Step>

  <Step title="Choose where it can speak freely">
    Mentions and direct messages work after installation. Select the channels
    where the Verb may answer without being mentioned.
  </Step>
</Steps>

## Where the Verb replies

* A direct message talks to the Verb directly.
* Mentioning the Verb can trigger it in a channel it can access.
* **Active channels** are the only channels where it may join in on its own.
* **Thread Replies** keeps answers inside the thread where the conversation began.
* Verba does not automatically join every channel in your workspace.

## Permissions

Slack asks for additional permission only when you turn on a feature that needs
it. The available groups are:

| Permission group | What it allows                                                |
| ---------------- | ------------------------------------------------------------- |
| Conversation     | Messages, mentions, direct messages, and threads              |
| Content          | Images, files, audio, GIFs, reactions, and polls              |
| Moderation       | Managing messages sent by the app                             |
| Workspace        | Channels, bookmarks, pins, and canvases where Slack allows it |

A Slack bot normally cannot delete messages written by other people. Slack's
own permissions always take priority.

## Slack controls

These controls change Slack-specific behavior. Image generation, voice replies,
multi-message replies, and autonomous behavior are configured in the matching
Verba engine pages.

| Control            | What it does                                     |
| ------------------ | ------------------------------------------------ |
| Emoji Reactions    | Adds a fitting Slack reaction when one is useful |
| GIF Follow-ups     | Finds and uploads a relevant animated GIF        |
| Workspace Emojis   | Uses an exact workspace emoji it knows about     |
| Interactive Polls  | Posts a poll with buttons and live vote totals   |
| Thread Replies     | Keeps replies in the original thread             |
| Scheduled Messages | Allows native Slack scheduled messages           |

## Slack commands

Each command has its own toggle in the Slack module:

| Command              | What it does                                                           |
| -------------------- | ---------------------------------------------------------------------- |
| `/activate-channel`  | Allows autonomous replies in the current channel                       |
| `/remove-channel`    | Stops autonomous replies in the current channel                        |
| `/reset`             | Clears recent conversation context without deleting long-term memories |
| `/generate <prompt>` | Generates an image when Image Engine is enabled                        |
| `/dashboard`         | Shares the Verb dashboard link                                         |
| `/ping`              | Checks whether the Verb is online                                      |

There is no standalone voice command. When Voice Engine is enabled, a voice
message may be added alongside a normal reply when the Verb decides it fits.

## Images, GIFs, and voice messages

* Generated images arrive as Slack file uploads.
* GIFs arrive as Slack files when GIF Follow-ups is enabled.
* Voice messages are sent as audio files alongside the normal text reply.
* If you ask about the Verb's appearance, Verba can use its profile and banner
  as visual references.

Slack does not provide native voice calling for Verba.

## Memory and personality

Slack uses the Verb's personality, instructions, knowledge, training, model
settings, social state, and memory. Recent context stays separated by Verb,
channel, and thread. Auto Memory can save useful details when you enable it.

## Important limitations

* You must create and configure the Slack app yourself.
* Adding a new permission group may ask you to approve Slack permissions again.
* The Verb can only use channels and actions that Slack grants to its app.
* Slack does not provide native voice calling for Verba.

If setup fails, check that the three Slack values were copied correctly, the
manifest was saved, and the app was installed in the intended workspace.

<CardGroup>
  <Card title="Image generation" icon="image" href="/guides/image-generation">
    Learn how Verba uses your Verb's visual identity.
  </Card>

  <Card title="Voice and audio" icon="microphone" href="/guides/voice-and-audio">
    Configure optional voice messages.
  </Card>

  <Card title="Memory and knowledge" icon="database" href="/guides/memory-and-knowledge">
    Keep the same character consistent everywhere.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Fix common connection and permission problems.
  </Card>
</CardGroup>


# Social and emotional state
Source: https://docs.verba.ink/guides/social-and-emotional-state

Give a verb a temporary mood and let conversations influence it without rewriting its personality.

## What social state is

Social state is a temporary layer on top of the saved personality. It helps
explain why a verb is more talkative, focused, warm, or irritated right now
without changing its permanent instructions, knowledge, or facts.

Open **Dashboard -> Verb -> AI Engine -> Social** to configure it.

## Sliders

Every slider runs from `-5` to `5` in quarter steps (`0.25`). Zero is neutral.

| Slider              | Low end      | High end  |
| ------------------- | ------------ | --------- |
| Willingness to talk | Reserved     | Chatty    |
| Irritation          | Patient      | Irritated |
| Focus               | Distracted   | Locked in |
| Energy              | Tired        | Energetic |
| Confidence          | Unsure       | Confident |
| Affection           | Distant      | Warm      |
| Playfulness         | Serious      | Playful   |
| Curiosity           | Uninterested | Curious   |

You can also add up to `500` characters of context explaining the current
state, such as what happened or who it relates to.

## Manual mode

In manual mode, the values stay where you set them until you change them. Use
this for events, roleplay scenes, or a deliberate support tone.

## Auto mode

In auto mode, Verba can gradually adjust the sliders after eligible
conversations in app chat and supported Discord, WhatsApp, Telegram, Slack,
Twitch, and Email flows. It considers the recent exchange and a small set of
important long-term memories.

Auto changes are intentionally gradual: a normal update moves a value by no
more than about one point, and updates are rate limited so the mood does not
thrash between messages.

<Warning>
  Social state influences delivery; it does not override saved personality,
  factual knowledge, safety rules, or system instructions.
</Warning>

## How memory and mood work together

Memory stores durable facts. Social state describes the verb's current posture.
For example, a memory may store what happened and the state can record reduced
focus or increased irritation. Auto mode can use high-importance memories as
context, but it does not rewrite those memories.

## Good uses

* Make a usually energetic character temporarily tired.
* Let repeated helpful exchanges build warmth.
* Represent distraction during an ongoing story event.
* Make a support verb more focused during an incident.

<CardGroup>
  <Card title="Memory and knowledge" icon="database" href="/guides/memory-and-knowledge">
    Decide what should persist and what should remain temporary.
  </Card>

  <Card title="AI engine settings" icon="sliders" href="/guides/ai-engine">
    Tune the model settings that social state works alongside.
  </Card>
</CardGroup>


# System instructions
Source: https://docs.verba.ink/guides/system-instructions

How system instructions work, where to set them, limits, and how they interact with memory/knowledge/training.

## What system instructions are

System instructions are the verb's persistent behavior rules.

Quick facts:

* Set in Dashboard -> Bot -> AI Engine -> Behavior
* Field name: `systemInstructions`
* Limit: `8000` characters

They should define:

* how the verb should behave
* response format and tone constraints
* uncertainty policy (what to do when information is missing)
* boundaries and refusal style

They should not be used as a dump for raw documentation or long transcripts.

## Interaction with other configuration layers

| Layer                | What it should contain                            |
| -------------------- | ------------------------------------------------- |
| `systemInstructions` | Behavior rules and output formatting policy       |
| Training examples    | Input/output style patterns and phrasing examples |
| Long-term memory     | Durable facts/preferences from conversation       |
| Knowledge entries    | Structured factual/reference information          |
| Conversation context | Recent turns from active chat/thread/session      |

## Practical precedence model

Use this order for authoring:

1. Put behavior policy in system instructions.
2. Put canonical facts in knowledge entries.
3. Put durable user/world facts in long-term memory.
4. Use training examples for style and recurring patterns.

If these layers conflict, clean up older memory/knowledge entries and keep one
canonical source of truth.

## Best-practice template

```text theme={null}
Role:
- You are Verba Documentation Assistant.

Behavior:
- Be factual and concise.
- Do not speculate.

Output format:
- Start with a direct answer.
- Then provide short sections with bullets.
- Include numbered steps for procedures.

Uncertainty:
- If docs context is insufficient, say what is missing and ask for the exact page/topic.
```

## Common mistakes

<AccordionGroup>
  <Accordion title="Putting factual docs only in system instructions">
    Put facts in knowledge entries; keep system instructions focused on behavior policy.
  </Accordion>

  <Accordion title="Conflicting rules">
    Avoid mixing contradictory rules like "be very short" and "be extremely detailed" in the same instruction set.
  </Accordion>

  <Accordion title="No uncertainty policy">
    Include explicit fallback behavior for missing info to reduce hallucinations.
  </Accordion>

  <Accordion title="Overlong and vague instructions">
    Keep instructions concrete and testable; split long policy into clear bullets.
  </Accordion>
</AccordionGroup>

## Related guides

* [AI engine settings](/guides/ai-engine)
* [Memory and knowledge](/guides/memory-and-knowledge)
* [Bot settings reference](/guides/bot-settings-reference)


# Telegram module
Source: https://docs.verba.ink/guides/telegram

Connect a BotFather bot token for Telegram DMs, groups, commands, media, and streamed replies.

## What the Telegram module supports

Telegram verbs support:

* Direct messages and group chats
* Text and photo understanding
* Image generation
* Web search, memory, and social auto-state
* Emoji reactions, relevant GIFs, stickers, custom emoji, and native polls
* Multi-message replies configured through the AI Engine
* Edit-in-place response streaming on Ultra
* Slash commands registered with Telegram

## Before you connect

Create a bot with Telegram's `@BotFather` and copy its bot token. Treat that
token like a password: anyone holding it can control the Telegram bot.

## Connect the bot

<Steps>
  <Step title="Open the Telegram module">
    Open your verb, select **Modules**, then choose **Telegram**.
  </Step>

  <Step title="Paste the BotFather token">
    Verba validates the token with Telegram before saving it. A token already
    connected to another verb cannot be connected twice.
  </Step>

  <Step title="Finish connection">
    Verba encrypts the saved token, configures a secret webhook, and registers
    the supported commands.
  </Step>

  <Step title="Add the bot to a group or open its DM">
    DMs are ready immediately. In groups, mention or reply to the bot, or use
    `/activate_channel` to let it answer without a mention.
  </Step>
</Steps>

## Commands

| Command              | What it does                                          | Permission notes                         |
| -------------------- | ----------------------------------------------------- | ---------------------------------------- |
| `/help`              | Shows available Telegram commands                     | Everyone                                 |
| `/ping`              | Checks whether the bot is responding                  | Everyone                                 |
| `/dashboard`         | Opens the Verba dashboard                             | Everyone                                 |
| `/generate <prompt>` | Generates an image when image generation is enabled   | Everyone                                 |
| `/reset`             | Clears conversation history                           | Group admins in groups; available in DMs |
| `/activate_channel`  | Enables replies without mentions in the current group | Group admins                             |
| `/remove_channel`    | Returns the group to mention/reply routing            | Group admins                             |

## Reply routing

* In DMs, every incoming user message addresses the verb.
* In groups, the verb answers when it is mentioned, when somebody replies to
  it, or when the group has been activated.
* Messages are queued per chat and duplicate webhook updates are ignored.
* Very long responses are split into Telegram-safe chunks.

## Media and streaming

Photo messages can be passed to a vision-capable model. Image generation uses
the model selected in the Image Engine. On Ultra, enabling Response Streaming
lets Telegram receive an early partial reply that is edited into the final
answer.

## Telegram Expression Controls

The Telegram module includes controls for:

* Emoji Reactions
* GIF Follow-ups
* Stickers
* Custom Emojis
* Poll Creation

These controls are enabled by default for newly connected bots and can be
disabled individually. GIFs and stickers are checked for conversational
relevance before they are sent. Polls are created for direct requests or a
strong group-choice moment, with duplicate and cooldown protection so ordinary
conversation does not turn into poll spam.

Multi-message replies are configured in the AI Engine rather than Telegram
Expression Controls.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The token is rejected">
    Copy a fresh token from `@BotFather`, remove spaces, and confirm it belongs
    to the intended bot. Revoke it in BotFather if it may have been exposed.
  </Accordion>

  <Accordion title="The bot works in DMs but not in a group">
    Mention it or reply to one of its messages. A group admin can also run
    `/activate_channel`. Check Telegram group permissions if commands fail.
  </Accordion>

  <Accordion title="A photo was not understood">
    Select a vision-capable text model and retry with one clear image plus a
    specific question.
  </Accordion>

  <Accordion title="The bot did not create a poll">
    Make sure Poll Creation is enabled. The bot creates a native poll when you
    ask clearly or when a real group decision fits the conversation; merely
    mentioning polls or discussing the feature does not force one.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Response streaming" icon="bolt" href="/guides/response-streaming">
    Learn how partial replies are edited in place.
  </Card>

  <Card title="Image generation" icon="image" href="/guides/image-generation">
    Choose models, prompts, and aspect ratios.
  </Card>
</CardGroup>


# Troubleshooting
Source: https://docs.verba.ink/guides/troubleshooting

Fix common Verba issues fast with concrete checks and recovery steps.

## Fast triage checklist

1. Confirm you are logged into the correct account/workspace.
2. Hard refresh the page and retry once.
3. Check plan limits (context, tokens, credits, model availability).
4. Confirm your verb settings were actually saved.
5. Test with a minimal prompt in a clean chat/thread.

## Discord issues

<AccordionGroup>
  <Accordion title="Connection failed while linking Discord token">
    Verify token format, ensure the token is not already linked to another verb, and retry after a short delay if Discord is rate limiting requests.
  </Accordion>

  <Accordion title="The application did not respond">
    This usually means command timeout, missing channel permission, or a disabled slash command. Check command toggles and bot permissions in that server/channel.
  </Accordion>

  <Accordion title="/vc-join or /vc-leave looks locked in dashboard">
    Those voice channel commands are currently `Ultra` features. Normal Discord
    activity/presence editing is still available on all plans.
  </Accordion>

  <Accordion title="Bot only responds sometimes">
    In servers, bot response depends on routing: mention, AI channel, or keyword match. If none of those apply, no response is expected.
  </Accordion>

  <Accordion title="Bot won't create a poll">
    Poll Creation must be enabled in Discord Expression Controls, and the bot
    must have Discord's native poll permission in that specific channel.
    Without that permission, Verba falls back to normal text.
  </Accordion>

  <Accordion title="Bot uses plain emoji instead of server emoji">
    Turn on Custom Emojis in Discord Expression Controls and verify the bot can
    use server or external emojis in that channel. When enabled, Verba prefers
    fitting custom emojis over plain Unicode.
  </Accordion>

  <Accordion title="Bots are not talking to each other">
    Put both bots in the same channel and either mention both to start the
    exchange or enable autonomous mode on both. Bot-to-bot replies are
    channel-scoped, so starting them in one channel does not make them continue
    everywhere else in the server.
  </Accordion>

  <Accordion title="Bot replies in wrong places or too often">
    Remove AI channels with `/remove-channel` and keep mention-only behavior in shared channels.
  </Accordion>

  <Accordion title="The bot left after an admin or moderation action">
    Anti-nuke containment saw a privileged bot-account action that was not
    authorized by Verba or a saved Custom Builder flow. Check Discord audit
    logs, rotate the token if it was used elsewhere, review permissions, then
    invite the bot again.
  </Accordion>

  <Accordion title="/reset fails in server but works in DM">
    Server reset requires admin/server-owner/bot-owner level permission. DM reset is user scoped.
  </Accordion>
</AccordionGroup>

## Response quality issues

<AccordionGroup>
  <Accordion title="Replies are too short">
    Increase max tokens and use a fuller reply style. Also check whether your current plan caps output lower than expected.
  </Accordion>

  <Accordion title="Replies are too generic">
    Tighten system instructions, add focused training examples, and lower temperature.
  </Accordion>

  <Accordion title="Bot forgets earlier messages">
    Increase model context (within plan cap) and avoid splitting related topics across many disconnected chats.
  </Accordion>

  <Accordion title="Bot misses known docs/knowledge">
    Add or refine knowledge entries, improve titles/categories, and verify entries are active. For URL imports, scrape again and clean the generated draft.
  </Accordion>

  <Accordion title="Web search feels noisy or irrelevant">
    Disable web search for stable topics. Keep it for fresh/live data only.
  </Accordion>
</AccordionGroup>

## Performance and timeout issues

<AccordionGroup>
  <Accordion title="Responses are slow">
    Reduce context, disable web search, and test a lighter model. Long prompts + web search + high max tokens significantly increase latency.
  </Accordion>

  <Accordion title="Intermittent provider failures">
    Retries/backoff are built into the call path, but upstream outages still happen. Retry shortly and keep fallback models available in your plan tier.
  </Accordion>

  <Accordion title="Image generation fails randomly">
    Confirm the monthly allowance, model tier, and Image Engine toggle. Then
    retry with Verba Free Image, a shorter prompt, `1:1`, and no reference image
    to separate configuration from a temporary provider failure.
  </Accordion>
</AccordionGroup>

## WhatsApp and Telegram issues

<AccordionGroup>
  <Accordion title="WhatsApp linking disappears after a restart">
    Normal restarts retain the gateway's durable linked-device state. If it is
    disconnected, check whether WhatsApp revoked the linked device or somebody
    explicitly logged out before attempting a new link.
  </Accordion>

  <Accordion title="Telegram token is invalid or already connected">
    Copy a fresh token from `@BotFather`. A single Telegram token can only be
    connected to one verb. Revoke and regenerate any token that was exposed.
  </Accordion>

  <Accordion title="Telegram bot ignores group messages">
    Mention or reply to it, or have a group admin use `/activate_channel`.
    Confirm the bot has permission to read and send messages in that group.
  </Accordion>
</AccordionGroup>

## Slack, Twitch, and Email issues

<AccordionGroup>
  <Accordion title="Slack will not let me connect the app">
    Verify that all three credentials belong to the same Slack app, copy the
    latest configured manifest into that app, save its changes, and confirm the
    OAuth redirect exactly matches the URL in the manifest. Recopy the manifest
    after changing credentials or reconnecting a different app.
  </Accordion>

  <Accordion title="Slack mentions work but ordinary channel messages do not">
    Add that channel under **Active channels** in the Slack module. Verba does
    not listen autonomously in every workspace channel by default.
  </Accordion>

  <Accordion title="A Slack expression or command says permission is missing">
    Enable the matching capability bundle and complete the new Slack OAuth
    approval. Also verify the command is enabled and the app can access the
    current channel.
  </Accordion>

  <Accordion title="Twitch setup stops after authorizing my channel">
    Finish the second OAuth screen with a different Twitch account. That account
    is the visible chat bot; using the broadcaster account twice is rejected.
  </Accordion>

  <Accordion title="A Twitch poll, moderation, or stream action fails">
    Check the capability bundle, broadcaster scopes, moderator/channel
    eligibility, and whether the command is owner-only. Polls, predictions, and
    ad controls can also depend on the broadcaster's Twitch status.
  </Accordion>

  <Accordion title="My Twitch image or audio appears as a link">
    That is expected. Twitch chat has no general media-upload endpoint, so
    Verba posts generated media as a public link.
  </Accordion>

  <Accordion title="Email says delivery is not configured">
    The administrator must configure Postmark SMTP and enable the Email
    integration. Receiving replies additionally requires inbound forwarding and
    both authenticated Postmark webhook URLs.
  </Accordion>

  <Accordion title="A Verb email receives mail but does not reply">
    Check whether the inbox is paused, the daily account quota is exhausted, the
    sender previously unsubscribed or bounced, the vanity is reserved/unknown,
    or Postmark cannot reach the inbound webhook.
  </Accordion>

  <Accordion title="An email attachment was ignored">
    Inbound files enter model context only after the configured scanner approves
    the type and contents. Without `ATTACHMENT_SCANNER_URL`, they are excluded
    deliberately.
  </Accordion>
</AccordionGroup>

## Account and billing issues

<AccordionGroup>
  <Accordion title="Insufficient credits error">
    Top up credits or switch to a lower-cost model. Credits are charged to the account tied to the request/verb owner depending on surface.
  </Accordion>

  <Accordion title="Model not selectable">
    Your plan may not include that model tier. Choose an available model or upgrade.
  </Accordion>

  <Accordion title="API key works in dashboard but fails in API calls">
    Check header format (`Authorization: Bearer vka_...` or `x-api-key`), key revocation status, and whether you exceeded active key limits.
  </Accordion>

  <Accordion title="I got temporarily IP banned">
    Verba can temporarily block repeated request bursts or repeated blocked
    traffic. Stop retry loops, wait for the temp-ban window to expire, and send
    support the timestamp, your public IP if known, and the page/action that
    triggered it.
  </Accordion>
</AccordionGroup>

## Chat and group issues

<AccordionGroup>
  <Accordion title="Create verb fails with 'Request body too large'">
    The create flow sends avatar/banner images inline inside the request body.
    Keep inline avatar and banner files at `1MB` or smaller each, or create the
    verb first and upload profile images afterward.
  </Accordion>

  <Accordion title="Message send blocked">
    Anti-spam protections can block mention floods and invisible-character abuse. Remove unusual hidden characters and retry.
  </Accordion>

  <Accordion title="Uploads fail">
    Current app chat supports images, video, audio, PDF, Word, and common
    text/code files up to `30MB` per upload. Document text extraction is capped
    at `20MB`; legacy image-only upload controls still use `5MB`.
  </Accordion>

  <Accordion title="Group invite problems">
    Verify invite code freshness and that owner has not regenerated it recently.
  </Accordion>

  <Accordion title="Autonomous DMs are too frequent">
    Lower autonomous frequency or disable autonomous mode on that verb. Verba
    now stops repeated follow-up loops on the same silent DM thread, but a bot
    that is intentionally configured to be active can still message on its own.
  </Accordion>
</AccordionGroup>

## When to contact support

Contact support with:

* Exact timestamp (with timezone)
* Verb ID/vanity URL
* Surface (`Discord`, `chat`, `API`, `Slack`, `Twitch`, or `Email`)
* Integration details (`WhatsApp`, `Telegram`, or another provider) when applicable
* Error text + screenshot
* Repro steps from clean session

<CardGroup>
  <Card title="Contact Support" icon="envelope" href="https://verba.ink/contact">
    Share reproducible steps and timestamps for fastest resolution.
  </Card>

  <Card title="Community" icon="users" href="https://discord.gg/verba">
    Ask in community channels for quick operational help.
  </Card>
</CardGroup>


# Connect Verba to Twitch
Source: https://docs.verba.ink/guides/twitch

Bring a Verb into your stream for chat, moderation, stream tools, and community reactions.

## What Twitch adds

A connected Twitch Verb can:

* Chat with viewers in your channel
* React to follows, subscriptions, cheers, raids, and Channel Point events
* Create polls and announcements when Twitch allows it
* Help with moderation, including timeouts, bans, blocked terms, and AutoMod
* Use supported stream tools such as clips, markers, shoutouts, and stream details
* Keep the same personality, memory, knowledge, and visual identity it has elsewhere

## Why Twitch asks for two accounts

Twitch needs two separate authorizations:

1. Your **broadcaster account** gives the Verb permission to work in your channel.
2. A separate **bot account** is the name and profile picture viewers see in chat.

The two accounts must be different. Verba never asks for either password and you
do not need to paste a bot token.

<Note>
  Twitch controls the bot account's username, profile picture, and banner. Set
  those on Twitch so the public bot identity matches the character you want.
</Note>

## Connect Twitch

<Steps>
  <Step title="Prepare the bot account">
    Create or choose the Twitch account viewers should see as this Verb. Do not
    use your broadcaster account for the bot step.
  </Step>

  <Step title="Start in Verba">
    Open the Verb's Twitch page and select **Connect channel & bot with Twitch**.
  </Step>

  <Step title="Authorize your channel">
    Sign in as the broadcaster and approve the requested permissions.
  </Step>

  <Step title="Authorize the bot">
    Twitch opens a second authorization screen. Switch to the separate bot
    account, check the account name carefully, and approve chat access.
  </Step>

  <Step title="Choose features">
    Enable only the feature groups you want the Verb to use: conversation,
    moderation, stream tools, content, or engagement.
  </Step>
</Steps>

If the second authorization is interrupted, the Twitch page keeps the setup
pending so you can continue with **Authorize bot account with Twitch**.

## Twitch controls

| Control                   | What it does                                        |
| ------------------------- | --------------------------------------------------- |
| Chat-Native Tone          | Keeps replies concise and natural for live chat     |
| Native Emotes             | Uses Twitch emotes it actually knows                |
| Channel Polls             | Creates a native poll when your channel is eligible |
| Live Event Reactions      | Responds to supported community events              |
| Highlighted Announcements | Sends a Twitch announcement                         |
| Creator Shoutouts         | Sends an official Twitch shoutout                   |

Image generation, voice messages, multi-message replies, and autonomous behavior
are configured in the matching Verba engine pages instead.

## Twitch commands

Twitch reserves slash commands for Twitch itself, so Verba's custom chat commands
use `!`:

| Command                                      | What it does                                                       |
| -------------------------------------------- | ------------------------------------------------------------------ |
| `!reset`                                     | Clears recent channel context without deleting long-term memories  |
| `!generate <prompt>`                         | Generates an image and posts its link when Image Engine is enabled |
| `!poll Question \| Option one \| Option two` | Creates a native Twitch poll when available                        |
| `!announce <message>`                        | Posts a highlighted announcement                                   |
| `!clip`                                      | Creates a clip from the live stream                                |
| `!shield on` / `!shield off`                 | Changes Shield Mode                                                |
| `!dashboard`                                 | Shares the Verb dashboard link                                     |
| `!ping`                                      | Checks whether the Verb is online                                  |

Every command has its own toggle on the Twitch page.

There is no standalone voice command. When Voice Engine is enabled, a voice
message may be added beside a normal reply when the Verb decides it fits.

## Images, GIFs, and voice messages

* Twitch chat receives generated images as links because Twitch does not support
  general image uploads in chat.
* Twitch does not support general GIF uploads. Native Twitch emotes are still
  available when enabled.
* Voice messages are shared as playable links alongside the normal text reply.
* If a prompt refers to the Verb's appearance, Verba can use its profile picture
  and banner as visual references.

Twitch does not provide native voice calling for bots.

## Memory and personality

The Verb keeps its personality, instructions, knowledge, training, social state,
and memory on Twitch. Recent context is kept for the connected channel and Verb.
Auto Memory can save useful details when you enable it.

## Important limitations

* Custom Verba commands cannot use `/`; Twitch reserves slash commands.
* Twitch chat does not have Slack-style threads or reactions.
* Polls, predictions, moderation, and stream tools depend on Twitch permissions
  and channel eligibility.
* The bot must be a real, separately authorized Twitch account.
* Twitch does not provide native bot calling or audio participation.

If the connection fails, check that the broadcaster and bot accounts are
different and that you completed both authorization screens.

<CardGroup>
  <Card title="Image generation" icon="image" href="/guides/image-generation">
    Learn how Verba uses visual references.
  </Card>

  <Card title="Voice and audio" icon="microphone" href="/guides/voice-and-audio">
    Configure optional voice messages.
  </Card>

  <Card title="Memory and knowledge" icon="database" href="/guides/memory-and-knowledge">
    Keep your character consistent everywhere.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Fix common Twitch connection problems.
  </Card>
</CardGroup>


# Valley 3
Source: https://docs.verba.ink/guides/valley-3

Verba's free model for character roleplay, storytelling, and vision.

## Built for characters

Valley 3 is Verba's default free text model. It is specifically designed for
roleplay and storytelling, with fast replies and support for image
understanding.

It prioritizes your verb's saved personality, memories, knowledge, reply style,
and scene continuity so conversations stay in character.

Choose **Valley 3** in **Dashboard -> Verb -> AI Engine -> Model**. It is
available on every plan and does not use credits.

<Card title="AI engine settings" icon="sliders" href="/guides/ai-engine">
  Configure reply style, context, creativity, and model selection.
</Card>


# Visual identity
Source: https://docs.verba.ink/guides/visual-identity

Avatars, banners, and a look that sticks.

## Choose a clear avatar

Your avatar shows up everywhere, so it needs to read at a tiny size. Keep it
simple, centered, and high contrast.

* Use a single subject.
* Avoid busy backgrounds.
* Keep faces or icons near the center.

## Make the banner support the avatar

Banners are wide, so use them for mood. Think background texture, environment,
or a simple pattern that matches the character.

<Info>
  If the avatar is bright, keep the banner calm. If the avatar is subtle, make
  the banner pop.
</Info>

## Tips for a clean look

* Stick to one color palette.
* Avoid text inside the image.
* Test on mobile and desktop.

<Card title="Content moderation" icon="shield" href="/guides/moderation">
  Learn what gets flagged before upload.
</Card>


# Voice and audio
Source: https://docs.verba.ink/guides/voice-and-audio

Give your verb a voice that fits the vibe.

## Voice replies

Voice is optional and can be enabled per verb. Start with text only, then add
voice once the personality feels right.

If you want voice on every eligible reply, set voice response frequency to
`100`. Lower values make voice replies intermittent on purpose.

Voice output is a **sidecar to the normal AI response**. Verba generates the
in-character text reply first, then may send the same response as audio when
Voice Engine is enabled and the configured frequency selects it. A clear
natural-language request for a voice message can also trigger audio, but Voice
Engine must still be enabled and the Verb must have a usable voice.

Slack and Twitch do not install a standalone voice command. Voice is not
handled as an isolated command response on those integrations.

## Delivery by surface

| Surface  | Voice-reply delivery                                | Native calling                               |
| -------- | --------------------------------------------------- | -------------------------------------------- |
| Discord  | Generated voice attachment alongside the text reply | Supported in Discord voice channels on Ultra |
| WhatsApp | WhatsApp-compatible generated audio/voice response  | Not supported                                |
| Telegram | Telegram-compatible generated audio/voice response  | Not supported for bots                       |
| Slack    | Native uploaded audio file alongside the text reply | Not supported                                |
| Twitch   | Playable audio link alongside the chat reply        | Not supported                                |
| Email    | Audio attachment alongside the email reply          | Not supported                                |

Calling is unavailable on providers that do not expose native bot calling.

## Voice attachment visual

The Voice Engine settings also include a **Voice Attachment Visual** section.

You can upload a custom still image for voice message videos instead of using
the default Verba image.

* The live preview uses the same `20:7` crop as the final voice attachment
* The generated video output is framed to `400x140`
* You can replace or remove the image at any time
* If no custom image is uploaded, Verba falls back to the default voice banner

For best results, use a wide banner-style image with the subject centered,
because tall portraits will be cropped heavily in the final attachment.

## Voice cloning

Upload a short, clean sample to create a custom voice. The best results come
from 6 to 12 seconds of clear speech with minimal background noise.

Reference text is optional. If you can, paste the exact transcript of the
sample. It improves similarity and keeps the voice more stable across replies.

## Supported languages

The voice engine supports a focused language set:

* Auto (recommended default)
* English
* Chinese
* Japanese
* Korean
* German
* French
* Russian
* Portuguese
* Spanish
* Italian

If you pick a language outside this list, the engine falls back to Auto.

## Premium voice model access

Voice model availability is plan-based in the same way as the AI and Image
engines.

When a selected premium voice model is outside your current tier, Verba shows an
upgrade prompt with the number of additional premium voice models available on a
higher plan.

That count is dynamic and can change as the voice catalog changes.

## Discord voice chat

On Discord, Ultra verbs can join voice chat with `/vc-join`, and they can also
join from a normal mention request such as asking the bot to join VC/call in
server chat.

Lower-tier verbs can still keep those commands enabled, but they respond with
an in-character upgrade message instead of joining live VC. Normal generated
voice messages stay free.

When the live voice path is healthy, the bot can:

* Listen in the connected voice channel
* Transcribe incoming speech
* Generate a reply
* Speak the reply back into VC

Voice-channel replies now depend on the live voice pipeline, so if VC is silent
you should verify:

* Voice Engine is enabled for the verb
* The selected voice model is available to that plan
* The bot can access and speak in the target voice channel
* The active speech provider is healthy and has available quota

<Note>
  If the selected live speech provider is unavailable or out of quota, Discord
  VC can join successfully but still fail to transcribe or speak until that
  provider becomes available again.
</Note>

## Voice notes on messaging platforms

WhatsApp voice notes can be transcribed and passed to the selected verb. When
voice replies are enabled, supported WhatsApp conversations can receive a voice
response as well. This is different from Discord live voice-channel calling,
which has its own Ultra plan requirement.

Telegram can receive voice/audio media through its bot integration. Slack
receives an uploaded audio file, Twitch receives a playable link because chat
has no general audio upload API, and Email receives an attachment. These are
message attachments, not calls.

<Note>
  Discord is currently the only integration with a native live-call path.
  WhatsApp calling is intentionally not exposed, and Slack, Twitch, Telegram
  bots, and Email have no Verba call action.
</Note>

## Keep it natural

* Short replies sound better.
* Avoid long paragraphs in voice mode.
* Set a frequency that feels human.

<Tip>
  If the voice feels off, lower reply length and reduce random creativity.
</Tip>

## Safety and permissions

Only upload audio you own or have permission to use.

<Card title="AI engine" icon="sliders" href="/guides/ai-engine">
  Lower temperature for clearer voice output.
</Card>


# Web search
Source: https://docs.verba.ink/guides/web-search

How fresh web-grounded answers work and how Verba handles search fallback.

## What web search does

When Web Search is enabled, Verba can recognize questions that need current or
uncertain information, run a search, and use the results while composing the
final answer in the verb's personality.

It is useful for news, live status, current public figures, recent releases,
prices, and other facts that can change after the model was trained.

## Search path and fallback

Verba uses LangSearch as its primary search provider. If that path is
unavailable, it can fall back to Brave's public HTML results. When a data-center
IP is blocked or rate limited, the Brave fallback can retry through a rotating
proxy pool (up to three proxy attempts).

The model should receive the search results and answer normally. Internal
`<tool_call>` markup is not intended to appear in a user-facing response.

## When to use it

* Current events and status incidents
* Policies, pricing, schedules, or leadership that changes
* Recent releases and live product information
* Questions where an old answer could mislead the user

## When to skip it

* Roleplay or storytelling
* Static lore and worldbuilding
* Stable facts already stored in Knowledge
* Latency-sensitive voice conversations

<Note>
  Search adds network and model-planning latency and can increase credit use.
  Response Streaming can show text sooner after generation starts, but it
  cannot remove the time needed to perform the search.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The bot printed a tool call instead of an answer">
    Retry once and report the timestamp, verb ID, and surface. That markup is an
    internal planning format and should be intercepted before sending.
  </Accordion>

  <Accordion title="Results are irrelevant">
    Ask a narrower question with names, location, and date. For stable subjects,
    turn Web Search off and put the canonical facts in Knowledge instead.
  </Accordion>

  <Accordion title="The reply is slow">
    Search may include a primary attempt and fallbacks. Disable it for requests
    that do not need fresh information and reduce model context if appropriate.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="AI engine" icon="sliders" href="/guides/ai-engine">
    Configure search alongside context, model, and streaming.
  </Card>

  <Card title="Memory and knowledge" icon="database" href="/guides/memory-and-knowledge">
    Store stable facts instead of searching for them every turn.
  </Card>
</CardGroup>


# WhatsApp module
Source: https://docs.verba.ink/guides/whatsapp

Connect a verb to WhatsApp, choose private or public verbs, and chat with text, images, and voice.

## What the WhatsApp module does

The WhatsApp module lets someone message the Verba WhatsApp number, sign in with
a secure authorization link, pick a verb, and continue the conversation inside
WhatsApp.

It supports:

* Your own private verbs
* Public verbs from Explore
* Normal text chat
* Image understanding
* Image generation
* Voice messages
* Reply context from WhatsApp replies
* Edit-in-place response streaming on Ultra
* Switching or disconnecting the connected verb

## Before you start

You need:

* A Verba account
* At least one verb, or a public verb you want to talk to
* WhatsApp installed on your phone or desktop
* The Verba WhatsApp number shown on the WhatsApp module page

<Note>
  You do not need to paste a token or create a WhatsApp bot yourself. The module
  uses the shared Verba WhatsApp number and links each chat to the verb you pick.
</Note>

The shared gateway stores its WhatsApp linked-device state durably. A normal
Verba server or container restart should not require users to relink WhatsApp.
Relinking is only needed after an explicit logout, revoked linked device, or
invalidated WhatsApp session.

## Connect a verb to WhatsApp

<Steps>
  <Step title="Open the WhatsApp module">
    Go to your verb dashboard, open Settings or Modules, then choose WhatsApp.
  </Step>

  <Step title="Message the Verba WhatsApp number">
    Send any message to the number shown on the module page. Verba replies with
    a secure authorization link.
  </Step>

  <Step title="Sign in and pick a verb">
    Open the link, sign in, then choose one of your verbs or a public verb.
  </Step>

  <Step title="Return to WhatsApp">
    After you choose a verb, the modal closes and sends you back to WhatsApp.
    The chat is now connected.
  </Step>
</Steps>

## Choosing public verbs

The authorization modal shows your own verbs first, then public verbs. Use the
search box to find a verb by name, tag, or description.

This means a WhatsApp chat can be connected to:

* A private verb you created
* A public verb from another creator
* A different verb later with `/switch`

## Media support

WhatsApp conversations can use more than plain text.

### Images

Send an image with a message and the connected verb can inspect it, answer
questions about it, or use it as context for the next reply.

If your verb has image generation enabled, you can also ask it to create an
image. Generated images are sent back to the WhatsApp chat as media.

### Voice messages

Send a WhatsApp voice note and Verba transcribes it before passing it to the
verb. If your verb has voice replies enabled, it can answer with voice as well.

### Reply context

When you reply to a specific WhatsApp message, Verba includes that quoted message
as context. This helps the verb understand what "that", "this one", or "the
image above" refers to.

### Response streaming

On Ultra, enabling Response Streaming in the verb's AI Engine lets WhatsApp
receive the first useful part of the reply early and then see that message
updated as generation continues. If streaming is unavailable before any
partial text is sent, Verba falls back to a normal complete reply.

## WhatsApp commands

| Command              | What it does                                                 |
| -------------------- | ------------------------------------------------------------ |
| `/help`              | Shows the available WhatsApp commands.                       |
| `/ping`              | Checks whether the WhatsApp connection is responding.        |
| `/generate <prompt>` | Generates an image when image generation is enabled.         |
| `/status`            | Shows the currently connected verb.                          |
| `/switch`            | Opens the verb picker again so you can connect another verb. |
| `/disconnect`        | Disconnects the current chat from the selected verb.         |

After enough replies, Verba may remind the user that `/disconnect` is available
if they want to change or stop the connected verb.

## Best practices

* Send a clear first message after connecting so the verb knows what you want.
* Add a short caption when sending images.
* Use WhatsApp replies when asking follow-up questions about an earlier message.
* Use `/switch` instead of disconnecting if you only want to talk to another verb.
* Use `/disconnect` when the chat should no longer be linked to any verb.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The authorization link expired">
    Send another message to the Verba WhatsApp number, or use `/switch` if the
    chat is already connected. Verba will send a fresh link.
  </Accordion>

  <Accordion title="I picked the wrong verb">
    Send `/switch` in WhatsApp and choose a different verb from the modal.
  </Accordion>

  <Accordion title="The verb did not understand an image">
    Re-send the image with a short caption explaining what you want the verb to
    look at. Clearer images and direct questions work best.
  </Accordion>

  <Accordion title="Voice did not work">
    Try sending the message again, or type the message as text. Very short,
    noisy, or interrupted voice notes can fail transcription.
  </Accordion>

  <Accordion title="I want to stop the chat">
    Send `/disconnect`. The chat will detach from the verb until you connect one
    again.
  </Accordion>

  <Accordion title="Do I need to relink after a Verba restart?">
    Normally, no. Linked-device credentials persist across ordinary restarts.
    Relink only if WhatsApp logged the shared gateway out or revoked its device.
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Discord deployment" icon="discord" href="/guides/discord">
    Connect a verb to Discord servers, channels, commands, and voice.
  </Card>

  <Card title="Image generation" icon="image" href="/guides/image-generation">
    Learn how image creation works across Verba chats and integrations.
  </Card>

  <Card title="Voice and audio" icon="microphone" href="/guides/voice-and-audio">
    Configure voice messages and audio behavior for your verbs.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Fast fixes for common account, chat, and module issues.
  </Card>

  <Card title="Response streaming" icon="bolt" href="/guides/response-streaming">
    See how early partial replies are finalized.
  </Card>
</CardGroup>


# Welcome to Verba
Source: https://docs.verba.ink/index

Create, deploy, and manage AI verbs with a guided workflow.

## Start here

New to Verba? These pages get you moving fast.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    From signup to a working verb in minutes.
  </Card>

  <Card title="Getting around" icon="map" href="/guides/getting-around">
    A quick tour of the dashboard and tools.
  </Card>

  <Card title="Your first verb" icon="user" href="/guides/first-verb">
    Build a personality, add visuals, and test the voice.
  </Card>

  <Card title="Magic Builder" icon="wand-magic-sparkles" href="/guides/magic-builder">
    Turn a short plain-language idea into an editable verb draft.
  </Card>

  <Card title="Personality playbook" icon="star" href="/guides/personality-playbook">
    Make your verb feel consistent and real.
  </Card>
</CardGroup>

## Make it yours

These settings shape how your verb looks and behaves.

<CardGroup>
  <Card title="Visual identity" icon="image" href="/guides/visual-identity">
    Avatars, banners, and a clean style.
  </Card>

  <Card title="AI engine" icon="sliders" href="/guides/ai-engine">
    Tune creativity, context, and cost.
  </Card>

  <Card title="Valley 3" icon="sparkles" href="/guides/valley-3">
    Meet Verba's free model for roleplay, storytelling, and vision.
  </Card>

  <Card title="Social and emotional state" icon="heart" href="/guides/social-and-emotional-state">
    Set a mood manually or let conversations change it over time.
  </Card>

  <Card title="Response streaming" icon="bolt" href="/guides/response-streaming">
    Show replies sooner on Discord, WhatsApp, and Telegram.
  </Card>

  <Card title="Memory and knowledge" icon="book" href="/guides/memory-and-knowledge">
    Keep your verb consistent over time.
  </Card>

  <Card title="Web search" icon="globe" href="/guides/web-search">
    Use fresh info only when it matters.
  </Card>
</CardGroup>

## Chat and community

Test fast and learn from other creators.

<CardGroup>
  <Card title="Chat and groups" icon="comments" href="/guides/chat-and-groups">
    Run conversations and group rooms.
  </Card>

  <Card title="Community" icon="users" href="/guides/community">
    Join the Discord and share your work.
  </Card>

  <Card title="Image generation" icon="image" href="/guides/image-generation">
    Let your verb create visuals on demand.
  </Card>

  <Card title="Voice and audio" icon="microphone" href="/guides/voice-and-audio">
    Add voice once the personality feels right.
  </Card>
</CardGroup>

## Deploy and integrate

Bring your verbs into the places people already talk.

<CardGroup>
  <Card title="Discord deployment" icon="discord" href="/guides/discord">
    Connect a verb to Discord servers, channels, commands, and voice.
  </Card>

  <Card title="WhatsApp module" icon="comments" href="/guides/whatsapp">
    Let people message a Verba number, choose a verb, and chat from WhatsApp.
  </Card>

  <Card title="Telegram module" icon="paper-plane" href="/guides/telegram">
    Connect a BotFather token for Telegram DMs, groups, commands, and media.
  </Card>

  <Card title="Slack module" icon="slack" href="/guides/slack">
    Give one Verb its own Slack app, channels, threads, expressions, and commands.
  </Card>

  <Card title="Twitch module" icon="twitch" href="/guides/twitch">
    Connect a broadcaster and separate bot identity for chat, moderation, and stream tools.
  </Card>

  <Card title="Email module" icon="envelope" href="/guides/email">
    Use a vanity address with Postmark-backed threaded replies and generated media.
  </Card>

  <Card title="Discord Custom Builder" icon="wand-magic-sparkles" href="/guides/custom-builder">
    Build commands, buttons, modals, webhooks, and server automations.
  </Card>

  <Card title="API guide" icon="code" href="/guides/api">
    Use Verba programmatically from your own app or workflow. The API item in
    the integration switcher opens this guide directly; it has no connection flow.
  </Card>
</CardGroup>

## Safety, billing, and help

When something feels off, this is where you go.

<CardGroup>
  <Card title="Moderation" icon="shield" href="/guides/moderation">
    Learn how content checks work.
  </Card>

  <Card title="Discord anti-nuke" icon="shield-halved" href="/guides/discord-safety">
    Understand how Verba contains unauthorized bot-token actions.
  </Card>

  <Card title="Billing and refunds" icon="credit-card" href="/guides/billing-and-refunds">
    Credits, purchases, and what to do if something looks wrong.
  </Card>

  <Card title="Best practices" icon="check" href="/guides/best-practices">
    Small habits that improve quality fast.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/guides/troubleshooting">
    Quick fixes for common issues.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.verba.ink/quickstart

Launch a working verb in minutes.

## Get set in three steps

<Steps>
  <Step title="Create your account">
    Sign up at verba.ink, then open the dashboard. That is where all your verbs
    live.
  </Step>

  <Step title="Build the basics">
    Choose **Magic Builder** to describe the verb in plain language and let
    Verba draft it, or choose the manual flow for field-by-field control. Give
    it a name, description, and a few tags; visuals can come later.
  </Step>

  <Step title="Test in chat">
    Open a chat, send a few prompts, and see how it sounds. Adjust personality
    or AI engine settings until it feels right.
  </Step>
</Steps>

<Tip>
  Keep your first test prompts short. You will learn more in three tiny chats
  than in one giant paragraph.
</Tip>

## What to do next

<CardGroup>
  <Card title="Getting around" icon="map" href="/guides/getting-around">
    Learn where everything lives in the app.
  </Card>

  <Card title="Your first verb" icon="user" href="/guides/first-verb">
    Go deeper on personality and settings.
  </Card>

  <Card title="Magic Builder" icon="wand-magic-sparkles" href="/guides/magic-builder">
    Learn the prompt, search, image, and job flow.
  </Card>

  <Card title="AI engine" icon="sliders" href="/guides/ai-engine">
    Tune creativity and cost.
  </Card>

  <Card title="Deploy your verb" icon="paper-plane" href="/guides/slack">
    Connect Discord, WhatsApp, Telegram, Slack, Twitch, or Email after chat testing.
  </Card>

  <Card title="Visual identity" icon="image" href="/guides/visual-identity">
    Add an avatar and banner that match the vibe.
  </Card>
</CardGroup>