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 and Discord channels. Messages are automatically routed back through the channel they originated from.

Discord is the only external channel integration currently supported. Support for additional channels including Slack, Telegram, and WhatsApp 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` or `discord`
`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` or `discord`

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
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 the first fully supported external channel. Linking your agent to Discord allows users to interact with it directly through Discord direct messages via the Shinzo bot.

Link Code Workflow

Connecting an agent to Discord follows a simple three-step process: 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 the Shinzo 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 the Shinzo bot on Discord, and it will be routed to your linked agent. The agent’s response comes back as a Discord message.

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 the Shinzo bot are no longer forwarded to the agent.

Listing Channel Bindings

View all active channel bindings for an agent with GET /v1/agent/:id/channels:

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

This returns all connected channels, including API (always present) and any linked external channels:

{
  "bindings": [
    {
      "channel": "api",
      "status": "active",
      "created_at": "2026-02-18T09:00:00Z"
    },
    {
      "channel": "discord",
      "status": "active",
      "discord_user_id": "123456789012345678",
      "discord_username": "your-username",
      "created_at": "2026-02-18T10:35:00Z"
    }
  ]
}

Use Cases for Discord Integration

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 type 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.

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 a Discord account is already linked, you do not need a new code.
Unlink before re-linking. If you need to change the linked Discord 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

Link Code Workflow

Check Link Status

Unlink Discord

Listing Channel Bindings

Use Cases for Discord Integration

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

​Link Code Workflow

​Check Link Status

​Unlink Discord

​Listing Channel Bindings

​Use Cases for Discord Integration

​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

Link Code Workflow

Check Link Status

Unlink Discord

Listing Channel Bindings

Use Cases for Discord Integration

Best Practices

Next Steps