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

# Use Evelin

> Generate replies, rewrite and translate drafts, review facts, and retrieve Evelin results through API or MCP.

Evelin runs inside Protodesk using the same conversation context, workspace knowledge, runtime settings, and credit policy as the app. Generation returns a draft or analysis. It does not send a customer message.

## Connect and grant access

Use [Protodesk MCP](/mcp/connect) with `ai:use` and `conversations:read`. OAuth and API keys are supported. REST requests use an API key at `https://api.protodesk.io/v1`; MCP OAuth tokens cannot authenticate REST requests.

The connection must belong to a current workspace owner or admin. Create API keys in **Settings → API**. Older generic keys without a recorded human creator cannot run these operations; replace them if the API returns `ai.connection_required`.

Only the exact API key or OAuth grant that created a run can retrieve its private results. Another key belonging to the same person, or a newly authorized OAuth connection, cannot take over those results. Ticket Context is shared conversation context.

## Suggest a reply

1. Call `workspace_context` and confirm the workspace.
2. Read the conversation and identify its conversation ID.
3. Call `suggest_evelin_reply` with a stable idempotency key.
4. Poll `get_evelin_run` using the returned run ID.
5. When it succeeds, call `get_evelin_result` with `kind: "reply-draft"`.
6. Review the body, grounding, citations, and any outdated-knowledge indicator.

Example tool arguments:

```json theme={null}
{
  "conversationId": "CONVERSATION_ID",
  "expectedWorkspaceId": "WORKSPACE_ID",
  "idempotencyKey": "reply-draft-20261006-001",
  "body": {
    "strategy": "recommended",
    "instruction": "Answer the latest question clearly and briefly."
  }
}
```

A reply guard can decide that no reply is needed. If no draft exists, read `get_evelin_result` with `kind: "reply-guard"` and inspect `shouldDraft`, `reasonCode`, and `reason`. Set `overrideNoReply: true` only when you intentionally want a draft despite that recommendation.

The REST equivalent is:

```bash theme={null}
curl https://api.protodesk.io/v1/ai/conversations/CONVERSATION_ID/actions/reply-suggest \
  -H "Authorization: Bearer $PROTODESK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-draft-20261006-001" \
  -d '{"strategy":"recommended","instruction":"Answer clearly and briefly."}'
```

A successful creation or identical retry returns HTTP `202` with the run in `data`. Poll `GET /ai/runs/{runId}`, then read `GET /ai/runs/{runId}/results/reply-draft`.

## Rewrite or translate a draft

Call `rewrite_with_evelin` with the conversation ID, workspace confirmation, idempotency key, and a `body` containing `mode` and `draft`.

| Mode | Options |
| - | - |
| `improve` | Proofread and improve the draft. Omit tone, preset, and target language. |
| `polish` | Use one `preset`: `expand`, `shorten`, `friendly`, or `professional`; alternatively provide `tone`. Do not provide both. |
| `translate` | Provide `targetLanguage`, such as `id`. Omit tone and preset. |

```json theme={null}
{
  "conversationId": "CONVERSATION_ID",
  "expectedWorkspaceId": "WORKSPACE_ID",
  "idempotencyKey": "translate-draft-20261006-001",
  "body": {
    "mode": "translate",
    "draft": "Thank you. We will check this for you.",
    "targetLanguage": "id"
  }
}
```

Retrieve `kind: "rewrite"` after the run succeeds. The result includes `text`, `mode`, `changed`, and applicable language, tone, or preset fields. The original draft is not edited.

To translate a stored message, use `translate_message_with_evelin` with `messageId` and `body.targetLanguage`. It translates the current message body and returns a rewrite result without changing the message. If the message changes before a retry, the same idempotency key conflicts.

Draft input is limited to 20,000 characters and the overall request body to 64 KiB.

## Other actions

| Action | Tool | Result |
| - | - | - |
| Follow up when the customer has not replied to the latest public agent message | `draft_evelin_follow_up` | `follow-up-draft` |
| Refresh Ticket Context | `regenerate_ticket_context` | Read `get_ticket_context` after completion |
| Check claims in a draft | `review_evelin_draft` with `body.draft` | `draft-grounding-review` |
| Translate a generated reply for a reviewer | `translate_evelin_reply_for_review` with `draftArtifactId` and `body.targetLanguage` | `draft-review-translation` |

Review translation only accepts a suggested-reply artifact owned by the same connection. It preserves the original reply and identifies its source artifact and content hash. Generated results remain subject to artifact retention, redaction, and knowledge freshness.

Manual generation supports email, WhatsApp, and chat conversations. A conversation with another channel returns `ai.channel.unsupported`.

## Runs, retries, and credits

Runs can be `queued`, `running`, or `waiting`, then finish as `succeeded`, `partially_succeeded`, `failed`, or `canceled`. Run status includes `creditsUsed` and an error category. A successful run does not always produce every result kind.

Poll with a reasonable interval, such as three seconds. A result may return `404` while unfinished or when it is absent, expired, redacted, or owned by another connection. Do not treat `404` as permission to start another chargeable run.

Retry an uncertain generation request with **the same arguments and idempotency key**. It reuses the original run. Changing inputs with that key returns a conflict. New keys represent new work and can consume additional credits.

If Evelin is disabled or unavailable, new work returns `503`. Credit exhaustion and other runtime failures remain visible through run status. These tools do not bypass the workspace's existing AI policy.

## Review before sending

Use a generated draft as a proposal for your review. To deliver it, call `send_message` separately with `messages:send` and an explicit destination. Inspect delivery status afterward. A completed Evelin run is never a delivery receipt.

Assistant chat sessions, action confirmation/undo, and feedback are not exposed by these ten tools yet. See the [tool reference](/mcp/hosted-tools) for the current supported catalog.


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