@chatafrika/sdk

Headless JavaScript SDK for ChatAfrika chat, presence, typing, and support features.

Installation

npm install @chatafrika/sdk

Quick Start

Your backend issues SDK tokens via POST /api/v1/apps/:appId/tokens (JWT or API key). Your frontend receives only the token—never App ID, public key, or secret key. See the ChatAfrika API docs for Issue SDK Token (POST /apps/:id/tokens).

import { ChatAfrika } from '@chatafrika/sdk';

// token from your backend—never use keys in the frontend
const sdk = new ChatAfrika({
  wsUrl: 'wss://ws.dev.chaterafrika.com/ws',
  token,
  debug: true,
});

await sdk.connect();

const convo = sdk.conversations.get('conv-123');
await sdk.conversations.join('conv-123');

convo.on('message', (msg) => {
  console.log('Message:', msg.content);
});

convo.sendMessage('Hello!');

Features

• ✅ WebSocket transport with auto-reconnection
• ✅ Optimistic message updates
• ✅ Message deduplication & reconciliation
• ✅ Typing indicators with auto-expiry
• ✅ Presence tracking
• ✅ Read receipts lifecycle
• ✅ Support session semantics (customer/agent roles)
• ✅ Event-driven architecture
• ✅ TypeScript support

Development

npm install
npm run build
npm run typecheck
npm run test:quick  # Quick test against real server

Testing

See TESTING.md for detailed testing guide.

Quick test (use a token from your backend, e.g. POST /apps/:id/tokens):

WS_URL=ws://localhost:8080/ws SDK_TOKEN=<token-from-backend> npm run test:quick

API Documentation

Core

• ChatAfrika - Main SDK class
• ConnectionState - Connection state enum
• ClientConfig - Configuration interface

Conversations

• sdk.conversations.get(id) - Get conversation
• sdk.conversations.join(id) - Join conversation
• sdk.conversations.leave(id) - Leave conversation
• sdk.conversations.list({ externalUserId }) - List EXTERNAL conversations (inbox). Requires apiUrl and apiKey+apiSecret or getRestHeaders in config.
• convo.fetchMessages({ externalUserId, cursor?, limit? }) - Fetch paginated message history for an EXTERNAL conversation. Same config as list().

Support Sessions

• sdk.support.get(id, role?) - Get support session
• session.isCustomer() - Check if customer
• session.isAgent() - Check if agent
• session.getStatus() - Get session status

Events

All classes extend EventEmitter. Listen to:

• message - New message received
• typing - Typing indicator
• presence - Presence update
• receipt - Receipt update
• assigned - Support session assigned
• bot_takeover - Bot took over
• closed - Support session closed

Publish for testing

Base URL for dev: https://dev.chaterafrika.com/ (API: https://dev.chaterafrika.com/api/v1, WebSocket: wss://ws.dev.chaterafrika.com/ws).

See PUBLISH_FOR_TESTING.md for:

• Publishing to npm with --tag beta (npm install @chatafrika/sdk@beta)
• Installing from Git or local path (no publish)
• Using npm link for local development
• Dev vs local URLs

Documentation

• Capabilities & Usage Guide - What the SDK can do and where to use it
• Testing Guide - How to test the SDK
• Publish for testing - Publish / install SDK for testing with dev

License

UNLICENSED