# Kanject.InstantMessaging

WebSocket-based chat with presence and typing indicators — one-to-one, group, and topic conversations. A serverless model: server-side managers own conversations and messages, and a WebSocket hub over API Gateway pushes them to connected clients, all in your own AWS account.

> **Note:** Developer guide. For the real-time feature tour, see the [InstantMessaging product page](https://www.kanject.com/baas/im/).

**You'll learn**

- Provision InstantMessaging into your AWS account
- Register the messaging services and attach the API Gateway WebSocket hub
- Create a conversation and persist a message through the managers
- Know the presence, typing, delivery-report, and conversation-type surface

## Provision

```bash
kanject baas deploy im --env dev
```

## Register it in your service

Register the messaging services with `AddServerlessInstantMessaging(...)`, then attach a real-time transport with `.UseApiGatewayWebsocketChatHub(...)`. The transport is an **API Gateway WebSocket** hub (an AppSync provider also exists); the WebSocket API is driven by string actions like `create_conversation` and `send_message`.

```csharp
using Kanject.InstantMessaging.Provider.AwsV2.Extensions;
using Kanject.InstantMessaging.ChatHub.Provider.ApiGateway.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register the messaging services, then attach the WebSocket transport.
builder.Services
    .AddServerlessInstantMessaging(new AwsInstantMessagingConfig { /* region, … */ })
    .UseApiGatewayWebsocketChatHub(/* API Gateway WebSocket options */);

var app = builder.Build();
app.Run();
```

## Create a conversation, send a message

There's no client object — you use the server-side managers. `IConversationManager<T>` creates conversations (`OneOnOne`, `GroupChat`, `TopicChat`); `IConversationChatManager<T>` persists messages; `IHubPublisher.PublishMessageAsync<T>` pushes them to connected participants:

```csharp
// Server-side managers create conversations and persist messages;
// IHubPublisher pushes them to connected clients over the WebSocket hub.
public class SupportChat(
    IConversationManager<Conversation> conversations,
    IConversationChatManager<Conversation> chats,
    IHubPublisher hub)
{
    public async Task<string?> StartAsync(string userA, string userB, Guid actingUserId)
    {
        var convo = await conversations.AddConversationAsync(new AddConversationRequest
        {
            ConversationType   = ConversationType.OneOnOne,
            ParticipantUserIds = new List<string> { userA, userB },
        }, actingUserId);

        await chats.AddConversationChatAsync(new AddConversationChatRequest
        {
            /* conversationId, body, MessageType.Text, … */
        }, actingUserId);

        return convo?.ConversationId;
    }
}
```

## What you get

- **Conversation types** — `OneOnOne`, `GroupChat`, `TopicChat`, one manager API.
- **Real-time over WebSocket** — API Gateway hub with `IHubPublisher` push (AppSync provider available).
- **Presence & typing** — `SetPresenceAction`, `TypingStart/Stop` over the hub; `SessionStatus` Online/Idle/Offline.
- **Delivery reports** — per-message delivery/read tracking (`IDeliveryReport`, `mark_read` / `set_cursor`).
- **Message history** — paginated backlog via `GetConversationChatsAsync` (`fetch_history`).
- **Message types** — `Text` and `Media`.

**Recap**

- Provision with `kanject baas deploy im`; register `AddServerlessInstantMessaging` + `.UseApiGatewayWebsocketChatHub`.
- Server-side managers (`IConversationManager<T>`, `IConversationChatManager<T>`) own conversations and messages.
- Real-time push is `IHubPublisher.PublishMessageAsync<T>` over an API Gateway WebSocket hub.
- Conversation types are `OneOnOne` / `GroupChat` / `TopicChat`; presence, typing, and delivery reports are built in.

## Related modules

- **[NotificationHub](https://www.kanject.com/docs/baas-notifications/)** — Push when a recipient is offline.
- **[Identity](https://www.kanject.com/docs/baas-identity/)** — User context for participants.
- **[Insights](https://www.kanject.com/docs/baas-insights/)** — Conversation and engagement metrics.

> **Next step:** Add offline push with [NotificationHub](https://www.kanject.com/docs/baas-notifications/), or read the [BaaS deployment guide](https://www.kanject.com/docs/baas/) for module composition.

---
_Source: https://www.kanject.com/docs/baas-im/ · Kanject Docs_