Documentation

Everything about Chatva: from the first script to the API.

Getting started Widget installation Connecting channels Widget configuration Team and departments Notifications Data export REST API OpenAPI

Getting started

Chatva collects every customer conversation into one inbox: the website widget, messengers and email. Agents reply from the dashboard, the bot handles common questions.

Create a company

Onboarding takes two minutes: name, plan, team invites.

Connect your first channel

The easiest start is the site widget or a Telegram bot.

Install the widget

One script before the closing body tag and you are live.

Open the demo dashboard

Widget installation

The widget installs with one script on every page before the closing body tag. The key in the code is a demo one, find yours in the dashboard on the Install tab.

<script src="https://cdn.chatva.app/widget.js" data-project="ch_test_a91f3" defer></script>

Where to paste

Platform	Where to paste
Tilda	Настройки сайта, Еще, HTML перед </body>
WordPress	Insert Headers and Footers, Scripts in Footer
1C-Битрикс	Настройки, Шаблоны, footer.php
InSales	Тема, Код, layouts/layout.liquid
Custom site	Общий шаблон или index.html

Script parameters

Parameter	Description
data-project	Project key from the dashboard
data-accent	Accent color, hex
data-position	Position: right or left
data-greeting	Header greeting
data-lang	Interface language: ru or en
data-collect	Contact collection: name,phone,email

Connecting channels

Chats arrive through your bot.

1
Open @BotFather and create a bot with /newbot.
2
Copy the token like 123456:ABC-DEF.
3
Paste the token in the Chatva dashboard: Channels, Telegram.

MAX

Connects with a code from the app.

1
Open MAX and find the official Chatva chat.
2
Enter the code from the dashboard, it is valid for 10 minutes.
3
Done — new conversations will appear in the inbox automatically.

WhatsApp Business via an official provider.

1
Enter your WhatsApp Business number.
2
Confirm the number with the SMS code.
3
Client messages will start arriving in the inbox.

VK

Messages of your VK community.

1
Press Connect and allow access in the VK popup.
2
Pick the community, messages appear in the inbox.
3
Operator replies will be sent on behalf of the community.

Avito

Messages from your listings.

1
Log in to Avito via OAuth.
2
Allow access to messages.
3
Conversations from your listings will appear in the inbox.

Email

Support emails turn into chats.

1
Set up forwarding to an address like support@yourco.chatva.app.
2
Replies to customers go out from your domain.
3
Emails will turn into conversations you can answer right from the inbox.

Widget configuration

Appearance

Color, position, corners, title, greeting and the Powered by Chatva label. Everything updates live in the preview.

Autoresponder

Quick buttons with custom answers, an offline message and handoff to a human: by trigger words or immediately.

Contact collection

Before the chat starts, the widget can ask for a name, phone or email. Fields are chosen in settings.

Receipts

The customer sees whether the message was delivered and read by a manager.

Behavior

Auto open after 10 seconds and night contact collection when everyone is offline.

Team and departments

Roles

The owner and admins see every chat and manage settings and the plan. Agents work with their own chats and department.

Capability	Owner	Admin	Agent
All company chats	✓	✓	-
Assign departments	✓	✓	-
Settings and channels	✓	✓	-
Plan and billing	✓	✓	-

Departments

Departments route chats: sales take orders, support handles questions. The inbox has a My department filter.

Invites

The limit depends on the plan: no invites on Start, Team gives five seats, Business is unlimited.

Notifications

Delivery channels

Browser push, Telegram bot, MAX bot and email. Pushes arrive even when the dashboard tab is closed.

Rules

New chat, chat unassigned for five minutes, mention in a note, morning digest and quiet hours from 21:00 to 8:00.

Data export

Export with chat selection: CSV and Excel with one row per message, JSON with the full chat structure.

JSON structure

{
  "exportedAt": "2026-09-06T12:00:00Z",
  "dialogs": [
    {
      "id": "c1",
      "client": "Кира Мещерякова",
      "channel": "Telegram",
      "messages": [
        {"from": "client", "time": "11:58", "text": "Здравствуйте!"}
      ]
    }
  ]
}

REST API

The API exposes conversations, messages, contacts and events — everything needed to integrate with your own systems. Typical scenarios:

CRM sync

Pull conversations and contacts into amoCRM, Bitrix24 or your own system on a schedule.

Automated client messages

Send messages into a conversation from your own logic: order status, appointment reminders, your bot's replies.

Real-time notifications

Subscribe to webhooks and receive new conversations and messages in Slack, Telegram or your issue tracker.

Backups

Export conversations regularly and store them yourself — the data belongs to you.

Base URL

Base URL
https://api.chatva.app/v1

Authorization

The key is created in settings on the Business plan and sent in the header.

Authorization: Bearer ch_live_9f3ka2

Endpoints

Method	Path	Description
GET	/conversations	Chat list with filters
GET	/conversations/{id}	Chat with all messages
POST	/messages	Send a message as an agent
GET	/contacts	Customer contacts
POST	/webhooks	Subscribe to chat events

Example request

curl https://api.chatva.app/v1/conversations?status=new \
  -H "Authorization: Bearer ch_live_9f3ka2"

Webhook events

Provide a URL when subscribing and we will POST JSON to it. Respond with 200 within 5 seconds, otherwise we retry up to three times.

Event	When it fires
message:new	A new message in any conversation — from a client, operator or bot
conversation:new	A new conversation is created in any channel
conversation:update	Conversation status, assignee, department or rating changed

Payload example

{
  "type": "message:new",
  "payload": {
    "conversation": {
      "id": "cv_018f3a",
      "channel": "telegram",
      "client": "Кира Мещерякова"
    },
    "message": {
      "id": "m_5521",
      "from": "client",
      "text": "Здравствуйте!",
      "createdAt": "2026-09-07T12:00:00Z"
    }
  }
}

Limits

120 requests per minute per key. Over the limit you get 429 with a Retry-After header.

Errors

{"error": {"code": "rate_limited", "message": "Retry after 30s"}}

OpenAPI

The full OpenAPI 3.0 specification. Imports into Postman, Insomnia and Swagger UI, and can generate a client for any stack.

Download openapi.jsonopenapi: 3.0.3

120 requests per minute per key. Over the limit you get 429 with a Retry-After header.