---
name: unified-messaging
description: >-
  Build chat, bot, and notification features against many messaging platforms
  (Slack, Microsoft Teams, Discord, Telegram, and more) through the single
  Unified.to Messaging API. Use when a coding task involves sending or reading
  messages, listing channels, or building a support/notification bot across one
  or more chat platforms.
license: MIT
metadata:
  category: messaging
  api_base: https://api.unified.to
  docs: https://docs.unified.to/messaging/overview
---

# Build a chat / support bot with the Unified.to Messaging API

Unified.to normalizes many messaging platforms behind one REST API. Write your
bot or notification integration once and it works across every supported chat
platform. This skill teaches an agent how to build against the Unified Messaging
API.

## When to use this skill

Use this skill when the task is to:

- Send messages into channels (alerts, notifications, bot replies)
- Read messages and channels
- Build a support or Q&A bot that works across chat platforms
- Archive conversations

## Prerequisites

1. A Unified.to workspace with an **API key** and **Workspace ID**.
2. An activated messaging integration (e.g. Slack or Discord) — start in the
   Sandbox. Bot integrations often require a bot token/connection; see the
   platform's setup guide (e.g. Slack, Discord, Telegram).
3. A **connection ID** from the embedded Authorization component
   (https://docs.unified.to/concepts/embedded-components).

Keep the API key server-side only.

## Core request pattern

```
https://api.unified.to/messaging/{connection_id}/{object}
```

Authenticate every request:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Regional base URLs: `api.unified.to` (NA), `api-eu.unified.to` (EU),
`api-au.unified.to` (AU).

## Data objects

| Object    | Purpose                                  |
| --------- | ---------------------------------------- |
| `channel` | A channel / conversation / room          |
| `message` | A message within a channel               |

### Supported operations

| Method   | Path                              | Description        |
| -------- | --------------------------------- | ------------------ |
| `GET`    | `/messaging/{cid}/channel`        | List channels      |
| `GET`    | `/messaging/{cid}/channel/{id}`   | Get one channel    |
| `POST`   | `/messaging/{cid}/channel`        | Create a channel   |
| `PATCH`  | `/messaging/{cid}/channel/{id}`   | Update a channel   |
| `DELETE` | `/messaging/{cid}/channel/{id}`   | Delete a channel   |
| `GET`    | `/messaging/{cid}/message`        | List messages      |
| `GET`    | `/messaging/{cid}/message/{id}`   | Get one message    |
| `POST`   | `/messaging/{cid}/message`        | Send a message     |
| `PATCH`  | `/messaging/{cid}/message/{id}`   | Update a message   |
| `DELETE` | `/messaging/{cid}/message/{id}`   | Delete a message   |

Not every platform supports every object or field. Check the **Feature Support**
tab in `app.unified.to`; a `501` response means unsupported.

## Pagination & filtering

- `limit` (max 100) and `offset` (zero-based).
- Filter messages by `channel_id`, and use `updated_gte=YYYY-MM-DDTHH:MM:SSZ`
  for incremental reads.

## Example: list channels and send a message (fetch)

```javascript
const BASE = 'https://api.unified.to';
const headers = {
    Authorization: `Bearer ${process.env.UNIFIED_API_KEY}`,
    'Content-Type': 'application/json',
};

// Find a channel
const channels = await (
    await fetch(`${BASE}/messaging/${connectionId}/channel?limit=100`, { headers })
).json();
const support = channels.find((c) => c.name === 'support');

// Send a message into it
await fetch(`${BASE}/messaging/${connectionId}/message`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        channel_id: support.id,
        message: 'Thanks for reaching out — an agent will reply shortly.',
    }),
});
```

## Building a support bot

1. **Receive inbound messages** by registering a **webhook** for the `message`
   object so new messages reach you in real time (no polling). See
   https://docs.unified.to/reference/webhooks and
   https://docs.unified.to/concepts/virtual_webhooks.
2. Generate a reply (e.g. with an LLM over your knowledge base).
3. **Post the reply** with `POST /messaging/{cid}/message` into the same
   `channel_id`.

See the worked example: https://docs.unified.to/guides/how_to_build_a_discord_support_bot_with_unified_and_langbase.

## Example: with the official SDK

```bash
npm install @unified-api/typescript-sdk
```

```typescript
import { UnifiedTo } from '@unified-api/typescript-sdk';

const unified = new UnifiedTo({ security: { jwt: process.env.UNIFIED_API_KEY! } });

const { messagingChannels } = await unified.messaging.listMessagingChannels({
    connectionId,
    limit: 100,
});
```

SDKs for Python, PHP, Java, Go, C#, and Ruby: https://docs.unified.to/reference/sdks.

## Error handling

| Code | Meaning & action                                            |
| ---- | ----------------------------------------------------------- |
| 401  | Connection broken — re-authorize / re-add the bot.          |
| 403  | Missing scopes — fix provider app + Unified.to scopes.      |
| 429  | Provider rate limit — back off; prefer webhook sync.        |
| 501  | Operation unsupported by platform — check Feature Support.  |

## References

- Messaging API overview & data model: https://docs.unified.to/messaging/overview
- Webhooks & virtual webhooks: https://docs.unified.to/reference/webhooks
- REST basics: https://docs.unified.to/reference/rest
- Source guide: https://docs.unified.to/guides/how_to_build_a_discord_support_bot_with_unified_and_langbase