Migration from Channels v1 to Auths v2

Move from API v1 Channels to API v2 Auths and auth webhooks

API v1 Channels are being replaced by API v2 Auths. An auth is the v2 name for a connected messaging provider (WhatsApp, Telegram, VK, and others).

This guide helps you switch integrations that create, list, update, or delete channels — and that listen for channel-related webhooks.

Warning

API v1 Channels will be shut down. The exact date will be announced later this year. After shutdown, Channels v1 will not work at all — migrate to Auths.

What changes

The entity is the same — connected messaging accounts. What changes is the API:

What	API v1	API v2
Base URL	`https://api.pact.im/p1/...`	`https://api.pact.im/api/p2/...`
Channel webhooks	Data with `entity: "channel"`, `type: "qr_code"`, and similar fields — see Webhooks v1	Unified format with `"type": "auth"` and `"event": "create" \| "update" \| "delete"` — see Auth events
How to confirm a channel	`request_code` / `confirm` methods and webhook data (QR, etc.)	Confirm auth (QR, code, or OAuth) and Enable auth when needed
Channel API methods	`/p1/companies/:company_id/channels/...`	`/api/p2/companies/:company_id/auths/...` — see Auths

Token auth still uses your private API token. In v2 you typically pass private_api_token as a query or body parameter — see Authentication.

Endpoint mapping

Action	API v1 (Channels)	API v2 (Auths)
List	`GET /p1/companies/:company_id/channels`	Get company auths — `GET /api/p2/companies/:company_id/auths`
Create / connect	`POST /p1/companies/:company_id/channels`	Create auth — `POST /api/p2/companies/:company_id/auths`
Confirm (code / enable)	`POST .../channels/:id/request_code`, `POST .../channels/:id/confirm`	Confirm auth and Enable auth
Disable / pause	—	Disable auth
Re-enable	—	Enable auth
Delete	`DELETE /p1/companies/:company_id/channels/:id`	Delete auth
List across companies	—	Get auths (multi-company)

Provider-specific create parameters (token, phone number, sync period, and so on) are documented on Create auth.

Confirmation flows (QR, code, OAuth)

In v1, confirmation was spread across channel create, request_code, confirm, and webhook payloads (for example QR codes).

In v2:

Create auth for the provider.
Complete the flow described in Confirm auth:
- QR — WhatsApp, Telegram Personal, MAX (qr in the response and in webhooks)
- Code — WhatsApp / Telegram Personal when phone_number is provided
- OAuth — Facebook, VK, Instagram Business, WhatsApp Business, Avito (oauth_provider_url)
Use Enable auth when the provider requires a verification code (for example Telegram Personal code flow).

Migrating webhooks

v1 channel lifecycle events used payloads with entity: "channel", type: "qr_code", and similar shapes under v1 Webhooks.

v2 delivers a single envelope with "type": "auth" and "event": "create" | "update" | "delete". Full payloads and meanings are in Auth events.

Situation	v2 auth event
Auth created	`event: create`
Connected / ready	`event: update` with `state: enabled`
Disconnected	`event: update` with `state: disabled`
Deleted	`event: delete`
QR refresh, pages list, OAuth progress	`event: update` (see auth-events examples)

Checklist for webhook handlers

Register or update a company webhook URL with Company webhooks (if you are not already receiving v2 events).
Accept the v2 envelope: event, type, object.
When type === "auth", read provider state from object (and pages / qr / oauth_provider_url when present).
Stop relying on v1-only fields such as channel_id, channel_type, or entity: "channel" for new logic.
Keep v1 handlers only while you still have traffic on the old API; plan to turn them off after cutover.

Suggested migration steps

Read the v2 Auths overview — Auths and the Auth object.
Map your calls — replace each Channels endpoint you use with the matching Auths method above.
Update create + confirm — follow Create auth and Confirm auth for each provider you support.
Switch webhooks — implement handling for Auth events; verify create / connect / disconnect / delete in a staging company.
Smoke-test — list auths, create one test auth, complete confirmation, confirm webhooks, then delete or disable the test auth.
Cut over — point production traffic to v2; remove v1 Channels usage when ready.