# Chat Channels API

Two things use a chat app. The owner links a chat identity to approve held payments from Telegram, a text or Slack. An agent has a Telegram bot of its own to talk with people. The steps are in the [Approvals](/docs/controls/approvals) and [Telegram bot](/docs/account/telegram) guides.

## Chat identities for approvals

Owner or admin only, except the list, which any member can read, and removing a link, which removes only your own. An agent is refused on every route here. Starting a link needs the OAuth scope `accounts:manage`. The steps marked browser only take a signed-in Console session and no token.

### GET /v1/chat-channels

- channels - for telegram, sms and slack: whether the channel is available (configured), the approvals bot's username for Telegram, and the installed workspace for Slack.
- identities[] - id, channel, member_id, status, display, created_at and confirmed_at. The link itself is returned only by the call that starts it.
- status is awaiting_chat, awaiting_code, awaiting_confirm, active or revoked.
- code_attempts - how many tries a texted code allows.

### POST /v1/chat-channels/identities

- { channel, phone? } - channel is telegram, sms or slack. phone is required for sms and refused for the others.
- The answer holds link: a url to open in Telegram, or a command to send in Slack, with expires_at. A link lasts 10 minutes.
- Starting an sms link is browser only.

### The remaining steps

- POST /v1/chat-channels/identities/:id/verify { code } - the six-digit code from a text. Browser only. Five tries.
- POST /v1/chat-channels/identities/:id/confirm - the owner confirms the identity. Browser only. Until this, the identity approves nothing.
- DELETE /v1/chat-channels/identities/:id - ends an identity.
- GET /v1/chat-channels/slack/install-url?redirect_uri&state - the address that installs the Slack app.
- POST /v1/chat-channels/slack/install { code, redirect_uri } - completes the install. Browser only.
- DELETE /v1/chat-channels/slack - removes the Slack install.

A linked identity can approve a held card or wallet payment, and nothing else, and only within the two limits set in the policy under `review.chat`. The decision is recorded with the channel it came from.

## An agent's own Telegram bot

- PUT /v1/accounts/:id/telegram { bot_token } - connects the bot that BotFather gave you. Owner or admin only. No OAuth token may call it: use an API key, the terminal or the Console. Answers 201.
- GET /v1/accounts/:id/telegram - bot_id, username, status and start_url, the link people open to write to the bot. 404 when the account has no bot.
- GET /v1/accounts/:id/telegram/chats - the 100 most recent chats that wrote to the bot: chat_id, chat_type (private, group or supergroup), label, first_seen_at, last_inbound_at and blocked.
- DELETE /v1/accounts/:id/telegram - disconnects the bot. Answers 204.
- POST /v1/accounts/:id/telegram/messages { chat_id, text } - answers a chat. The account's own agent with its Passport, or the owner. text is plain, at most 4,096 characters. One action.
- GET /v1/accounts/:id/messages?channel=telegram - what people wrote.

A person has to write to the bot first. A send to a chat that never wrote is `403 TELEGRAM_SEND_REFUSED` with the reason `chat_unknown`. The other reasons are `chat_blocked`, `no_bot` and `bot_unavailable`. With controls on, a send is asked as `telegram.send`.
