STACK
MENU
DOCS / API REFERENCE / CHAT CHANNELS

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 and Telegram bot 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.

Chat Channels | Docs