API reference

Chat channels

What this covers#

Connect a channel of your own to one of your agents, and the agent answers everyone who writes to it: a Telegram bot made with @BotFather (its webhook is set for you), or a WhatsApp number or Instagram professional account on your own Meta app (paste the response's webhook_url and meta.verify_token into the app's webhook settings). Tokens and secrets are sent once and never returned. WhatsApp and Instagram replies go out only within Meta's 24-hour window.

Every example below runs as written once these are exported:

bash

export DVAARIK_API_KEY="dvk_..."        # project API key, server side only
export DVAARIK_TOKEN="<account access token>"   # console session, from POST /console/auth/login
export CHANNEL_ID="<uuid>"
export PROJECT_ID="<uuid>"

A <value> inside a JSON body is a value you supply. Responses are JSON; every error body is { "detail": … }. Each schema is expanded once per page, where it first appears.

Machine door errors#

Raised by the project-key dependency before any handler on this page runs.

Status	Cause
`401`	`Missing API key` or `Invalid API key` — the `X-Api-Key` header is absent, unknown, or revoked.
`403`	`API key is not scoped to a project`, `Project unavailable`, or `API key is missing the required scope '<scope>'`.
`429`	The project's `api_rpm` ceiling was exceeded. Honour `Retry-After`; `X-RateLimit-*` headers are on every response.

Scopes used on this page: channel:read, channel:write. Mint a key with only these.

Account door errors#

Status	Cause
`401`	No account session was presented, or it is invalid or expired. Refresh once, then re-authenticate.
`403`	The account is suspended or its email is not verified.

Operations — project API key#

Call these from your own server with a project key. Never from a browser or a mobile bundle.

GET `/v2/chat-channels`#

List the project's channels with their state, webhook address, limits and, for WhatsApp and Instagram, what to paste into the Meta app. Never a token or a secret.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`channel:read`
Operation	`listChatChannels`
Success	`200` `ChatChannelPage`

`ChatChannelPage`#

Field	Type	Required	Notes
`data`	ChatChannelInfo[]	yes

`ChatChannelInfo`#

Field	Type	Required
`account_id`	string or null	yes
`account_name`	string or null	yes
`agent_id`	uuid or null	yes
`checked_at`	date-time or null	yes
`created_at`	date-time	yes
`disconnected_at`	date-time or null	yes
`id`	uuid	yes
`last_error`	string or null	yes
`last_error_at`	date-time or null	yes
`meta`	ChatChannelMeta or null	no
`name`	string	yes
`pending_updates`	integer or null	yes
`provider`	"telegram" or "whatsapp" or "instagram" or "api"	yes
`replies_per_day`	integer	yes
`replies_per_minute`	integer	yes
`status`	"active" or "error" or "disconnected"	yes
`turns_per_hour`	integer	yes
`updated_at`	date-time	yes
`webhook_url`	string	yes

`ChatChannelMeta`#

WhatsApp and Instagram: what to paste into your Meta app, and what Meta says about the account.

Field	Type	Required
`display_phone_number`	string or null	no
`subscription`	ChatChannelSubscription or null	no
`token_expires_at`	date-time or null	no
`token_refreshed_at`	date-time or null	no
`username`	string or null	no
`verified_name`	string or null	no
`verify_token`	string	yes
`waba_id`	string or null	no
`webhook_fields`	string[]	yes
`webhook_object`	"whatsapp_business_account" or "instagram"	yes

`ChatChannelSubscription`#

How subscribing your app to the account's webhooks went (Meta's subscribed_apps).

Field	Type	Required
`at`	date-time or null	no
`error`	string or null	no
`ok`	boolean	yes

`FieldErrors`#

A 422 from a route that names its fields: every field that failed validation, or one sentence when the request validated and was then refused.

Field	Type	Required	Notes
`detail`	string or FieldError[]	yes	The fields that failed validation (each named), or a sentence for the developer.

Error	When
`401`	No API key was sent in X-Api-Key, or it is invalid or revoked.
`403`	The API key lacks the scope this route needs, or its account or project is unavailable.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`429`	The project's requests-per-minute limit is reached; Retry-After says when to try again.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/v2/chat-channels" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

POST `/v2/chat-channels`#

Connect a Telegram bot, a WhatsApp number or an Instagram account to an agent. The token is checked with the provider first and a refused one is never stored. A Telegram webhook is set for you; for WhatsApp and Instagram, paste webhook_url and meta.verify_token into your Meta app.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`channel:write`
Operation	`createChatChannel`
Success	`201` `ChatChannelInfo`

Request body: ChatChannelCreate.

`ChatChannelCreate`#

Connect a channel to one of your agents: your own Telegram bot (its token from @BotFather), or a WhatsApp number or Instagram professional account on your OWN Meta app (the access token, the app secret that signs its webhooks, and the account's id). For WhatsApp and Instagram, paste the response's webhook_url and meta.verify_token into your Meta app's webhook settings.

Field	Type	Required	Notes
`access_token`	string or null	no
`agent_id`	uuid	yes
`app_secret`	string or null	no
`bot_token`	string or null	no
`instagram_account_id`	string or null	no
`instagram_app_secret`	string or null	no
`name`	string	yes	min length 1; max length 120
`phone_number_id`	string or null	no
`provider`	"telegram" or "whatsapp" or "instagram"	yes
`replies_per_day`	integer or null	no
`replies_per_minute`	integer or null	no
`turns_per_hour`	integer or null	no
`waba_id`	string or null	no

Error	When
`401`	No API key was sent in X-Api-Key, or it is invalid or revoked.
`403`	The API key lacks the scope this route needs, or its account or project is unavailable.
`404`	The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
`409`	A limit or the resource's state refuses this change; the sentence says which.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`429`	The project's requests-per-minute limit is reached; Retry-After says when to try again.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/v2/chat-channels" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent uuid>",
    "name": "Support bot",
    "provider": "telegram",
    "bot_token": "<token from @BotFather>"
  }'

DELETE `/v2/chat-channels/{channel_id}`#

Disconnect the channel: it stops answering at once and its credentials are forgotten. A Telegram webhook is deleted while it still points here; a Meta app keeps its callback URL until you change it.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`channel:write`
Operation	`disconnectChatChannel`
Success	`200` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`channel_id`	path	uuid	yes

Error	When
`401`	No API key was sent in X-Api-Key, or it is invalid or revoked.
`403`	The API key lacks the scope this route needs, or its account or project is unavailable.
`404`	The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`429`	The project's requests-per-minute limit is reached; Retry-After says when to try again.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X DELETE "https://api.developers.dvaarik.com/v2/chat-channels/$CHANNEL_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

GET `/v2/chat-channels/{channel_id}`#

Read one channel.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`channel:read`
Operation	`getChatChannel`
Success	`200` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`channel_id`	path	uuid	yes

Error	When
`401`	No API key was sent in X-Api-Key, or it is invalid or revoked.
`403`	The API key lacks the scope this route needs, or its account or project is unavailable.
`404`	The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`429`	The project's requests-per-minute limit is reached; Retry-After says when to try again.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/v2/chat-channels/$CHANNEL_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

PATCH `/v2/chat-channels/{channel_id}`#

Rename the channel, answer with another agent, change its limits, or give the same account's new credentials: a bot's new token; a new access token, app secret or WABA id. Only the fields you send change; the verify token never does.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`channel:write`
Operation	`updateChatChannel`
Success	`200` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`channel_id`	path	uuid	yes

Request body: ChatChannelUpdate.

`ChatChannelUpdate`#

Rename, answer with another agent, change the limits, or give the SAME account's new credentials: a bot's new token (Telegram); a new access token, app secret or WABA id (WhatsApp, Instagram). A new token is checked against the account before it is saved.

Field	Type	Required
`access_token`	string or null	no
`agent_id`	uuid or null	no
`app_secret`	string or null	no
`bot_token`	string or null	no
`instagram_app_secret`	string or null	no
`name`	string or null	no
`replies_per_day`	integer or null	no
`replies_per_minute`	integer or null	no
`turns_per_hour`	integer or null	no
`waba_id`	string or null	no

Error	When
`401`	No API key was sent in X-Api-Key, or it is invalid or revoked.
`403`	The API key lacks the scope this route needs, or its account or project is unavailable.
`404`	The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
`409`	A limit or the resource's state refuses this change; the sentence says which.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`429`	The project's requests-per-minute limit is reached; Retry-After says when to try again.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X PATCH "https://api.developers.dvaarik.com/v2/chat-channels/$CHANNEL_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "replies_per_minute": 20
  }'

POST `/v2/chat-channels/{channel_id}/check`#

Ask the provider now: Telegram's last error and the messages it still holds, or whether Meta still accepts the token, with your app subscribed again. A refused token turns the channel error.

Detail	Value
Door	Project API key — `X-Api-Key: $DVAARIK_API_KEY`
Scope	`channel:write`
Operation	`checkChatChannel`
Success	`200` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`channel_id`	path	uuid	yes

Error	When
`401`	No API key was sent in X-Api-Key, or it is invalid or revoked.
`403`	The API key lacks the scope this route needs, or its account or project is unavailable.
`404`	The addressed resource does not exist in this key's project. One in another project is deliberately indistinguishable from one that never existed.
`409`	A limit or the resource's state refuses this change; the sentence says which.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.
`429`	The project's requests-per-minute limit is reached; Retry-After says when to try again.

Plus the machine-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/v2/chat-channels/$CHANNEL_ID/check" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

Operations — account session#

The same resource through the console door. These are what the web console calls; both doors return the same shapes.

GET `/console/v2/projects/{project_id}/chat-channels`#

List the project's channels with their state, webhook address, limits and, for WhatsApp and Instagram, what to paste into the Meta app. Never a token or a secret.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleListChatChannels`
Success	`200` `ChatChannelPage`

Parameter	In	Type	Required	Notes
`project_id`	path	uuid	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chat-channels" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

POST `/console/v2/projects/{project_id}/chat-channels`#

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleCreateChatChannel`
Success	`201` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`project_id`	path	uuid	yes

Request body: ChatChannelCreate.

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`409`	The project or resource is in a state that refuses this change.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chat-channels" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent uuid>",
    "name": "Support bot",
    "provider": "telegram",
    "bot_token": "<token from @BotFather>"
  }'

DELETE `/console/v2/projects/{project_id}/chat-channels/{channel_id}`#

Disconnect the channel: it stops answering at once and its credentials are forgotten. A Telegram webhook is deleted while it still points here; a Meta app keeps its callback URL until you change it.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleDisconnectChatChannel`
Success	`200` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`channel_id`	path	uuid	yes
`project_id`	path	uuid	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`409`	The project or resource is in a state that refuses this change.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X DELETE "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chat-channels/$CHANNEL_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

GET `/console/v2/projects/{project_id}/chat-channels/{channel_id}`#

Read one channel.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleGetChatChannel`
Success	`200` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`channel_id`	path	uuid	yes
`project_id`	path	uuid	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chat-channels/$CHANNEL_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

PATCH `/console/v2/projects/{project_id}/chat-channels/{channel_id}`#

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleUpdateChatChannel`
Success	`200` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`channel_id`	path	uuid	yes
`project_id`	path	uuid	yes

Request body: ChatChannelUpdate.

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`409`	The project or resource is in a state that refuses this change.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X PATCH "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chat-channels/$CHANNEL_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "replies_per_minute": 20
  }'

POST `/console/v2/projects/{project_id}/chat-channels/{channel_id}/check`#

Ask the provider now: Telegram's last error and the messages it still holds, or whether Meta still accepts the token, with your app subscribed again. A refused token turns the channel error.

Detail	Value
Door	Account session — `Authorization: Bearer $DVAARIK_TOKEN`
Operation	`consoleCheckChatChannel`
Success	`200` `ChatChannelInfo`

Parameter	In	Type	Required	Notes
`channel_id`	path	uuid	yes
`project_id`	path	uuid	yes

Error	When
`401`	No account session was presented, or it is invalid or expired.
`403`	The account is suspended or its email is not verified.
`404`	The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed.
`409`	The project or resource is in a state that refuses this change.
`422`	The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field.

Plus the account-door errors above. Full list on the errors page.

bash

curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/chat-channels/$CHANNEL_ID/check" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

Try it without a key in the browser

The playground opens a real voice session with your account session, so a project key never reaches a browser. Machine calls belong on your own server.

Open the playground Quickstart

Chat channels

What this covers#

Machine door errors#

Account door errors#

Operations — project API key#

GET /v2/chat-channels#

ChatChannelPage#

ChatChannelInfo#

ChatChannelMeta#

ChatChannelSubscription#

FieldErrors#

POST /v2/chat-channels#

ChatChannelCreate#

DELETE /v2/chat-channels/{channel_id}#

GET /v2/chat-channels/{channel_id}#

PATCH /v2/chat-channels/{channel_id}#

ChatChannelUpdate#

POST /v2/chat-channels/{channel_id}/check#

Operations — account session#

GET /console/v2/projects/{project_id}/chat-channels#

POST /console/v2/projects/{project_id}/chat-channels#

DELETE /console/v2/projects/{project_id}/chat-channels/{channel_id}#

GET /console/v2/projects/{project_id}/chat-channels/{channel_id}#

PATCH /console/v2/projects/{project_id}/chat-channels/{channel_id}#

POST /console/v2/projects/{project_id}/chat-channels/{channel_id}/check#

GET `/v2/chat-channels`#

`ChatChannelPage`#

`ChatChannelInfo`#

`ChatChannelMeta`#

`ChatChannelSubscription`#

`FieldErrors`#

POST `/v2/chat-channels`#

`ChatChannelCreate`#

DELETE `/v2/chat-channels/{channel_id}`#

GET `/v2/chat-channels/{channel_id}`#

PATCH `/v2/chat-channels/{channel_id}`#

`ChatChannelUpdate`#

POST `/v2/chat-channels/{channel_id}/check`#

GET `/console/v2/projects/{project_id}/chat-channels`#

POST `/console/v2/projects/{project_id}/chat-channels`#

DELETE `/console/v2/projects/{project_id}/chat-channels/{channel_id}`#

GET `/console/v2/projects/{project_id}/chat-channels/{channel_id}`#

PATCH `/console/v2/projects/{project_id}/chat-channels/{channel_id}`#

POST `/console/v2/projects/{project_id}/chat-channels/{channel_id}/check`#