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

# Compatibility adapter V2 → V4

> What the compatibility adapter does, who this guide is for, and how it is organized.

# Compatibility adapter V2 → V4

The **compatibility adapter** accepts requests from clients of the old V2 platform in their original form and turns them into V4 campaigns. The client changes neither the request bodies nor how it parses responses: it sends the same JSON to its old address, and the current platform does the calling.

> [!NOTE]
>
> **Who this guide is for.** V2 clients who keep sending API requests in V2 form, their integrators, and the platform staff who set up such clients and monitor their campaigns: root organization administrators and agent developers.

> [!WARNING]
>
> **The adapter always responds with HTTP 200** and a V2-form body — including rejections and internal failures: V2 integrations break on any other status. Only the `type` field in the response body tells success from error. The response texts in this guide match the texts of the V2 installation `v2-mx` byte for byte; texts that did not exist in V2 are marked "added by the platform".

## How it works

The V2 client keeps sending requests to its old address, and the platform routes them to the adapter. The client signs in with its V2 login and password, which are set up as an **adapter account**.

* A `create` request passes the same checks as in V2 and becomes a campaign in the account's organization. One set of attributes "account, script, name, start hour, day, attempts" yields one campaign per day; further requests with the same attributes add batches of calls to it.
* `delete` and `delete_phone_number` withdraw contacts from the dialing campaign.
* `details` returns the day's calls export based on the report template.
* Fields of a request row become agent variables according to the map in the **compatibility registry**.

```
client system  --request in V2 form-->  adapter
                                          |  sign-in, limits
                                          |  V2 checks: keys, values, hours
                                          |  registry: script -> agent, fields -> variables
                                          v
                                        V4 campaign
                                          |
client system  <--response in V2 form, always HTTP 200--
```

## What is set up before the first request

Before the client's first request, a platform administrator sets up:

* **an adapter account** — the client's V2 login and password, the V4 organization where its campaigns will live, and dialing defaults for when a request does not pass a parameter. How to set it up: [Adapter accounts](https://docs.hubtalk.ai/v4/compat-adapter/accounts.md);
* **a compatibility registry** — one row for each script name the client sends in `data[].type`: which agent calls, which fields a request row carries, and how they reach the agent. How to build it: [Compatibility registry](https://docs.hubtalk.ai/v4/compat-adapter/registry.md).

The adapter login and password work **only for adapter requests**. They do not let you into the cabinet and do not open the public [Web API](https://docs.hubtalk.ai/v4/web-api.md); a Web API key and a cabinet login, in turn, do not open the adapter.

## Terms

| Term | Meaning |
| - | - |
| Compatibility adapter | The entry point that accepts V2 requests in their original form. |
| Adapter account | The V2 client's login and password plus the V4 organization and dialing defaults. Works only for adapter requests. |
| System | An installation of the old platform: **V2 · MX** or **V2 · KZ**. The first wave of clients is MX. |
| Compatibility registry | The account's scripts: V2 script name → V4 agent, the schema of request row fields, the variable map, retry rules, the dialing binding. |
| Script | A registry row. The script name is the `type` field in a `data[]` row of the client's request. |
| Compatibility adapter campaign | An ordinary V4 campaign created by a client request. In the cabinet it is marked with the source **Compatibility adapter**. |
| Adapter contact ID | A nine-digit number starting from 100 000 000 that the client receives in the response to `create` and passes to `delete`. |
| Daily export | The `details` operation: one day's calls based on the account's export template. |
| Adapter password store | A separate secure store that holds adapter account passwords. Passwords are not stored in the cabinet database. |

## The "in the logs" mark

Sometimes the reason for a rejection is visible only in the application log, not in the cabinet. In this guide such places are marked with the words **"in the logs"**. Platform engineers read the log: if you need such an investigation, give them the client's login, the operation, and the request time. Everything that can be seen in the cabinet is described through the cabinet. What exactly is written to the log is covered in [What is visible only in the logs](https://docs.hubtalk.ai/v4/compat-adapter/monitoring-calls.md#what-is-visible-only-in-the-logs).

## Sections

> [card] [API for the V2 client](https://docs.hubtalk.ai/v4/compat-adapter/request.md)
>
> Address, request body, sign-in and limits, the `create`, `delete`, `details` operations, differences from V2.

> [card] [Setup](https://docs.hubtalk.ai/v4/compat-adapter/accounts.md)
>
> Adapter accounts and the compatibility registry: setup, fields and variables, retry rules.

> [card] [Monitoring](https://docs.hubtalk.ai/v4/compat-adapter/monitoring.md)
>
> How to find an adapter campaign, its contacts, withdrawals, calls, and exports.

> [card] [FAQ](https://docs.hubtalk.ai/v4/compat-adapter/faq-variables.md)
>
> What goes wrong: variables, an empty queue, hours, webhooks, sign-in.


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