Channel API

The Channel API lets any messaging service — Slack, Discord, Telegram, or your own — act as a frontend for chat.dev. Users on your platform can create agents, send tasks, attach files, and receive responses through your interface.

Overview#

A channel is a connection between your messaging platform and chat.dev. When you create a channel, you get:

• An API key for authenticating inbound messages
• A webhook secret for verifying outbound message signatures
• A callback URL where chat.dev delivers agent responses

There are two directions of traffic:

• Inbound: your app calls POST /api/channels/:channelId/inbound when one of your users sends a message, clicks a command button, or uploads an attachment.
• Outbound: chat.dev calls your callbackUrl when it needs to send a message back later, such as agent progress, task output, or asynchronous status updates.

The callbackUrl is your HTTPS endpoint for outbound delivery. It should accept a JSON POST, verify the X-Webhook-Signature, then render or deliver the message to the user or group identified by externalUserId and groupExternalId.

Authentication#

Management endpoints#

Channel CRUD operations require a session cookie (same auth as the web dashboard).

Inbound messages#

Pass the API key in the Authorization: Bearer <key> header.

The API key authenticates your integration to chat.dev. It is not a user token and should never be shown to end users.

Outbound webhooks#

chat.dev signs every outbound payload with HMAC-SHA256 using your webhook secret. Verify the X-Webhook-Signature header:

const crypto = require("crypto");

function verifySignature(body, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Endpoints#

Endpoint index#

chat.dev also sends outbound webhook requests to your channel's callbackUrl. That is not a chat.dev API endpoint; it is your HTTPS endpoint that receives POST requests from chat.dev.

Create a channel#

Use this endpoint from an authenticated chat.dev web session. It creates a channel owned by the logged-in chat.dev user.

POST /api/channels
Content-Type: application/json
Cookie: <session>

{
  "name": "My Slack Bot",
  "platform": "slack",
  "callbackUrl": "https://your-server.com/chat-dev-webhook"
}

Fields:

Response (201):

{
  "id": "ch_abc123",
  "name": "My Slack Bot",
  "platform": "slack",
  "callbackUrl": "https://your-server.com/chat-dev-webhook",
  "apiKey": "chk_...",
  "webhookSecret": "whsec_..."
}

Save the apiKey and webhookSecret immediately — the API key is only shown once.

List channels#

GET /api/channels
Cookie: <session>

Delete a channel#

DELETE /api/channels/:id
Cookie: <session>

Rotate API key#

POST /api/channels/:id/rotate-key
Cookie: <session>

Returns a new apiKey.

Send an inbound message#

The main endpoint your integration calls when a user sends a message.

POST /api/channels/:channelId/inbound
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "externalUserId": "U12345",
  "displayName": "Alice",
  "message": "/create my-agent",
  "messageId": "msg_unique_id",
  "isGroup": false,
  "groupExternalId": "G67890",
  "groupName": "Engineering",
  "participants": ["U12345", "U67890"],
  "attachments": [
    {
      "url": "https://your-cdn.example.com/uploads/screenshot.png",
      "contentType": "image/png",
      "filename": "screenshot.png"
    }
  ]
}

Identity rules:

• externalUserId is scoped to this channel. Use the stable user ID from your platform, not a display name.
• For DMs, omit isGroup or set it to false.
• For group conversations, set isGroup: true and include a stable groupExternalId. Group members can write @chatdev message to use their own chat.dev account tools in the shared group, or @agentname message to talk to one of their own agents or an agent shared into that group. Follow-up messages from the same sender stick to the last @chatdev or @agentname target until they mention a different target.
• participants is optional. If supplied, chat.dev can sync known group members, but channel users are only auto-created when they send their first message.

Response:

{
  "ok": true,
  "replies": [
    "Agent 'my-agent' created and starting..."
  ]
}

Synchronous replies appear in the replies array. Async agent output (task results, status updates) is delivered to your callback URL via webhook.

Your integration should display every normal string in replies to the user. A reply prefixed with __structured: contains machine-readable JSON for your backend and usually should not be shown raw in the user interface.

If chat.dev returns a continue-setup link, show it to the user. Channel users can start without browser setup, but once they hit the free agent or prompt/API limits they need to finish setup before continuing.

Channel command endpoints#

All command endpoints use the same Authorization: Bearer <apiKey> header as inbound messages. They expose the slash commands as structured API calls so clients do not have to send command text through /inbound.

Common request body fields for every command endpoint:

For group commands, include:

{
  "externalUserId": "U12345",
  "isGroup": true,
  "groupExternalId": "G67890",
  "groupName": "Engineering"
}

Command endpoints return the same shape as inbound messages unless noted:

{
  "ok": true,
  "replies": ["..."]
}

Command endpoint argument reference

Command request examples

Create an agent:

{
  "externalUserId": "U12345",
  "displayName": "Alice",
  "name": "my-agent"
}

Load or start an agent:

{
  "externalUserId": "U12345",
  "agentName": "my-agent"
}

Send a task to the loaded agent:

{
  "externalUserId": "U12345",
  "prompt": "Fix the failing checkout test and open a PR."
}

Run a group command:

{
  "externalUserId": "U12345",
  "displayName": "Alice",
  "isGroup": true,
  "groupExternalId": "G67890",
  "groupName": "Engineering",
  "agentName": "team-agent"
}

Fund an agent:

{
  "externalUserId": "U12345",
  "agentName": "my-agent",
  "amountUsd": 25
}

Fork an agent from a connected repo:

{
  "externalUserId": "U12345",
  "name": "bugfix-agent",
  "repo": "owner/repo"
}

Get loaded agent terminal link

POST /api/channels/:channelId/commands/getlink
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "externalUserId": "U12345",
  "displayName": "Alice",
  "groupExternalId": "G67890"
}

groupExternalId is optional. Include it when the button was clicked in a group conversation so chat.dev can use the group's loaded shared agent.

Response:

{
  "agent": { "name": "my-agent", "status": "running" },
  "url": "https://chat.dev/api/auth/session-login?sid=...",
  "message": "Open \"my-agent\" in chat.dev: https://chat.dev/api/auth/session-login?sid=..."
}

Opening url signs the user into chat.dev and shows the real agent page with the live terminal. This is intentionally different from the public sanitized history page.

Get agent wallet public key

POST /api/channels/:channelId/commands/getwallet
Authorization: Bearer <apiKey>
Content-Type: application/json

{
  "externalUserId": "U12345",
  "displayName": "Alice",
  "agentName": "my-agent",
  "groupExternalId": "G67890"
}

agentName is optional. If omitted, chat.dev uses the loaded agent for the user or group. groupExternalId is optional; include it to look up an agent shared into that group before falling back to the user's own agents.

Response:

{
  "agent": { "name": "my-agent", "status": "running" },
  "publicKey": "7xK...",
  "message": "my-agent wallet public key: 7xK..."
}

Text command shortcuts#

Channel UIs can also expose text shortcuts. When your app sends:

{
  "externalUserId": "U12345",
  "message": "/getlink"
}

chat.dev replies with a one-click login URL for the currently loaded agent.

When your app sends:

{
  "externalUserId": "U12345",
  "message": "/getwallet my-agent"
}

chat.dev replies with that agent's wallet public key.

Outbound webhook format#

When an agent sends a response, chat.dev POSTs to your callback URL:

{
  "event": "message.send",
  "channelId": "ch_abc123",
  "externalUserId": "U12345",
  "groupExternalId": "G67890",
  "message": "I've created the Express server. Here's what I did..."
}

Headers:

• Content-Type: application/json
• X-Webhook-Signature: <HMAC-SHA256 hex digest>
• X-Channel-Id: ch_abc123

Delivery expectations:

• Respond with any 2xx status after you accept the message.
• Use externalUserId to route DMs.
• Use groupExternalId when present to route group messages.
• Validate the signature against the raw request body using the channel's webhookSecret.
• Treat duplicate payloads idempotently; future retry behavior may redeliver the same logical message.

Text-only channel registration#

For integrations that operate purely via messaging (no browser onboarding), register a text-only channel using a registration key. This bypasses the session-cookie requirement entirely.

POST /api/channels/register
Content-Type: application/json

{
  "registrationKey": "<secret>",
  "name": "My Telegram Bot",
  "callbackUrl": "https://your-server.com/chat-dev-webhook",
  "platform": "telegram",
  "ownerEmail": "you@example.com"
}

Response (201):

{
  "id": "ch_abc123",
  "name": "My Telegram Bot",
  "platform": "telegram",
  "callbackUrl": "https://your-server.com/chat-dev-webhook",
  "apiKey": "chk_...",
  "webhookSecret": "whsec_...",
  "textOnly": true
}

How text-only channels differ#

• No browser required to start. Users can create and use agents from the channel immediately.
• Freemium account setup. Channel-created users receive the same free agent/runtime/API allowance as lightweight web signups. They only receive a continue-setup link after they hit the free agent or prompt/API usage limits.
• Auto-onboarding. On a user's first message, they receive a welcome message with an explanation of chat.dev, available commands, links to the Terms of Service and Privacy Policy, and their auto-generated SOL wallet address.
• Implicit consent. The welcome message states: "By continuing to communicate with this channel you agree to these terms."
• SOL wallet. Each new user automatically gets a Solana deposit address for funding agents. The address is included in the welcome text and in a structured JSON reply:

{
  "type": "welcome",
  "solAddress": "7xK...",
  "tosUrl": "https://chat.dev/terms",
  "privacyUrl": "https://chat.dev/privacy"
}

Structured replies are prefixed with __structured: in the replies array. Parse the JSON after that prefix to extract wallet addresses programmatically.

User accounts#

Channel users get auto-created chat.dev accounts on first message. Each user is identified by channelId + externalUserId. Users can link their channel identity to an existing chat.dev account via the /login command.

All commands#

Channel users have access to the same commands as SMS users. See the Commands page.

Every slash command exposed to channel users can be called as a dedicated API endpoint under POST /api/channels/:channelId/commands/.... The complete endpoint list and request fields are in the Channel command endpoints section above.