Invocation Channels - xpander.ai

A deployed agent doesn’t care how a task arrives. The same @on_task handler runs whether the input came from a Slack message, a webhook, a cron trigger, or another agent. You enable channels per agent in Xpander Chat under the agent’s Channels tab.

REST API

The default channel. Every agent is reachable through xpander’s REST API as soon as it’s deployed:

curl -X POST "https://api.xpander.ai/v1/agents/{agent_id}/invoke" \
  -H "x-api-key: $XPANDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Summarize the attached file"}}'

Three invocation modes:

Mode	Endpoint	Best for
Sync	`/invoke`	Short tasks (under 30s) where the caller needs the answer immediately. Blocks until complete, returns the full result.
Async	`/invoke/async`	Long-running tasks or callers that can’t hold a connection open. Returns a task ID immediately; poll or stream events later.
Stream	`/invoke/stream`	Real-time UIs. Returns a Server-Sent Events stream of `TaskUpdateEvent`s as the agent runs.

Full endpoint reference: REST API → Agents.

Slack

Deploys your agent as a bot in your Slack workspace. Any DM or channel mention routes to your agent’s @on_task handler. The user who sends the message becomes the user_id on the task, so user memories work out of the box. Set up in Xpander Chat under the agent’s Channels tab. Each Slack workspace is one connected account; Xpander Chat walks through OAuth.

Channel progress preferences

Slack, Teams and Telegram use a status line by default. Channel bindings accept nullable verbose_task_progress (NULL inherits the bot preference); bot settings accept the same key. Explicit verbose opt-in wins over the legacy stream_task_progress: false setting. Clients should write the new preference and preserve existing legacy values. This affects channel presentation only; REST invocation SSE events remain unchanged.

Webhooks

Enable

In Xpander Chat, open the Channels tab and enable Webhook. The Webhook row shows your payload URL (with agent ID and API key embedded).

Make requests

All webhook requests are POST to https://webhook.xpander.ai/:

curl -X POST 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"prompt": "Summarize the latest support tickets"}'

Required parameters:

Parameter	Location
`agent_id`	Query string or body
`x-api-key`	Header or query string

Optional parameters:

Parameter	Type	Description
`prompt`	string	Text input for the agent.
`asynchronous`	boolean	Return immediately without waiting. Default: `false`.
`task_id`	string	Continue an existing conversation thread.
`user_id`	string	User identifier for tracking and memory scoping.
`user_email`	string	User email for personalization.
`user_first_name` / `user_last_name`	string	User name for personalization.
`getter`	string	Dot-notation path to extract from the response instead of returning the full payload.
`json`	boolean	Parse the result as JSON instead of returning a string.
`user_tokens`	string (JSON)	Pre-authenticated MCP OAuth tokens (see below).
`disable_attachment_injection`	boolean	When `true`, uploaded files are not injected into the LLM context window. File URLs are still available to the agent’s skills, but raw content is not prepended to the prompt. Useful when files are large or a skill handles processing directly.

Any additional fields in the request body are passed to the agent as context.

When the same parameter appears in multiple places, query parameters take priority over body parameters, which take priority over defaults.

Sync vs async

Synchronous (default): blocks until the agent finishes and returns the full result.

{
  "id": "task-uuid",
  "agent_id": "your-agent-id",
  "status": "completed",
  "result": "The agent's response...",
  "created_at": "2026-01-29T00:40:46.161472+00:00",
  "finished_at": "2026-01-29T00:40:47.919145+00:00",
  "source": "webhook",
  "execution_attempts": 1
}

Asynchronous: set asynchronous=true to return immediately. Best for long-running tasks, file processing, or when you don’t need the result inline.

curl -X POST 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID&asynchronous=true' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"prompt": "Generate the monthly report"}'

Returns {"status": "Started"} immediately. Check the task in Xpander Chat for the result.

Upload files

Upload files using multipart/form-data. The agent automatically processes them: OCR for images, text extraction for PDFs, transcription for audio.

curl -X POST 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID' \
  -H 'x-api-key: YOUR_API_KEY' \
  --form 'files=@"/path/to/document.pdf"' \
  --form 'files=@"/path/to/image.png"'

Supported formats: PDF, DOC, DOCX, TXT, XLS, XLSX, CSV, PNG, JPEG, GIF, WEBP, SVG, ZIP. Uploaded files are stored on xpander and exposed to your agent through presigned URLs scoped to your organization. URLs remain valid for 30 days after upload. For large batches (10+ files), use async mode and break uploads into batches of 5–10 files.

Extract data from responses

Use getter with dot notation to extract a specific field from the agent’s response instead of the full object:

curl -X POST 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID&getter=result.summary' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"prompt": "Analyze quarterly report"}'

Returns the extracted value directly: "Q4 revenue increased 15%". Behind a load balancer with an idle timeout, an AWS ALB answers 504 after 60 seconds by default, a synchronous call or a key-based webhook whose turn runs longer never returns. Use the asynchronous form and poll the task for turns that may take more than a minute.

Map dynamic parameters

Use params_mapping as a query parameter to extract values from nested payload fields and map them to webhook parameters. Useful for Telegram bots, WhatsApp, and other messaging platforms where identifiers are nested:

curl -g -X POST 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID&params_mapping={"task_id":"message.chat.id","prompt":"message.text","user_email":"message.from.email"}' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "message": {
      "chat": {"id": 123456789},
      "from": {"email": "user@example.com"},
      "text": "Hello agent!"
    }
  }'

Supports all standard parameters: task_id, user_id, user_email, user_first_name, user_last_name, prompt.

Pass MCP OAuth tokens

If your agent uses skills served over MCP with OAuth authentication, pass pre-authenticated user tokens via user_tokens to bypass the interactive OAuth flow during webhook execution:

curl -X POST 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "prompt": "Check my calendar",
    "user_email": "user@example.com",
    "user_tokens": {
      "mcp-graph-item-uuid-1": "user-access-token-abc123"
    }
  }'

To find the graph item IDs for your MCP skills, call the Get Agent API and inspect graph.items for entries with type: "mcp".

Error codes

Status	Response	Cause
400	`{"detail": "agent_id is required"}`	Missing `agent_id` parameter.
401	`{"detail": "API key not specified"}`	Missing `x-api-key` header or query param.
403	`{"detail": "Invalid API key"}`	Wrong API key or no access to this agent.

The x-api-key header is the only auth on the webhook endpoint by default. If you need request signing (HMAC for GitHub webhooks, signature verification for Stripe), validate it inside your handler before consuming the payload. xpander doesn’t validate third-party signatures for you.

MCP (Model Context Protocol)

Agents are reached over MCP through two endpoints, neither of which is configured per agent in Xpander Chat:

The API’s MCP endpoint, https://api.xpander.ai/mcp/, is the xpander API over MCP: the same control plane and data plane calls, listing and invoking agents, reading tasks and threads, reaching skills, custom functions, workspace files and schedules. It is not an agent. It signs in with OAuth 2.1; an API key is not accepted. Client setup is on Model Context Protocol.
The Omni endpoint, https://omni.xpander.ai/mcp, is Omni, the built-in agent, behind one address. Through it a client does everything you can do in Xpander Chat: find and task your organization’s agents, assemble skills and agents, start cloud sessions, ask what a run did. It signs in with OAuth in the browser. See Omni in your MCP client.

Skills served over MCP that your agents use are registered by an admin under Settings > MCP registry and added with Add skill; there is no per-agent MCP URL to configure.

Scheduled tasks (cron)

A cron expression that creates a task on a schedule. The task input is whatever you configure in Xpander Chat: a fixed prompt or a templated one with placeholders. The agent’s @on_task handler runs as if a user invoked it.

Agent-to-agent (A2A)

A2A lets other agents (inside or outside your organization) discover and invoke this agent via Google’s Agent2Agent protocol. This is how multi-agent teams compose: a manager agent delegates to specialist agents by calling them as skills.

Enable

In Xpander Chat, open the Channels tab, enable A2A, then:

Click Agent card to see the agent’s A2A identity: its Agent A2A URL, name, and version. This is what external agents use to discover and call it.
Click Manage API keys to generate credentials. External agents authenticate with these keys on every call. Generate one per external agent or team to keep access scoped and revocable.

Call an agent from code

From a parent agent’s handler, calling a child agent looks like calling any other skill. The child appears in agent.tools.list once it’s been added as a dependency in Xpander Chat:

from xpander_sdk import Agents

parent_agent = Agents().get(agent_id="agt_parent...")
result = await parent_agent.ainvoke_tool(
    tool=parent_agent.tools.get_tool_by_name("call_specialist_agent"),
    payload={"prompt": "Investigate this incident and return a summary"},
)
print(result.is_success, result.result)

What this means in practice:

The child agent runs its full loop. It has its own skills, instructions, memory, and knowledge bases. The parent only sees the final output as a skill result.
Each agent has its own A2A URL. External systems (agents on other platforms) can discover and call your agent at https://a2a.xpander.ai/ag_YOUR_AGENT_ID/ using the A2A protocol.
API keys are per external agent. Generate a separate key for each external caller so you can revoke access independently. The keys are scoped to the A2A channel; they can’t be used to invoke the agent through REST or webhooks.

Cross-platform delegation

The A2A protocol is designed for agents on different platforms to call each other. An agent built on LangChain, AutoGen, or any other A2A-compatible agent loop can invoke your xpander agent at its A2A URL using a standard A2A request, and vice versa.

Picking a channel

A common combination:

REST for programmatic access and backend integrations.
Slack for the team.
MCP for individual developers in their IDE or Claude Desktop.
Webhooks for inbound triggers from external systems (GitHub, Stripe, Zapier).
Cron for scheduled routine work.
A2A for delegation from a manager agent or cross-platform invocation.

All channels route through the same @on_task handler. There’s no per-channel cost in the SDK.

Things to watch for

Channels can collide in subtle ways. A scheduled task that fires every minute while a Slack user is mid-conversation creates two concurrent invocations against the same agent and sometimes the same session. If your handler isn’t idempotent, you’ll see weird interleavings in the conversation history. Either scope cron tasks to dedicated agents, or design handler logic that tolerates concurrent runs against the same session.

Next steps

REST API reference

Sync, async, and stream endpoints.

MCP guide

Full MCP setup walkthrough with screenshots.

Webhooks guide

Full webhook reference with the tester in Xpander Chat.

Scheduled tasks

Cron-driven invocations.

​REST API

​Slack

​Channel progress preferences

​Webhooks

​Enable

​Make requests

​Sync vs async

​Upload files

​Extract data from responses

​Map dynamic parameters

​Pass MCP OAuth tokens

​Error codes

​MCP (Model Context Protocol)

​Scheduled tasks (cron)

​Agent-to-agent (A2A)

​Enable

​Call an agent from code

​Cross-platform delegation

​Picking a channel

​Things to watch for

​Next steps

REST API reference

MCP guide

Webhooks guide

Scheduled tasks

REST API

Slack

Channel progress preferences

Webhooks

Enable

Make requests

Sync vs async

Upload files

Extract data from responses

Map dynamic parameters

Pass MCP OAuth tokens

Error codes

MCP (Model Context Protocol)

Scheduled tasks (cron)

Agent-to-agent (A2A)

Enable

Call an agent from code

Cross-platform delegation

Picking a channel

Things to watch for

Next steps