Documentation

Everything you need to set up and use Veyra on your website.

Getting Started

Requirements

Veyra is a hosted SaaS product — there is nothing to install on your server. You only need:

A Veyra account (free to create, no credit card required)
The ability to add a <script> tag to your website's HTML
A modern browser for the agent dashboard (Chrome, Firefox, Safari, Edge)

Veyra works with any website or webshop — no framework requirements. WordPress, Shopify, custom HTML, or anything else.

Create an account

Go to veyra.support/register and fill in your name, email address, and a password. Your account is activated immediately — no email confirmation is required.

After registering you will be taken directly to the agent dashboard. From there you can add your first website and get your embed code.

Two-factor authentication: After your first login you will be prompted to set up 2FA using an authenticator app. This is mandatory for all agent accounts to keep your conversations secure.

Add your first website

1 In the dashboard sidebar, click Websites.
2 Click Add website in the top-right corner.
3 Fill in the website name (e.g. "My Webshop") and domain (e.g. myshop.com).
4 Optionally set a greeting message, agent display name, and widget colors.
5 Click Save. You will be redirected to the website detail page where your embed code is ready to copy.

The Widget

Embed code

Each website in your account has a unique embed code. The code is a single <script> tag — no separate CSS file, no additional dependencies.

All widget configuration is passed directly as data-* attributes on the script tag. This means the widget reads its full configuration from the HTML and does not make any extra API calls to fetch settings — keeping load time minimal.

You can always find the current embed code for a website by opening the Websites page in your dashboard and clicking Embed code on any website card.

Configuration attributes

The following data-* attributes are supported on the widget script tag.

Attribute	Required	Default	Description
data-shop-id	Required	—	Your unique website identifier. Found in the Websites section of your dashboard.
data-api-url	Required	—	The Veyra API endpoint. Always https://api.veyra.support.
data-main-color	Optional	#2563eb	Primary color used for the chat button and header background.
data-secondary-color	Optional	#7c3aed	Secondary color used for agent message bubbles.
data-tertiary-color	Optional	#10b981	Accent color used for the visitor avatar and online indicators.
data-greeting	Optional	Hi there!…	The opening message displayed when a visitor opens the chat widget.
data-agent-name	Optional	Support Team	The display name shown in the widget header as the agent name.

Colors & branding

Veyra supports three color slots to match your brand. You can preview the colors live in the website editor before saving. Colors are stored on your account and baked into the embed code — changing a color requires saving the website and updating the snippet on your site.

Main color — chat button background, widget header, send button.
Secondary color — agent message bubbles.
Tertiary color — visitor avatar, online status dot.

A complete snippet with all color attributes looks like this:

HTML

<script src="https://cdn.veyra.support/widget.js"
        data-shop-id="YOUR_SHOP_ID"
        data-api-url="https://api.veyra.support"
        data-main-color="#2563eb"
        data-secondary-color="#7c3aed"
        data-tertiary-color="#10b981"
        data-greeting="Hi there! How can we help you today?"
        data-agent-name="Support Team"
        async></script>

Conversations

Conversation list

The Conversations page in the dashboard shows every active and historical chat session across all your websites. Each row displays:

Visitor identifier (anonymous, e.g. "Visitor #A3F2C1")
Current status: Waiting, Being helped, or Closed
Which website the conversation came from
Timestamp of the last message

Click any row to open the full conversation panel with the complete message history.

Sending messages

Open a conversation and type your reply in the input at the bottom of the panel. Press Enter or click the send button to deliver it instantly via WebSocket.

As soon as an agent opens a conversation its status changes to Being helped, and the visitor sees the agent name in the widget header. The status returns to Waiting if the agent closes the panel without ending the conversation.

File attachments

Both agents and visitors can attach files to a conversation. Supported types include images, PDFs, and most common document formats. The maximum file size is 10 MB per file.

Files are automatically deleted from our servers 72 hours after they are uploaded. Download anything you need to keep before that window closes.

Conversation status

Every conversation moves through the following statuses:

Waiting

A visitor opened the chat and sent a message. No agent has opened the conversation yet.

Being helped

An agent has opened the conversation panel. The visitor can see the agent name in the widget.

Closed

The conversation has been marked as resolved. The visitor can still read the history but cannot send new messages.

Filtering by website

If you have more than one website registered, a website filter dropdown appears above the conversation list. Select a website to see only the conversations from that domain. Selecting All websites shows everything.

You can also deep-link to a filtered view from the Websites page — click the Conversations button on any website card to open the conversation list pre-filtered to that website.

Internal notes

Agents can leave private notes on any conversation. Notes are only visible to other agents — they are never shown to the visitor in the widget. Use notes to hand off context between team members, flag follow-ups, or record decisions.

To add a note, open a conversation and switch to the Notes tab in the reply area. Type your note and click Add note. Notes are displayed in the conversation timeline with a distinct yellow background so they stand out from regular messages.

Notes cannot be edited after saving. If you need to correct a note, add a new one.

Visitor ratings

When a conversation ends, visitors can rate their experience using a 1–5 star scale displayed directly in the chat widget. The rating is attached to the conversation and visible to agents in the conversation detail view and on the dashboard.

Ratings feed into two dashboard metrics: the Avg. rating stat card (account-wide average) and the CSAT score (percentage of ratings that are 4 or 5 stars, displayed as a performance metric).

Each visitor can rate only once per conversation — no duplicate submissions.
The rating prompt is shown only to conversations the visitor ended or that were closed by an agent.
The rating timestamp is stored alongside the score and is visible in the conversation detail.

The rating prompt can be toggled on or off account-wide under Settings → Visitor settings. When disabled, the prompt is never shown to visitors.

Missed conversations

A conversation is flagged as missed when no agent sends a reply within a configurable time window after the conversation starts. This helps you identify visitors who may have given up waiting and left without getting help.

Missed

No agent message was sent within the configured threshold (default: 5 minutes) of the conversation being created.

Missed conversations show a red MISSED badge in the conversation list and contribute to the Missed today stat card on the dashboard, which turns red when the count is above zero.

Use the Missed filter in the conversation list to view only missed conversations and act on them immediately. The filter is available in the status dropdown alongside Active and Ended.

The missed threshold can be adjusted per account under Settings → Visitor settings → Missed conversation threshold. Values between 1 and 60 minutes are supported. The default is 5 minutes.

Tags & labels

Tags are colored labels you can attach to any conversation to categorize it. Common uses include tagging conversations by topic (e.g. "Billing", "Returns", "Bug report") or by priority ("Urgent", "VIP").

To tag a conversation, open it and click Add tag in the conversation detail panel on the right. Tags are created and managed by admins under Admin → Tags. Agents can apply any existing tag but cannot create new ones.

Once tagged, conversations can be filtered by tag in the conversation list — see Filtering by tag.

Export

Admins can export all conversations to CSV from Admin → Export. The export includes the conversation metadata (ID, website, visitor, status, timestamps) and the full message transcript.

Exports are generated on demand and downloaded directly in the browser. There is no limit on the date range — the export always covers all conversations in your account.

For programmatic access to conversation data, consider the Public API which supports real-time polling and pagination.

Tags & Labels

Managing tags

Tags are managed by admins under Admin → Tags. Each tag has a name and a color. The color is displayed as a badge next to the conversation in the list, making it easy to spot tagged conversations at a glance.

1 Go to Admin → Tags in the sidebar.
2 Click New tag, enter a name (e.g. "Returns"), and choose a color.
3 Click Save. The tag is immediately available for agents to apply to conversations.

To delete a tag, click the trash icon next to it. Deleting a tag removes it from all conversations it was applied to.

Filtering by tag

In the conversation list, use the Tag dropdown to show only conversations that have a specific tag applied. You can combine the tag filter with the website filter and status filter to narrow down the list further.

Selecting All tags (the default) clears the tag filter and shows all conversations regardless of their tags.

Departments

Overview

Departments let you organize agents into groups and route incoming conversations to the right team. For example, you might have a "Sales" department and a "Technical Support" department, each with different agents.

Departments are created and managed by admins under Admin → Departments. Each agent can be a member of one or more departments.

Departments are optional. If you only have one team or do not need routing, you do not need to set up departments.

Forwarding conversations

Any agent can forward an open conversation to a different department. This is useful when a visitor's question needs to be handled by a specialist team.

1 Open the conversation you want to forward.
2 In the conversation detail panel on the right, click Forward to department.
3 Select the target department and confirm.

After forwarding, the conversation appears in the queue for all agents in the target department. The conversation status resets to Waiting so a new agent can pick it up.

Forwarded conversations are flagged in the conversation list with a forwarded indicator. The full forwarding history is visible in the conversation timeline.

Websites

Managing websites

You can add as many websites as you need under a single Veyra account. All websites share the same agent pool and dashboard — your agents can handle conversations from any website in one place.

To delete a website, click the Delete button on its card. You will be asked to confirm before the website and its embed code are removed. Existing conversation history is retained even after a website is deleted.

Per-website embed code

Every website has a unique data-shop-id that ties conversations to the correct website. The embed code is displayed on both the website list page (expandable) and the individual website editor page.

After saving changes to a website (colors, greeting, agent name) the embed snippet updates automatically — copy the new snippet and replace the old one in your HTML.

Per-website branding

Each website can have its own color scheme, greeting message, and agent display name. This makes Veyra ideal for agencies managing multiple client websites — every client gets a widget that feels like it belongs to their brand.

Agents

Inviting agents

Go to Agents in the sidebar and click Add agent. Enter the name and email address of the new team member. They will receive an invitation email with a link to set their password.

Agents are shared across all websites in your account. There is no limit on the number of agents.

Roles & permissions

Action	Admin	Agent
Handle conversations
View all conversations
Add / edit / delete websites
Invite and manage agents
Configure AI assistant
Import & manage product catalog
Change account settings

Two-factor authentication

2FA is mandatory for all agent accounts. On first login, agents are prompted to scan a QR code with any TOTP authenticator app (Google Authenticator, Authy, 1Password, etc.).

Agents are also shown a set of single-use recovery codes at setup time. These codes bypass 2FA in case the agent loses access to their authenticator app. Store them safely — they are shown only once.

Admins cannot disable 2FA for individual agents. If an agent is permanently locked out, delete their account and create a new one.

Agent profile

Every agent can update their own profile without admin involvement. Click Profile in the bottom-left corner of the sidebar to open the profile page.

From the profile page an agent can:

Display name — the name shown to visitors in the widget and to teammates in the dashboard.
Avatar URL — an optional image URL for a profile photo. Shown in the sidebar and in conversation headers.
Password — change the account password by entering the current password first (see Password reset).

Admins can update any agent's name and email from Admin → Agents, but only the agent themselves can change their own password.

Presence status

Agents can set their availability status to Online or Away using the toggle in the bottom-left corner of the sidebar. The current status is shown as a colored dot next to the agent's avatar.

Online

Agent is actively available. The dashboard sends a heartbeat every 60 seconds to keep the status current. The chat widget shows as active if at least one agent is online.

Away

Agent is logged in but not actively monitoring. Counts as offline for widget availability purposes.

When an agent logs out, their status is automatically set to Offline. If the browser closes without an explicit logout, the status is inferred from the heartbeat — after 2 minutes without a ping the agent is considered offline.

Agent presence takes priority over business hours. If at least one agent is online, the chat widget is visible regardless of business-hours configuration. If no agents are online, business hours determine widget visibility.

Password reset

If an agent forgets their password, they can request a reset link from the login page by clicking Forgot password?. An email is sent to their registered email address with a secure link valid for 1 hour.

Clicking the link opens the password-reset page where the agent enters and confirms a new password (minimum 8 characters). After a successful reset the link is invalidated immediately and cannot be reused.

For security, the reset email is always sent regardless of whether the email address matches an account — this prevents user enumeration. If no email arrives within a few minutes, check your spam folder.

Agents who are already logged in can change their password directly from their profile page without going through the reset flow.

AI Assistant

Overview

Veyra can connect to OpenAI to provide automated responses to visitor messages. When enabled, the AI responds instantly — even outside your business hours. Agents can always step in, override the AI response, and take over the conversation.

Veyra uses your own OpenAI API key. You are billed directly by OpenAI for the tokens used — Veyra does not mark up or resell AI credits.

Connecting OpenAI

1 Go to Settings → AI Assistant in your dashboard.
2 Paste your OpenAI API key (starts with sk-).
3 Write your system prompt — this tells the AI who it is, what it can help with, and what to avoid.
4 Toggle Enable AI and save. The AI will now respond to new visitor messages.

System prompt

The system prompt is the instruction you give the AI before any conversation starts. Use it to define the AI's persona, the topics it should help with, and anything it should not discuss.

Example system prompt

You are the customer support assistant for MyShop.com, a Dutch online electronics store.

Help customers with:
- Order status and delivery questions
- Product information and availability
- Return and refund policy (14-day no-questions-asked)
- Technical questions about products we sell

Do not discuss competitors. If you cannot answer a question confidently, say that a human agent will follow up shortly and set the conversation status to "Waiting".

Enabling & disabling

The AI can be toggled on or off at any time from Settings → AI Assistant without losing your API key or system prompt configuration. This is useful for temporarily disabling the AI during peak hours when you want human-only support.

Auto-translation

Auto-translation lets agents support visitors in any language without learning it. When enabled, visitor messages are automatically translated to the agent's working language before they appear in the dashboard. Agent replies are translated back into the visitor's language before the visitor reads them.

Language detection is instant — neither the agent nor the visitor needs to select a language. Translation uses your connected OpenAI API key and supports all languages OpenAI can handle (50+).

1 Go to Settings → AI Assistant.
2 Enable the Auto-translate conversations toggle.
3 Set your Agent language — the language you want incoming messages translated to (e.g. English, Dutch, German).
4 Save. All new conversations will now have messages translated in both directions automatically.

Auto-translation requires the AI assistant to be enabled with a valid OpenAI API key. Each translated message counts toward your OpenAI token usage.

Auto-summary

When a conversation is closed, Veyra automatically generates a short AI summary of the conversation using your OpenAI API key. The summary appears at the top of the closed conversation view so agents can quickly understand what happened without reading the full transcript.

Summaries are generated in the background and do not delay the closing action. They are stored alongside the conversation and visible to all agents who open it.

Auto-summary requires the AI assistant to be enabled and a valid OpenAI API key to be configured. If the AI is disabled, summaries are not generated.

Auto-sentiment

Veyra analyses the sentiment of each closed conversation and labels it as Positive, Neutral, or Negative. The sentiment badge is shown in the conversation list and in the conversation detail view.

Sentiment analysis runs at the same time as the auto-summary — when the conversation closes. It uses the full conversation transcript to infer the overall visitor mood.

PositiveVisitor was satisfied — the issue was resolved or the interaction was pleasant.

NeutralThe interaction was informational or the visitor showed no strong emotion.

NegativeVisitor expressed frustration, dissatisfaction, or left with an unresolved issue.

Use sentiment data together with visitor ratings to identify conversations that may need a follow-up from a senior agent.

Product Catalog

Overview

The product catalog lets you upload your entire product range so the AI can answer visitors' questions about specific products — prices, descriptions, availability — accurately and without guessing.

Products are imported via a CSV file from Admin → Products. Once imported, the AI uses semantic search to find the right product whenever a visitor asks a product-related question. No extra configuration is needed — it works automatically alongside your existing AI assistant setup.

The product catalog requires the AI assistant to be enabled. Make sure you have connected your OpenAI API key under Settings → AI Assistant before importing products.

CSV format

Your CSV file must include a header row with the following column names. Column order does not matter. Only name is required — all other columns are optional but recommended for best results.

Column	Required	Description
name	Required	Product name. Used as the primary identifier in search results.
description	Optional	A short description of the product. The more detail here, the better the semantic search results.
price	Optional	Price as a string, e.g. €29.99 or 29.99 EUR. Displayed to visitors and cited by the AI.
sku	Optional	Your internal stock-keeping unit code. Useful for reference but not used in search.
url	Optional	Direct URL to the product page. If provided, the product name becomes a link in the admin catalog view.

Example CSV:

CSV

name,description,price,sku,url
Trail Runner X200,Lightweight waterproof trail running shoe available in blue and grey,€89.99,SKU-042,https://myshop.com/trail-runner-x200
Urban Sprint Pro,City running shoe with cushioned sole available in 5 colours,€64.99,SKU-019,https://myshop.com/urban-sprint-pro

Limits: maximum 2,000 products per import, maximum file size 8 MB. Importing replaces your entire catalog — existing products are deleted and replaced with the new CSV contents.

Importing products

1 In the admin sidebar, go to Products.
2 Click Download template to get a sample CSV with the correct headers, or prepare your own file using the format described above.
3 Click the upload area and select your CSV file, or drag and drop it.
4 Click Import products. The import may take a moment while embeddings are generated for each product.
5 Once complete, a confirmation message shows how many products were imported. The full catalog appears in the table below.

To remove all products, click Delete all products in the top-right corner of the Products page. This immediately removes all products and disables product lookup until you import again.

Each import replaces the entire catalog. To update a single product, re-export your catalog, make the change, and re-import the full file.

How AI lookup works

When a visitor sends a message, Veyra first checks whether the message is product-related using a keyword filter (e.g. words like "price", "cost", "product", "stock", "available"). If the message appears product-related, the AI performs a semantic similarity search against your catalog.

Semantic search means the AI understands meaning, not just exact words. A visitor asking "do you have waterproof shoes for hiking?" will correctly match a product described as "trail running shoe, waterproof" — even though the words are different.

Up to 5 of the most relevant products are injected into the AI's context before it generates a reply. The AI uses only these matched products to answer — it will not invent product details that are not in your catalog.

Product-related question — "How much does the Trail Runner X200 cost?" → catalog is searched, matching product is returned, AI answers with the real price.

Non-product question — "What are your return policy hours?" → catalog is not searched, AI answers from its system prompt as normal.

Tip: Write detailed product descriptions in your CSV. The richer the description, the more accurately the semantic search can match visitor questions to the right product.

Order Tracking

Overview

Order tracking lets your webshop push order data to Veyra so the AI can answer order-status and shipment questions on your behalf. When a visitor asks about an order, the AI verifies their identity via order ID and postal code and responds with the current status and tracking URL — without involving an agent.

Orders are synced to a specific website (shop) in your Veyra account. Each website has its own independent order catalog. Authentication uses your existing API key — no additional credentials are needed.

Order lookup requires the AI assistant to be enabled. Make sure you have connected your OpenAI API key under Settings → AI Assistant before syncing orders.

Sync API

Use the order sync API to push orders from your webshop to Veyra. The endpoint uses the same API key authentication as the Public API — see Authentication — but is not subject to the 5-minute rate limit. You can call it as frequently as needed (e.g. from an order-status webhook).

Upload / upsert orders

Send a JSON array of orders. Existing orders (matched by orderId) are updated in place; new orders are inserted. Up to 1,000 orders per call.

POST /api/v1/shops/{shopId}/orders
Authorization: Bearer veyra_your_key_here
Content-Type: application/json

[
  {
    "orderId":     "ORD-12345",
    "status":      "Shipped",
    "postalCode":  "1234 AB",
    "trackingUrl": "https://tracking.example.com/ORD-12345"
  },
  {
    "orderId":     "ORD-12346",
    "status":      "Processing",
    "postalCode":  "2500 GH",
    "trackingUrl": ""
  }
]

Field	Required	Description
orderId	Required	Your unique order identifier. Used as the lookup key — re-sending the same orderId updates the existing record.
status	Required	Current order status shown to the visitor, e.g. "Processing", "Shipped", "Delivered", "Cancelled".
postalCode	Required	The delivery postal code. Used to verify the visitor's identity before revealing order details. Matching is case- and space-insensitive.
trackingUrl	Optional	Full URL to the carrier's tracking page. Included in the AI reply when present.

Successful response:

HTTP/1.1 200 OK

{ "upserted": 2 }

Delete all orders

Removes the entire order catalog for the given website. Use this before a full re-sync to ensure stale orders are removed.

DELETE /api/v1/shops/{shopId}/orders
Authorization: Bearer veyra_your_key_here

HTTP/1.1 200 OK

{ "success": true }

Finding your shopId: Open the website in your Veyra dashboard (Websites → your website). The shop ID appears in the page URL: /admin/websites/YOUR_SHOP_ID.

Dashboard

Agents can inspect the synced order catalog directly in the dashboard. Open a website from the Websites page and switch to the Orders tab.

The tab shows the total number of synced orders and lists the most recent 50 (order ID, status, postal code, tracking URL).
The tab also shows the API endpoint and an example curl command for quick reference.
Use the Delete all orders button to clear the catalog without an API call.

Each website has its own order catalog. Orders synced to website A are completely separate from orders synced to website B.

AI order lookup

The AI checks for order intent only when the visitor brings it up — it never proactively mentions order tracking. When an order-related keyword is detected in the visitor's latest message (e.g. "order", "package", "tracking", "shipment", "bezorging", "Sendung"), the AI scans the conversation history to collect two pieces of information:

Order ID — extracted from any previous visitor message in the conversation (e.g. "my order number is ORD-12345").

Postal code — extracted from any previous visitor message (e.g. "my postcode is 1234 AB"). Dutch, German, and US formats are all recognised.

The visitor does not need to provide both in the same message. The AI remembers what was said earlier in the conversation.

Both found & match — the AI responds with the order status and tracking URL (if available).

Partial info — the AI asks the visitor for the missing order ID or postal code before looking anything up.

No match found — the AI tells the visitor it could not find a matching order and suggests contacting support directly.

Postal code matching is case- and space-insensitive. 1234 AB matches 1234ab. This ensures typos and formatting differences don't prevent a valid match.

Public API

Overview

The Veyra Public API lets you integrate conversation data and order information with your CRM, helpdesk, data warehouse, or webshop back-end. All endpoints use the same API-key authentication and return JSON.

Base URL

https://api.veyra.support/api/v1

Method	Endpoint	Description	Rate limit
Conversations (read)
GET	/conversations	List conversations (paginated)	1 req / 5 min
GET	/conversations/{id}	Get a conversation with its messages	1 req / 5 min
GET	/conversations/{id}/messages	List messages for a conversation	1 req / 5 min
GET	/conversations/{id}/files	List file attachments for a conversation	1 req / 5 min
Order sync (write)
POST	/shops/{shopId}/orders	Upload / upsert orders (max 1,000 per call)	No limit
DELETE	/shops/{shopId}/orders	Delete all orders for a website	No limit
Product sync (write)
POST	/shops/{shopId}/products	Import / replace product catalog (max 2,000 per call)	No limit
DELETE	/shops/{shopId}/products	Delete all products for a website	No limit

API keys

API keys are long-lived credentials that authenticate requests on behalf of your company. Each key is scoped to a single company and can access all public API endpoints — both read (conversations) and write (order sync).

Generate keys in the admin dashboard under API Keys.
Only admins can create or revoke keys.
The full key is shown only once at creation — store it securely (e.g. in your environment variables or secrets manager).
Revoke a key immediately if it is compromised — it takes effect instantly.

Treat your API key like a password. Do not commit it to version control or expose it in client-side code.

Authentication

Send your API key in the Authorization header as a Bearer token:

Authorization: Bearer veyra_your_key_here

Alternatively, you can use the X-API-Key header:

X-API-Key: veyra_your_key_here

Rate limiting

The conversation read endpoints are rate-limited to one request per company every 5 minutes. The limit applies across all read endpoints and all API keys belonging to the same company — it does not reset per key.

The order sync endpoints (POST /api/v1/shops/{shopId}/orders and DELETE /api/v1/shops/{shopId}/orders) are not rate-limited. You can call them as frequently as needed — for example from an order-created webhook in your webshop.

When the limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait, and a JSON body:

HTTP/1.1 429 Too Many Requests
Retry-After: 247

{
  "message": "Rate limit exceeded. Try again in 247 seconds."
}

Always check the Retry-After value before retrying. A simple pattern:

const res = await fetch('/api/v1/conversations', { headers })

if (res.status === 429) {
  const retryAfter = res.headers.get('Retry-After') // seconds
  console.log(`Rate limited — retry in ${retryAfter}s`)
  return
}

const data = await res.json()

Conversations

List conversations — returns a paginated list. Defaults to active conversations.

GET /api/v1/conversations?status=active&page=1&per_page=25

Query parameters: status (active or ended), page (default 1), per_page (1–100, default 25).

{
  "data": [
    {
      "conversationId": "conv_abc123",
      "shopId": "shop_xyz",
      "status": "active",
      "visitorName": "Jan de Vries",
      "visitorEmail": "jan@example.com",
      "createdAt": "2025-05-20T09:12:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 25
}

Get a single conversation — returns the conversation and all its messages in one response.

GET /api/v1/conversations/{id}

Messages

Returns all messages for a conversation in chronological order.

GET /api/v1/conversations/{id}/messages

[
  {
    "id": "msg_001",
    "conversationId": "conv_abc123",
    "sender": "visitor",
    "text": "Hi, where is my order?",
    "createdAt": "2025-05-20T09:12:05Z"
  },
  {
    "id": "msg_002",
    "sender": "agent",
    "text": "Let me check that for you!",
    "createdAt": "2025-05-20T09:12:40Z"
  }
]

Files

Returns all file attachments uploaded within a conversation. The url field is a direct link to download the file.

GET /api/v1/conversations/{id}/files

[
  {
    "id": "att_001",
    "conversationId": "conv_abc123",
    "sender": "visitor",
    "name": "order_screenshot.png",
    "size": 204800,
    "mimeType": "image/png",
    "url": "https://api.veyra.support/uploads/abc123.png",
    "createdAt": "2025-05-20T09:13:10Z"
  }
]

Files are stored for 72 hours by default. Download and store them on your side if you need them longer.

Product sync

The product sync endpoints let you push your product catalog to Veyra programmatically — useful for keeping Veyra in sync with your webshop platform without a manual CSV import. Authentication and rate-limit rules are the same as the order sync API: API-key auth, no rate limit.

A valid OpenAI API key must be configured for the website before importing products. Veyra generates a semantic embedding for each product so the AI can look them up. Configure the key under Websites → your website → AI tab.

Import / replace product catalog

Sends a JSON array of products. This replaces the entire catalog for the website — existing products are deleted and replaced with the new list. Maximum 2,000 products per call.

POST /api/v1/shops/{shopId}/products
Authorization: Bearer veyra_your_key_here
Content-Type: application/json

[
  {
    "name":        "Trail Runner X200",
    "description": "Lightweight waterproof trail running shoe",
    "price":       "€89.99",
    "sku":         "SKU-042",
    "url":         "https://myshop.com/trail-runner-x200"
  }
]

Field	Required	Description
name	Required	Product name. Used as the primary identifier for AI search. Products without a name are skipped.
description	Optional	A description of the product. The richer the description, the better the semantic search results.
price	Optional	Price as a string, e.g. "€29.99" or "29.99 EUR". Displayed to visitors and cited by the AI.
sku	Optional	Your internal stock-keeping unit code. Stored for reference but not used in search.
url	Optional	Direct URL to the product page. Visible in the admin catalog view.

Successful response:

HTTP/1.1 200 OK

{ "imported": 1, "skipped": 0 }

Delete all products

Removes the entire product catalog for the website.

DELETE /api/v1/shops/{shopId}/products
Authorization: Bearer veyra_your_key_here

HTTP/1.1 200 OK

{ "success": true }

Analytics

Dashboard overview

The admin dashboard (Admin → Dashboard) gives you a real-time snapshot of your support operation. Stat cards update every 30 seconds automatically.

Card	Description
Today	Total conversations started today. Resets at midnight (server time).
This week	Conversations started since Monday of the current ISO week.
This month	Conversations started since the 1st of the current calendar month.
Missed today	Conversations started today where no agent replied within the configured threshold. Turns red when non-zero.
Avg. rating	The all-time average visitor satisfaction rating (1–5 stars) across all rated conversations. Shows – when no ratings exist.

Below the stat cards, the dashboard shows a ranked list of agents by conversations handled and a scrollable list of recent conversations with their current status, visitor identity, and time since the last message.

Use the website selector in the top-right corner of the dashboard to filter all cards and lists to a single website. Selecting "All websites" (the default) shows aggregated data.

Performance metrics

Below the stat cards, the dashboard surfaces three key performance indicators computed over the last 30 days of ended conversations.

First response time

The average time between a conversation being created and the first message sent by an agent. A low first response time signals that agents are picking up conversations quickly. Shown as a human-readable duration (e.g. 2 min, 1h 5m).

Resolution time

The average time from conversation creation to it being marked as ended. Measures how long it takes your team to fully resolve an issue. Computed only on ended conversations in the last 30 days.

CSAT score

Customer Satisfaction score — the percentage of rated conversations where the visitor gave 4 or 5 stars. Displayed in green (≥ 80%), amber (60–79%), or red (< 60%). Shows the number of rated conversations below the score.

A conversations per day bar chart below the metric cards shows daily conversation volume for the last 30 days. Hovering a bar reveals the exact date and count. Days with no conversations appear as empty bars so the full timeline is always visible.

CSAT requires the visitor rating feature to be enabled in Settings → Visitor settings. All metrics require conversations — a freshly created account will show "–" until enough data has accumulated.

Settings

Business hours

Define the days and time ranges when your team is available. Outside these hours the chat widget is automatically hidden from visitors — they will not see the chat button, so no conversations start when nobody is there to respond.

Business hours apply account-wide. If you need different hours per website, use multiple accounts.

Sound notifications

Agents hear an alert sound in the dashboard whenever a new visitor message arrives. Visitors hear a sound when an agent replies in the widget.

Both sounds can be toggled independently in Settings → Notifications. Sounds require the dashboard to be open in an active browser tab.

Visitor settings

Visitor settings control how the chat widget interacts with visitors. These settings are account-wide and apply to all websites. Find them under Settings → Visitor settings.

Collect visitor info

When enabled, the widget prompts visitors to enter their name, email address, and optional order ID before being connected to an agent. This information is stored on the conversation and visible in the conversation detail panel.

Ask for a satisfaction rating

When enabled, a 1–5 star rating prompt is displayed in the widget after a conversation ends. Ratings are stored per conversation and feed the CSAT and Avg. rating metrics on the dashboard. Each visitor can rate only once per conversation.

Missed conversation threshold

The number of minutes after which a conversation with no agent reply is flagged as missed. Accepts values from 1 to 60 minutes. The default is 5 minutes. See Missed conversations for details on how missed conversations appear in the dashboard and conversation list.

White-labeling

Pro

Removes all Veyra branding from the visitor-facing chat widget. When enabled, the widget shows only your customised colors, greeting, and agent name — no Veyra logo or "Powered by" text. Available on the Pro plan only.

Changes to visitor settings take effect immediately for all new conversations. Ongoing conversations are not affected.

Language

The Veyra agent dashboard is available in six languages: English, Dutch, German, French, Polish, and Russian. Switch language using the selector in the bottom-left corner of the dashboard — the choice is saved per browser session.

The chat widget shown to visitors renders in the visitor's own browser language automatically, with the same six languages supported.

Offline contact form

When your team is offline (outside business hours and no agents are online), the chat widget can show a contact form instead of the normal chat. Visitors fill in their name, email address, and message — the form is submitted and an email is sent to your support inbox.

To enable the offline contact form, configure your SMTP settings in Settings → SMTP. Fill in the host, port, username, password, and the "from" address used for outgoing emails. Once saved, the contact form activates automatically whenever no agents are available.

Setting	Description
SMTP Host	The hostname of your mail server, e.g. smtp.gmail.com or mail.yourdomain.com.
SMTP Port	Typically 587 (STARTTLS) or 465 (SSL/TLS).
Username	The account used to authenticate with the SMTP server, usually an email address.
Password	The SMTP account password or app-specific password.
From address	The email address that appears in the From field of outgoing messages.

The same SMTP configuration is used for password-reset emails. Configuring it once enables both features.

Security & Privacy

Session management

Agent sessions expire after 2 hours of inactivity. On expiry you are redirected to the login page. Sessions are stored in HttpOnly, SameSite cookies — they are not accessible to JavaScript and cannot be stolen by XSS.

You can log out explicitly using the Sign out link at the bottom of the sidebar, which immediately invalidates the session on the server.

Two-factor authentication

Every agent account requires TOTP-based 2FA. Even if an agent's password is compromised, an attacker cannot log in without the rotating 6-digit code from the authenticator app.

See Agents → Two-factor authentication for setup instructions.

Data & privacy

Veyra does not collect personal information about your visitors beyond what they type in the chat. Visitors are identified only by an anonymous session identifier (e.g. "Visitor #A3F2C1"). No name, email, or IP address is stored unless the visitor types it themselves.

We do not sell, share, or use your data or your visitors' data for any purpose outside operating the Veyra service.

File retention

Files uploaded in conversations are stored on our servers for 72 hours and then automatically and permanently deleted. This applies to files sent by both agents and visitors.

Message text (the chat transcript) is retained as long as your account is active and is deleted when you close your account.

Activity & Audit

Activity log

The activity log records all significant actions taken by agents in your account. Admins can view it under Admin → Activity log. Each entry shows who did what, on which resource, and when.

Logged actions include:

Agent logins and logouts
Agent created, updated, or deleted
Website created, updated, or deleted
Conversation closed or forwarded
Settings changed (AI, SMTP, business hours)
Product catalog imported or deleted
API key created or revoked

The log is read-only and cannot be modified or deleted by anyone, including admins. It is retained for the lifetime of your account.

Referral Program

Referral program

Veyra has a built-in referral program that rewards you for bringing new customers to the platform. Every account gets a unique referral link visible in Admin → Referrals.

When someone signs up using your link and upgrades to a paid plan, you earn a 5% permanent discount on your own subscription — stacking up to a maximum of 40% off. The discount is applied immediately to your active subscription and continues on every future renewal automatically.

The referral dashboard shows:

Your unique referral link and a one-click copy button
Number of signups attributed to your link
Number of conversions (paid upgrades)
Your current discount percentage

The discount is applied automatically as soon as your referral converts to a paid plan — no action needed on your end. It applies to every renewal going forward, for as long as you remain subscribed.

Ready to get started?

Create your free account and have live chat on your website in under 5 minutes.

Create free account

Documentation

Getting Started

Requirements

Create an account

Add your first website

Embed the widget

The Widget

Embed code

Configuration attributes

Colors & branding

Conversations

Conversation list

Sending messages

File attachments

Conversation status

Filtering by website

Internal notes

Visitor ratings

Missed conversations

Tags & labels

Export

Tags & Labels

Managing tags

Filtering by tag

Departments

Overview

Forwarding conversations

Websites

Managing websites

Per-website embed code

Per-website branding

Agents

Inviting agents

Roles & permissions

Two-factor authentication

Agent profile

Presence status

Password reset

AI Assistant

Overview

Connecting OpenAI

System prompt

Enabling & disabling

Auto-translation

Auto-summary

Auto-sentiment

Product Catalog

Overview

CSV format

Importing products

How AI lookup works

Order Tracking

Overview

Sync API

Dashboard

AI order lookup

Public API

Overview

API keys

Authentication

Rate limiting

Conversations

Messages

Files

Product sync

Analytics

Dashboard overview

Performance metrics

Settings

Business hours

Sound notifications

Visitor settings

Language

Offline contact form

Security & Privacy

Session management

Two-factor authentication

Data & privacy

File retention

Activity & Audit