> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Unified Messaging API

> Unified Messaging API for communication workflows across platforms, with consistent data models for conversations, message delivery, and participant management.

export const category_0 = "messaging"

## What is a Unified API?

A **unified API** provides a single, standardized interface to interact with multiple third-party providers. Instead of learning each provider's unique API format, authentication scheme, and data model, you write code once, and StackOne handles the differences.

**What StackOne normalizes:**

* **Data models** – Consistent field names and structures across providers (e.g., `files` in Google Drive, SharePoint, and Dropbox all return the same schema; `users` in Google Workspace, Okta, and 1Password all return the same schema)
* **Authentication** – OAuth, API keys, and tokens are managed per-provider; you just pass an `x-account-id` header
* **Pagination** – Cursor-based pagination works the same regardless of whether the provider uses offsets, pages, or cursors
* **Error formats** – Standardized error responses with provider-specific details when available

<Tip>
  **Building AI agents?** Use the [MCP Server](/mcp/quickstart), an [AI Toolset SDK](/agents/typescript/introduction), or the [Actions API (RPC)](/platform/api-reference/actions/make-an-rpc-call-to-an-action) instead — same data, optimized for LLM tool calling.
</Tip>

## Benefits of the Messaging API

<AccordionGroup>
  <Accordion title="Real-Time Data Synchronization">
    StackOne's APIs support real-time data polling, allowing for immediate updates and synchronization across platforms.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne's architecture avoids unnecessary data storage, maintaining compliance with data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    Both [synthetic and native webhooks](/guides/webhooks), enable real-time notifications for tickets and comment events.
  </Accordion>

  <Accordion title="Comprehensive Integration Coverage">
    StackOne offers [pre-built connectors](https://www.stackone.com/integrations) with a wide range of {category_0} platforms, simplifying the integration process.
  </Accordion>
</AccordionGroup>

## Key Features

| **Feature**             | **Description**                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| Conversation Management | Easily create and manage conversations across multiple messaging platforms with unified fields |
| Real-Time Message Sync  | Keep messages, threads, and statuses synchronized across all integrated systems                |
| Real-Time Webhooks      | Receive instant notifications for new messages, edits, and conversation updates                |
| Participant Management  | Manage participants, roles, and permissions within conversations                               |
| Attachments Support     | Send and receive files, images, and documents within messages                                  |

## StackOne SDKs & OpenAPI Specification

<p class="sdk-text">Use our official SDKs for faster integration. Build with language-native libraries. Full list [here](/guides/stackone-api-sdks).</p>

<CardGroup cols={2}>
  <Card title="OpenAPI Specification" icon="link" href="https://api.eu1.stackone.com/oas/messaging.json" arrow="true" cta="Click here" />

  <Card title="Popular SDKs" icon="download" class="sdk-card">
    [Node.js](https://www.npmjs.com/package/@stackone/stackone-client-ts)
    [Java (JVM)](https://mvnrepository.com/artifact/com.stackone/stackone-client-java)
    [PHP](https://packagist.org/packages/stackone/client-sdk)
    [Ruby](https://rubygems.org/gems/stackone_client)
  </Card>
</CardGroup>

## Entity Model and Relationships

The following diagram illustrates the key entities within the Messaging API:

```mermaid theme={null}
%%{init: {
    "er": {
        "layoutDirection": "LR",
        "nodeSpacing":   60,
        "rankSpacing":  120
    },
    "useMaxWidth": false
}}%%
erDiagram
    CONVERSATION {
        string id
        string[] participants
        string name
        datetime created_at
        datetime last_message_at
    }
    MESSAGE {
        string id
        object content
        string parent_message_id
        object[] attachments
        object author
        datetime created_at
        datetime updated_at
    }
    USER {
        string id
        string email
        string username
        string name
        string first_name
        string last_name
        boolean bot
        boolean active
    }
    ATTACHMENT {
        string id
        string file_name
        string file_size
        string file_type
    }

    CONVERSATION ||--o{ MESSAGE : ""
    CONVERSATION ||--o{ USER : ""
    MESSAGE ||--o{ ATTACHMENT : ""
    USER ||--o{ MESSAGE : ""
```

## Entity Definitions

| Entity       | Description                                                                           |
| ------------ | ------------------------------------------------------------------------------------- |
| Conversation | A thread or group chat where participants exchange messages.                          |
| Message      | Individual communication sent within a conversation, can include text or attachments. |
| Participant  | A user or entity involved in a conversation, with roles and permissions.              |
| Attachments  | Files and documents associated with messages.                                         |