# Elvo

> Elvo is an AI-first customer service platform. Conversations arrive from email, chat, and other channels; AI drafts and auto-replies handle most of the load with human agents supervising.

## Agent quickstart (read this first)

You are an AI agent working in an Elvo helpdesk through the REST API. Human guide: https://elvo.is/help/ai-agents. Full reference: https://elvo.is/docs (OpenAPI: https://elvo.is/api/public/v1/openapi.json; every operation has an `operationId`).

1. **Auth.** Send `Authorization: Bearer elvo_...` on every request to https://elvo.is/api/public/v1. A token is created in Settings → API & agents (Icelandic: API og gervigreind) and acts as the person who created it: you see and do what they can. Read tokens can only GET; write tokens can also POST, PUT, PATCH and DELETE.
2. **Who am I.** `GET /me` returns the user the token acts as. Use that user id to recognise your own comments, drafts and assignments.
3. **List work, newest first.** `GET /conversations?status=open` (default order is `created_at` descending). Without `status` you get every status, including spam (`ignored`) and trash (`deleted`). Snoozed conversations are hidden by default (`snoozed=hide`); archived ones are included by default (`archived=all`, pass `archived=hide` to match the inbox). Page with `cursor` and `limit` (max 100).
4. **Read the full timeline.** `GET /conversations/{id}/comments?include_internal=true&include_events=true`. Comments come newest first in `data`; with `include_events=true` the events (assign, tag, status changes) come in a separate top-level `events` array, oldest first. Read `content_text` (plain text, quoted email history removed); `content` is the stored body and `content_format` says if it is `html` or `text`. Email messages carry `from`, `to`, `cc`. In events, `before`/`after`/`metadata` are internal and unstable: display them, do not depend on their keys.
5. **Act.** Three different things:
   - **Reply** (reaches the customer): `POST /conversations/{id}/comments` with `{"content": "...", "to": ["customer@example.com"]}`. On email conversations `to` is required; the server never guesses recipients. Add `"status": "resolved"` to close in the same call.
   - **Internal note** (team only, sends nothing): same endpoint with `"is_internal": true`. Plain text with light markdown; mention a teammate with `@[Full Name]`.
   - **Draft** (a person reviews and sends it; nothing is sent): `PUT /conversations/{id}/draft` with `{"content": "..."}`. The body is normalised to HTML (for example wrapped in `<p>`). Each person has their own draft on a conversation, and the token user's draft is yours: GET, PUT and DELETE only read, write and remove that draft, never a teammate's. It shows in the conversation for everyone on the team who opens it, with the token user as author, so a teammate can review, edit and send it.
6. **Change state.** `PATCH /conversations/{id}` with `status`, `assigned_to_id`, `team_id`, `subject`, or tags. `tags` replaces the whole list; use `add_tags` / `remove_tags` to change some tags without reading the list first. Tag names are case-sensitive and an unknown name creates the tag.
7. **Keep up with changes.** Either poll `GET /conversations?sort=updated_at&order=asc&updated_after=<largest updated_at you have processed, minus a few minutes>` and dedupe by `id` (the overlap covers email that carries its sent time, which can precede its arrival), or register a webhook (`POST /webhooks`) for `conversation.created`, `conversation.updated` and `comment.created`. Webhooks never deliver internal notes and are not replayed while an endpoint is disabled, so a poll is still the safe way to reconcile.

**Facts to rely on**

- IDs are UUIDs. `conversation_number` is the short number people see, not an id.
- Statuses: `open` (needs your team), `pending` (waiting for the customer), `resolved` (done; there is no `closed`, use `resolved`), `ignored` (spam), `deleted` (trash). A new customer message normally reopens a conversation to `open`.
- Errors are JSON: `{ "error": { "type", "message", "details" } }`. Read `message`; it says what to fix. Unknown query parameters and body fields are rejected with `400 validation_error` rather than ignored; an unsupported HTTP method gets `405 method_not_allowed`.
- Rate limits: 200 reads and 60 writes per minute per token. On `429`, wait `Retry-After` seconds. See "Rate limits" below.
- New response fields can appear at any time. Ignore fields you do not know.

## Products

Elvo is a unified customer-service platform (þjónustuborð / helpdesk) for Icelandic businesses. One AI service agent, "Elvo-þjónninn", answers across every channel, resolving simple requests automatically or drafting replies a human approves. Everything lands in one shared helpdesk where the team takes over with full context.

- Spjallþjónn (web chat): answers website visitors instantly from your own content and hands complex cases to the team. https://elvo.is/spjallthjonn
- Svarþjónn (email & messages): reads email, social messages, and web-form submissions, triages them, and writes reply drafts you approve. https://elvo.is/svarthjonn
- Raddþjónn (voice): answers phone calls in Icelandic, resolves simple requests, transfers to a person during opening hours, and otherwise takes a message. https://elvo.is/raddthjonn
- Þjónustuborð (helpdesk): the shared inbox that unifies every channel, enriched with AI and integrations. https://elvo.is/thjonustubord

## Pricing

Per-seat monthly plans, billed in ISK (+VAT). Four tiers: Lítill, Vöxtur (recommended), Stór, and Sérsniðið (custom pricing for larger organizations). The Raddþjónn voice agent is a paid add-on. Current prices: https://elvo.is/verdskra

## Company

Elvo is an Icelandic company serving Icelandic businesses; the product and its AI agents operate in Icelandic. Security and privacy: GDPR-compliant with a data-processing agreement, all data hosted within Europe (EU), AES-256 encryption in transit and at rest, and full audit trails.

- Home: https://elvo.is/
- Pricing: https://elvo.is/verdskra
- Web chat agent (Spjallþjónn): https://elvo.is/spjallthjonn
- Email agent (Svarþjónn): https://elvo.is/svarthjonn
- Voice agent (Raddþjónn): https://elvo.is/raddthjonn
- Helpdesk (Þjónustuborð): https://elvo.is/thjonustubord
- About us: https://elvo.is/um-okkur

## Public REST API

Elvo exposes a public REST API for AI agents and integrations. Authenticate with a Bearer token (format `elvo_...`) created in Settings → API & agents. Read tokens can only make GET/HEAD requests; write tokens can also POST, PUT, PATCH, and DELETE.

- OpenAPI spec: https://elvo.is/api/public/v1/openapi.json
- Interactive docs: https://elvo.is/docs
- Guide for AI agents: https://elvo.is/help/ai-agents
- Base URL: https://elvo.is/api/public/v1

## Endpoints (v1)

All endpoints return JSON with envelope `{ "data": ... }` for single resources or `{ "data": [...], "pagination": { "next_cursor", "has_more" } }` for lists. Cursor pagination: `?cursor=...&limit=25` (max 100). Each line shows the `operationId` in brackets.

- POST /conversations (createConversation): Create a conversation.
- GET /conversations (listConversations): List conversations. Query: status, assigned_to_id, team_id, contact_id, channel, channel_id, tag, q, contact_email, created_after, updated_after, sort, order, snoozed, archived, unanswered_for_minutes.
- POST /conversations/drafts (createConversationDraft): Create an outbound compose draft.
- GET /conversations/{conversationId} (getConversation): Get a conversation.
- PATCH /conversations/{conversationId} (updateConversation): Update a conversation.
- POST /conversations/{conversationId}/snooze (snoozeConversation): Snooze a conversation.
- DELETE /conversations/{conversationId}/snooze (unsnoozeConversation): Unsnooze a conversation.
- GET /conversations/{conversationId}/comments (listComments): List conversation comments. Query: include_internal, include_events.
- POST /conversations/{conversationId}/comments (createComment): Send a reply or add an internal note.
- PATCH /conversations/{conversationId}/comments/{commentId} (updateComment): Edit an internal note.
- DELETE /conversations/{conversationId}/comments/{commentId} (deleteComment): Delete an internal note.
- GET /conversations/{conversationId}/draft (getDraft): Get your draft on the conversation.
- PUT /conversations/{conversationId}/draft (upsertDraft): Create or update your draft on the conversation.
- DELETE /conversations/{conversationId}/draft (deleteDraft): Delete your draft on the conversation.
- GET /chats (listChats): List your chats.
- GET /chats/{chatId} (getChat): Get a chat.
- GET /mentions (listMentions): List my mentions. Query: since, author_id, kind.
- GET /chats/{chatId}/messages (listChatMessages): List chat messages. Query: include_events.
- POST /chats/{chatId}/messages (createChatMessage): Post a chat message.
- PATCH /chats/{chatId}/messages/{messageId} (updateChatMessage): Edit a chat message.
- DELETE /chats/{chatId}/messages/{messageId} (deleteChatMessage): Delete a chat message.
- GET /contacts (listContacts): List contacts. Query: q, email.
- GET /contacts/{contactId} (getContact): Get a contact.
- GET /organization (getOrganization): Get current organization.
- POST /attachments (createAttachment): Upload an attachment.
- GET /webhooks (listWebhooks): List webhook endpoints.
- POST /webhooks (createWebhook): Create a webhook endpoint.
- GET /webhooks/{webhookId} (getWebhook): Get a webhook endpoint.
- PATCH /webhooks/{webhookId} (updateWebhook): Update a webhook endpoint.
- DELETE /webhooks/{webhookId} (deleteWebhook): Delete a webhook endpoint.
- GET /users (listUsers): List team members. Query: include_deactivated.
- GET /users/{userId} (getUser): Get a team member.
- PATCH /users/{userId} (updateUser): Change a member's role.
- DELETE /users/{userId} (deactivateUser): Deactivate a member.
- POST /users/{userId}/reactivate (reactivateUser): Reactivate a deactivated member.
- GET /invitations (listInvitations): List pending invitations.
- POST /invitations (createInvitation): Invite a member.
- DELETE /invitations/{invitationId} (deleteInvitation): Revoke an invitation.
- GET /teams (listTeams): List teams.
- POST /teams (createTeam): Create a team.
- GET /teams/{teamId} (getTeam): Get a team.
- PATCH /teams/{teamId} (updateTeam): Update a team.
- DELETE /teams/{teamId} (deleteTeam): Delete a team.
- GET /teams/{teamId}/members (listTeamMembers): List team members.
- POST /teams/{teamId}/members (addTeamMember): Add a team member.
- PATCH /teams/{teamId}/members/{userId} (updateTeamMember): Change a member's team role.
- DELETE /teams/{teamId}/members/{userId} (removeTeamMember): Remove a team member.
- GET /channels (listChannels): List channels.
- GET /tags (listTags): List tags. Query: q.
- POST /tags (createTag): Create a tag.
- GET /tags/{tagId} (getTag): Get a tag.
- PATCH /tags/{tagId} (updateTag): Update a tag.
- DELETE /tags/{tagId} (deleteTag): Delete a tag.
- GET /canned-responses (listCannedResponses): List canned responses. Query: team_id, category.
- POST /canned-responses (createCannedResponse): Create a canned response.
- GET /canned-responses/{responseId} (getCannedResponse): Get a canned response.
- PATCH /canned-responses/{responseId} (updateCannedResponse): Update a canned response.
- DELETE /canned-responses/{responseId} (deleteCannedResponse): Delete a canned response.
- GET /automation-rules (listAutomationRules): List automation rules.
- POST /automation-rules (createAutomationRule): Create an automation rule.
- GET /automation-rules/{ruleId} (getAutomationRule): Get an automation rule.
- PATCH /automation-rules/{ruleId} (updateAutomationRule): Update an automation rule.
- DELETE /automation-rules/{ruleId} (deleteAutomationRule): Delete an automation rule.
- POST /automation-rules/{ruleId}/apply (applyAutomationRule): Apply a rule to existing conversations.
- GET /knowledge-sources (listKnowledgeSources): List knowledge sources. Query: status, source_type.
- POST /knowledge-sources (createKnowledgeSource): Create a knowledge source.
- GET /knowledge-sources/{sourceId} (getKnowledgeSource): Get a knowledge source.
- PATCH /knowledge-sources/{sourceId} (updateKnowledgeSource): Update a knowledge source.
- DELETE /knowledge-sources/{sourceId} (deleteKnowledgeSource): Delete a knowledge source.
- POST /knowledge-sources/files (uploadKnowledgeSourceFile): Upload a file as a knowledge source.
- PUT /knowledge-sources/{sourceId}/file (replaceKnowledgeSourceFile): Replace the file behind a knowledge source.
- POST /knowledge-sources/{sourceId}/sync (syncKnowledgeSource): Re-sync a live knowledge source.
- GET /reports/performance (getPerformanceReport): Get the performance report. Query: period, from, to, team_id, agent_ids, comparison.
- GET /me (getMe): Get the token owner, organization and token.
- GET /me/out-of-office (getOutOfOffice): Get my out-of-office status.
- PUT /me/out-of-office (setOutOfOffice): Set my out-of-office status.
- DELETE /me/out-of-office (clearOutOfOffice): Clear my out-of-office status.

## Errors

```json
{ "error": { "type": "validation_error", "message": "...", "details": ... } }
```

Types: authentication_error (401), authorization_error (403), validation_error (400), not_found (404), plan_limit (402), conflict (409), rate_limit_exceeded (429), internal_error (500).

## Rate limits

200 read requests/minute and 60 write requests/minute per token (sliding window). Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (an ISO 8601 timestamp). A 429 also carries `Retry-After` in seconds. Error responses other than 429 may omit the `X-RateLimit-*` headers.

## Mentions

Notify a teammate from a note or chat message by writing `@[Name]` (their exact display name; matching is case-insensitive and whitespace-tolerant) in the content. Notes also support `@[team:Name]` and `@[everyone]` (admin tokens only). Unmatched names notify no one.

## Workspace administration

Everything under Settings is on the API too: members (`/users`, `/invitations`), teams and membership (`/teams`), inbound channels (`GET /channels`: every mailbox, Meta page, WhatsApp number, widget and phone line with the team it routes to), tags (`/tags`), canned responses (`/canned-responses`), automation/routing rules (`/automation-rules`: full rule JSON, suitable for version control), the AI knowledge base (`/knowledge-sources`: create text or URL sources, upload files, PATCH text or PUT a replacement file to keep the AI fresh from a pipeline), and the performance report (`GET /reports/performance`). Member, invitation, team and knowledge writes need a token created by an organization admin.

## Tags

Conversations carry `tags`: an array of tag names from an org-wide vocabulary (each tag also has a color and emoji; manage the vocabulary via `/tags`). Names are case-sensitive and max 100 characters. Writing `tags` on PATCH replaces the full list (empty array clears); `add_tags` and `remove_tags` change only the names you give. Unknown names create new tags automatically. Filter with `GET /conversations?tag=<name>` (exact name match).

## Not yet in the API

Bulk operations, composer features (scheduled send, forwarding), knowledge files over 4 MB (dashboard only), and rule change history/diff (export rules with GET and keep them in version control). Email elvo@elvo.is if you need one of these.

## Custom integrations & chat widget

Beyond the REST API, Elvo pulls live context from a business's own systems into agent sidebars and AI reply drafts. Built-in connectors: DK, Business Central, Payday, Regla, Shopify, WooCommerce, HubSpot, Dropp, Abler. A custom integration covers any other system via a single HTTPS endpoint the business hosts: Elvo POSTs the contact's identity and latest message, the endpoint returns structured JSON (sidebar fields + an AI summary). Full contract with sample servers: https://elvo.is/docs (section "Custom integrations").

The customer-facing chat widget (Spjallþjónn) embeds on any website with a script snippet from Settings; widget conversations arrive in the workspace like any other channel and are readable via the REST API and webhooks. Embed snippet: https://elvo.is/docs (section "Embedding the chat widget").

## Help center (Icelandic)

- [AI-aðgerðir](https://elvo.is/hjalp/ai-adgerdir)
- [Vefþjónusta (API)](https://elvo.is/hjalp/api)
- [Áskrift og verðskrá](https://elvo.is/hjalp/askrift)
- [Notaðu eigin gervigreind í Elvo](https://elvo.is/hjalp/eigin-gervigreind)
- [Fjarvera](https://elvo.is/hjalp/fjarvera)
- [Flýtilyklar](https://elvo.is/hjalp/flytilyklar)
- [Flytja inn gögn](https://elvo.is/hjalp/flytja-inn-gogn)
- [Frammistaða](https://elvo.is/hjalp/frammistada)
- [Fyrirtækisstillingar](https://elvo.is/hjalp/fyrirtaeki)
- [Fyrstu skref](https://elvo.is/hjalp/fyrstu-skref)
- [Gervigreind — AI-drög og þekkingargrunnur](https://elvo.is/hjalp/gervigreind)
- [Hvað er Elvo?](https://elvo.is/hjalp/hvad-er-elvo)
- [Setja í bið og fresta](https://elvo.is/hjalp/i-bid)
- [Yfirlit](https://elvo.is/hjalp)
- [Leit og geymsla](https://elvo.is/hjalp/leit-og-geymsla)
- [Merki](https://elvo.is/hjalp/merki)
- [Meta (Facebook og Instagram)](https://elvo.is/hjalp/meta)
- [Notendur og hlutverk](https://elvo.is/hjalp/notendur)
- [Persónulegar stillingar](https://elvo.is/hjalp/personulegar-stillingar)
- [Reglur](https://elvo.is/hjalp/reglur)
- [Sameina mál](https://elvo.is/hjalp/sameina-mal)
- [Samþættingar](https://elvo.is/hjalp/samthaettingar)
- [Setja upp spjallþjóninn](https://elvo.is/hjalp/spjallthjonn)
- [Stöðluð svör](https://elvo.is/hjalp/stodlud-svor)
- [Svara viðskiptavinum](https://elvo.is/hjalp/svara-vidskiptavinum)
- [Svarglugginn](https://elvo.is/hjalp/svargluggi)
- [Tengiliðir](https://elvo.is/hjalp/tengilidir)
- [Teymi og samvinna](https://elvo.is/hjalp/teymi)
- [Tilkynningar](https://elvo.is/hjalp/tilkynningar)
- [Undirskriftir](https://elvo.is/hjalp/undirskriftir)
- [Viðmótið](https://elvo.is/hjalp/vidmotid)
- [Að vinna með mál](https://elvo.is/hjalp/vinna-med-mal)
- [Áframsending](https://elvo.is/hjalp/tengja-tolvupost/aframsending)
- [Gmail / Google Workspace](https://elvo.is/hjalp/tengja-tolvupost/gmail)
- [Tengja tölvupóst](https://elvo.is/hjalp/tengja-tolvupost)
- [Fyrir kerfisstjóra: samþykkja Elvo í Microsoft 365](https://elvo.is/hjalp/tengja-tolvupost/kerfisstjori)
- [Outlook / Microsoft 365](https://elvo.is/hjalp/tengja-tolvupost/outlook)

## Help center (English)

- [AI actions](https://elvo.is/help/ai-actions)
- [Use your own AI agent with Elvo](https://elvo.is/help/ai-agents)
- [AI drafts & knowledge base](https://elvo.is/help/ai-drafts-and-knowledge)
- [Public API](https://elvo.is/help/api)
- [Automation rules](https://elvo.is/help/automation-rules)
- [Billing & plans](https://elvo.is/help/billing)
- [Canned responses](https://elvo.is/help/canned-responses)
- [Set up the chat agent](https://elvo.is/help/chat-agent)
- [The composer](https://elvo.is/help/composer)
- [Contacts](https://elvo.is/help/contacts)
- [Import data](https://elvo.is/help/import-data)
- [Overview](https://elvo.is/help)
- [Integrations](https://elvo.is/help/integrations)
- [Keyboard shortcuts](https://elvo.is/help/keyboard-shortcuts)
- [Merging tickets](https://elvo.is/help/merging-tickets)
- [Meta (Facebook & Instagram)](https://elvo.is/help/meta)
- [Notifications](https://elvo.is/help/notifications)
- [Organization settings](https://elvo.is/help/organization)
- [Out of office](https://elvo.is/help/out-of-office)
- [Performance](https://elvo.is/help/performance)
- [Personal settings](https://elvo.is/help/personal-settings)
- [Quickstart](https://elvo.is/help/quickstart)
- [Replying to customers](https://elvo.is/help/replying-to-customers)
- [Search & archive](https://elvo.is/help/search-and-archive)
- [Signatures](https://elvo.is/help/signatures)
- [Snoozing & on hold](https://elvo.is/help/snoozing)
- [Tags](https://elvo.is/help/tags)
- [Teams & collaboration](https://elvo.is/help/teams)
- [The interface](https://elvo.is/help/the-interface)
- [Users & roles](https://elvo.is/help/users-and-roles)
- [What is Elvo?](https://elvo.is/help/what-is-elvo)
- [Working with tickets](https://elvo.is/help/working-with-tickets)
- [Forwarding](https://elvo.is/help/connect-email/forwarding)
- [Gmail / Google Workspace](https://elvo.is/help/connect-email/gmail)
- [Connect email](https://elvo.is/help/connect-email)
- [For IT admins: approve Elvo in Microsoft 365](https://elvo.is/help/connect-email/it-admin)
- [Outlook / Microsoft 365](https://elvo.is/help/connect-email/outlook)