Agent Messaging & Channels

Overview

The Shinzo agent messaging system lets you send messages to agents and retrieve conversation history. Agents support communication through the API, Discord, Slack, and Telegram channels. Messages are automatically routed back through the channel they originated from.

Supported channels: Discord, Slack, and Telegram are fully supported. WhatsApp support is coming soon.

Sending Messages

Send a message to an agent with POST /v1/agent/:id/messages:

curl -X POST https://api.app.shinzo.ai/v1/agent/AGENT_ID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Summarize the latest project updates.",
    "channel": "api",
    "queue_mode": "collect"
  }'

Request Parameters

Parameter	Type	Required	Default	Description
`content`	string	✅	—	The message text to send to the agent
`metadata`	object	❌	—	Arbitrary key-value metadata to attach to the message
`channel`	enum	❌	`"api"`	Channel to send through: `api`, `discord`, or `slack`
`queue_mode`	enum	❌	`"collect"`	How to handle messages when the agent is busy: `collect` or `interrupt`

Response Format

A successful request returns the created message object:

{
  "id": "msg_abc123",
  "role": "user",
  "content": "Summarize the latest project updates.",
  "status": "pending",
  "channel": "api",
  "queue_mode": "collect",
  "created_at": "2026-02-18T10:30:00Z"
}

Listing Messages

Retrieve conversation history with GET /v1/agent/:id/messages:

curl -X GET "https://api.app.shinzo.ai/v1/agent/AGENT_ID/messages?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

Parameter	Type	Default	Description
`limit`	number	`50`	Number of messages to return (1-100)
`before`	string	—	Return messages before this message UUID (cursor)
`after`	string	—	Return messages after this message UUID (cursor)
`status`	enum	—	Filter by status: `pending`, `delivered`, or `read`
`channel`	enum	—	Filter by channel: `api`, `discord`, or `slack`

Response Format

{
  "messages": [
    {
      "id": "msg_abc123",
      "role": "user",
      "content": "Summarize the latest project updates.",
      "status": "delivered",
      "channel": "api",
      "queue_mode": "collect",
      "reply_to_id": null,
      "created_at": "2026-02-18T10:30:00Z",
      "delivered_at": "2026-02-18T10:30:01Z",
      "read_at": null
    },
    {
      "id": "msg_def456",
      "role": "assistant",
      "content": "Here is a summary of the latest project updates...",
      "status": "delivered",
      "channel": "api",
      "queue_mode": null,
      "reply_to_id": "msg_abc123",
      "created_at": "2026-02-18T10:30:05Z",
      "delivered_at": "2026-02-18T10:30:05Z",
      "read_at": null
    }
  ],
  "has_more": false
}

Cursor-Based Pagination

Use the before and after parameters with message UUIDs to paginate through results. To fetch the next page, pass the last message’s id as the after parameter:

curl -X GET "https://api.app.shinzo.ai/v1/agent/AGENT_ID/messages?after=msg_def456&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Continue paginating until has_more is false.

Message States

Messages transition through three states:

State	Description
`pending`	Message has been received and is queued for processing
`delivered`	Message has been delivered to the agent or sent back to the user
`read`	Message has been read/acknowledged

Queue Modes

Queue modes control how the agent handles incoming messages when it is already processing a task.

Collect Mode

{ "queue_mode": "collect" }

Messages are batched in the agent’s queue while it processes the current task. Once the agent finishes, it picks up all queued messages together. This is the default behavior and is ideal for most use cases.

Use collect mode when message order matters or when you want to batch related requests. The agent processes all collected messages as a group once it becomes available.

Interrupt Mode

{ "queue_mode": "interrupt" }

The agent’s current task is cancelled immediately, and the new message is processed right away. Use this for high-priority messages that cannot wait.

Interrupt mode cancels the agent’s in-progress work. Any partial results from the interrupted task may be lost. Use this only when the new message genuinely takes priority.

Channel Routing

When a message arrives through a specific channel (for example, Discord), the agent’s response is automatically routed back through that same channel. You do not need to specify the return channel — the platform handles this for you. This means:

A message sent via the API receives its response via the API
A message sent via Discord receives its response as a Discord message
A message sent via Slack receives its response as a Slack message
A message sent via Telegram receives its response as a Telegram message
The same agent can handle conversations across multiple channels simultaneously

An agent can maintain active conversations across multiple channels simultaneously. Each channel operates independently with its own message history.

Discord Integration

Discord is a fully supported external channel. Linking your agent to Discord allows users to interact with it directly through Discord direct messages via the Shinzo bot. Use cases:

Personal assistant. Link your agent to Discord and interact with it throughout the day without leaving your chat client.
Team collaboration. Team members can each link to the same agent for shared access to tools and knowledge.
Notification delivery. Configure webhooks to trigger agent messages that are delivered directly to your Discord DMs.
Rapid prototyping. Test agent behavior interactively through Discord during development without building a custom frontend.

Setting Up the Shinzo Bot

Before linking, you must create a Discord bot application and configure it in Shinzo: Step 1: Create a Discord application

Visit discord.com/developers/applications and click “New Application”
Give your application a name and click Create
Navigate to the Bot section in the left sidebar
Click “Add Bot” and confirm

Step 2: Get your bot token

Under the Bot section, click “Reset Token” to generate a new bot token
Copy the token immediately — it won’t be shown again
Enable the following Privileged Gateway Intents:
- Message Content Intent
- Server Members Intent
- Presence Intent

Keep your bot token secret! Anyone with this token can control your bot. Never commit it to version control or share it publicly.

Step 3: Configure the bot token in your agent Add the bot token to your agent’s configuration:

curl -X PATCH "https://api.app.shinzo.ai/v1/agent/AGENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "discord_bot_token": "your-discord-bot-token"
  }'

Alternatively, set this during agent creation with the discord_bot_token field in the POST /v1/agent request.

Need help? See Discord’s official documentation on Creating a Bot and Bot Tokens for detailed instructions.

Linking Your Discord Account

After configuring your bot token, you can link your Discord user account to your agent: Step 1: Generate a link code Request a 6-character link code from the API with POST /v1/agent/:id/discord/link:

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/discord/link" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response includes the code and its expiration time:

{
  "code": "A1B2C3",
  "expires_at": "2026-02-18T10:40:00Z"
}

Link codes expire after 10 minutes. If the code expires before it is used, generate a new one.

Step 2: Link via Discord Send the following command as a direct message to your bot on Discord:

/link A1B2C3

The bot confirms the link and your agent is now connected to your Discord account. Step 3: Start chatting Send any message to your bot on Discord, and it will be routed to your linked agent. The agent’s response comes back as a Discord message.

What are link codes for? Link codes pair your Discord user identity with your Shinzo account so messages from you are properly attributed. The bot token setup and link code flow are two separate steps — the token activates the bot, and the link code associates your user account with it.

Check Link Status

Verify whether a Discord account is linked to your agent with GET /v1/agent/:id/discord/status:

curl -X GET "https://api.app.shinzo.ai/v1/agent/AGENT_ID/discord/status" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response when linked:

{
  "linked": true,
  "discord_user_id": "123456789012345678",
  "discord_username": "your-username",
  "queue_mode": "collect",
  "created_at": "2026-02-18T10:35:00Z"
}

Response when not linked:

{
  "linked": false
}

Unlink Discord

Disconnect a Discord account from your agent with DELETE /v1/agent/:id/discord/unlink:

curl -X DELETE "https://api.app.shinzo.ai/v1/agent/AGENT_ID/discord/unlink" \
  -H "Authorization: Bearer YOUR_TOKEN"

This deactivates the channel binding. The agent stops receiving messages from Discord, and any messages sent to your bot are no longer forwarded to the agent.

Slack Integration

Slack is a fully supported external channel. You can connect your Shinzo agent to Slack by creating your own Slack app and providing the required credentials to Shinzo. Use cases:

Workspace assistant. Link your agent to Slack and interact with it throughout your workday without leaving your communication tool.
Team productivity. Access agent capabilities directly from your team’s Slack workspace.
Notification delivery. Configure webhooks to trigger agent messages that are delivered directly to your Slack DMs.
Rapid prototyping. Test agent behavior interactively through Slack during development without building a custom interface.
Cross-platform access. Use the same agent through both Discord and Slack depending on your context.

Creating Your Slack App

Before linking, you must create a Slack app and configure it in Shinzo. Slack requires three credentials for bot operation: Step 1: Create a Slack app

Visit api.slack.com/apps and click “Create New App”
Choose “From scratch” and give your app a name
Select the Slack workspace where you want to install the app

Step 2: Configure bot permissions

In your app settings, navigate to OAuth & Permissions
Under Bot Token Scopes, add the following scopes:
- chat:write - Send messages as the bot
- im:write - Send direct messages
- im:history - Read direct message history
- users:read - Access user profile information
Click “Install to Workspace” and authorize the app
Copy the Bot User OAuth Token (starts with xoxb-)

Step 3: Enable Socket Mode and get tokens

Navigate to Socket Mode in the left sidebar and toggle it on
When prompted, generate an app-level token with the connections:write scope
Copy the App-Level Token (starts with xapp-)
Navigate to Basic Information and copy your Signing Secret

Step 4: Enable the Messages Tab This step is required so users can send direct messages to your bot. Without it, Slack shows “Sending messages to this app has been turned off.”

Navigate to App Home in the left sidebar
Scroll down to the Show Tabs section
Enable “Allow users to send Slash commands and messages from the messages tab”

If you skip this step, users will see “Sending messages to this app has been turned off” when they try to DM the bot, and linking will not work.

Step 5: Enable Event Subscriptions

Navigate to Event Subscriptions in the left sidebar and toggle it on
Under Subscribe to bot events, add the following events:
- app_mention - To receive messages when your bot is @mentioned
- message.im - To receive direct messages sent to your bot
Click Save Changes

Required step! Your Slack bot will not receive messages without Event Subscriptions enabled. Make sure to add both app_mention and message.im events.

Step 6: Configure credentials in your agent Add all three credentials to your agent’s configuration:

curl -X PATCH "https://api.app.shinzo.ai/v1/agent/AGENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slack_bot_token": {
      "bot_token": "xoxb-YOUR-BOT-TOKEN",
      "signing_secret": "YOUR-SIGNING-SECRET",
      "app_token": "xapp-YOUR-APP-TOKEN"
    }
  }'

Alternatively, set this during agent creation with the slack_bot_token field in the POST /v1/agent request.

Keep all three credentials secret! Never commit them to version control or share them publicly.

Need help? See Slack’s official documentation on Creating Apps, Bot Tokens, and Socket Mode.

Linking Your Slack Account

After configuring your bot credentials, you can link your Slack user account to your agent: Step 1: Generate a link code Request a 6-character link code from the API with POST /v1/agent/:id/slack/link:

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/slack/link" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response includes the code and its expiration time:

{
  "code": "X7Y8Z9",
  "expires_at": "2026-02-25T10:50:00Z"
}

Link codes expire after 10 minutes. If the code expires before it is used, generate a new one.

Step 2: Link via Slack Send the following message as a direct message to your bot on Slack:

link X7Y8Z9

Do not use a leading / — type link X7Y8Z9 as a plain message, not /link X7Y8Z9. Slack intercepts messages that start with / as slash commands, which will fail with “not a valid command.”

The bot confirms the link and your agent is now connected to your Slack account. Step 3: Start chatting Send any message to your bot on Slack, and it will be routed to your linked agent. The agent’s response comes back as a Slack message.

What are link codes for? Link codes pair your Slack user identity with your Shinzo account so messages from you are properly attributed. The bot credentials setup and link code flow are two separate steps — the credentials activate the bot, and the link code associates your user account with it.

Check Link Status

Verify whether a Slack account is linked to your agent with GET /v1/agent/:id/slack/status:

curl -X GET "https://api.app.shinzo.ai/v1/agent/AGENT_ID/slack/status" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response when linked:

{
  "linked": true,
  "slack_user_id": "U01234ABCDE",
  "slack_team_id": "T01234ABCDE",
  "slack_username": "your-username",
  "linked_at": "2026-02-25T10:45:00Z"
}

Response when not linked:

{
  "linked": false
}

Unlink Slack

Disconnect a Slack account from your agent with DELETE /v1/agent/:id/slack/unlink:

curl -X DELETE "https://api.app.shinzo.ai/v1/agent/AGENT_ID/slack/unlink" \
  -H "Authorization: Bearer YOUR_TOKEN"

This deactivates the channel binding. The agent stops receiving messages from Slack, and any messages sent to your bot are no longer forwarded to the agent.

Telegram Integration

Telegram is a fully supported external channel. Linking your agent to Telegram allows users to interact with it directly through Telegram direct messages via your agent’s Telegram bot. Use cases:

Mobile-first access. Link your agent to Telegram and interact with it on-the-go from your mobile device.
Privacy-focused communication. Use Telegram’s encrypted messaging for secure agent interactions.
Global accessibility. Telegram works well even in regions with limited connectivity or restrictions on other platforms.
Bot-native workflows. Leverage Telegram’s bot ecosystem for rich integrations and inline interactions.
Multi-platform flexibility. Use the same agent through Discord, Slack, and Telegram depending on your preference.

Setting Up Your Agent’s Telegram Bot

Before linking, you must create a dedicated Telegram bot for your agent and configure it in Shinzo: Step 1: Create a Telegram bot via BotFather

Open Telegram and search for @BotFather (the official bot creation tool)
Send the command /newbot to BotFather
Follow the prompts to choose a name and username for your bot
BotFather will provide you with a bot token (e.g., 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw)

Keep your bot token secret! Anyone with this token can control your bot. Never commit it to version control or share it publicly.

Step 2: Configure the bot token in your agent Add the bot token to your agent’s configuration:

curl -X PATCH "https://api.app.shinzo.ai/v1/agent/AGENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "telegram_bot_token": "110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"
  }'

Alternatively, set this during agent creation with the telegram_bot_token field in the POST /v1/agent request. Step 3: Start a conversation with your bot

Search for your bot in Telegram using the username you created (e.g., @YourAgentBot)
Click Start or send any message to open the conversation
Your bot is now ready to be linked to your Telegram account

Need help? See Telegram’s official Bot API Documentation and BotFather Guide for detailed instructions on bot creation and management.

Link Code Workflow

Connecting an agent to Telegram follows the same simple three-step process as Discord and Slack: Step 1: Generate a link code Request a 6-character link code from the API with POST /v1/agent/:id/telegram/link:

curl -X POST "https://api.app.shinzo.ai/v1/agent/AGENT_ID/telegram/link" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response includes the code and its expiration time:

{
  "code": "P9Q8R7",
  "expires_at": "2026-03-09T19:00:00Z"
}

Link codes expire after 10 minutes. If the code expires before it is used, generate a new one.

Step 2: Link via Telegram Send the following command as a message to your agent’s Telegram bot:

/link P9Q8R7

The bot confirms the link and your agent is now connected to your Telegram account. Step 3: Start chatting Send any message to your agent’s Telegram bot, and it will be routed to your linked agent. The agent’s response comes back as a Telegram message.

Check Link Status

Verify whether a Telegram account is linked to your agent with GET /v1/agent/:id/telegram/status:

curl -X GET "https://api.app.shinzo.ai/v1/agent/AGENT_ID/telegram/status" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response when linked:

{
  "linked": true,
  "telegram_user_id": "123456789",
  "telegram_username": "your-username",
  "linked_at": "2026-03-09T18:55:00Z"
}

Response when not linked:

{
  "linked": false
}

Unlink Telegram

Disconnect a Telegram account from your agent with DELETE /v1/agent/:id/telegram/unlink:

curl -X DELETE "https://api.app.shinzo.ai/v1/agent/AGENT_ID/telegram/unlink" \
  -H "Authorization: Bearer YOUR_TOKEN"

This deactivates the channel binding. The agent stops receiving messages from Telegram, and any messages sent to your bot are no longer forwarded to the agent.

Best Practices

Use collect mode by default. Reserve interrupt for genuinely urgent messages that cannot wait for the current task to finish.
Attach metadata for traceability. Include request IDs, user identifiers, or other context in the metadata field to correlate messages with your application logic.
Paginate large histories. Use cursor-based pagination instead of fetching all messages at once to keep response times low.
Filter by channel when needed. If your agent handles messages from multiple channels, use the channel filter to retrieve conversations for a specific integration.
Monitor message status. Track pending messages to detect processing delays and ensure your agent is keeping up with demand.
Generate link codes close to when they will be used. Codes expire after 10 minutes, so avoid generating them far in advance.
Check link status before generating new codes. If an account is already linked, you do not need a new code.
Unlink before re-linking. If you need to change the linked account, unlink the current one first.

Shinzo Agents

Overview

Sending Messages

Request Parameters

Response Format

Listing Messages

Query Parameters

Response Format

Message States

Queue Modes

Collect Mode

Interrupt Mode

Channel Routing

Discord Integration

Setting Up the Shinzo Bot

Linking Your Discord Account

Check Link Status

Unlink Discord

Slack Integration

Creating Your Slack App

Linking Your Slack Account

Check Link Status

Unlink Slack

Telegram Integration

Setting Up Your Agent’s Telegram Bot

Link Code Workflow

Check Link Status

Unlink Telegram

Best Practices

Next Steps

Agent Configuration

Filesystem Management

Shinzo Agents

​Overview

​Sending Messages

​Request Parameters

​Response Format

​Listing Messages

​Query Parameters

​Response Format

​Cursor-Based Pagination

​Message States

​Queue Modes

​Collect Mode

​Interrupt Mode

​Channel Routing

​Discord Integration

​Setting Up the Shinzo Bot

​Linking Your Discord Account

​Check Link Status

​Unlink Discord

​Slack Integration

​Creating Your Slack App

​Linking Your Slack Account

​Check Link Status

​Unlink Slack

​Telegram Integration

​Setting Up Your Agent’s Telegram Bot

​Link Code Workflow

​Check Link Status

​Unlink Telegram

​Best Practices

​Next Steps

Agent Configuration

Filesystem Management

Overview

Sending Messages

Request Parameters

Response Format

Listing Messages

Query Parameters

Response Format

Cursor-Based Pagination

Message States

Queue Modes

Collect Mode

Interrupt Mode

Channel Routing

Discord Integration

Setting Up the Shinzo Bot

Linking Your Discord Account

Check Link Status

Unlink Discord

Slack Integration

Creating Your Slack App

Linking Your Slack Account

Check Link Status

Unlink Slack

Telegram Integration

Setting Up Your Agent’s Telegram Bot

Link Code Workflow

Check Link Status

Unlink Telegram

Best Practices

Next Steps