{"id":47953881,"url":"https://github.com/zernio-dev/chat-sdk-adapter","last_synced_at":"2026-04-05T10:00:43.683Z","repository":{"id":347825844,"uuid":"1195367476","full_name":"zernio-dev/chat-sdk-adapter","owner":"zernio-dev","description":"Official Zernio adapter for Chat SDK","archived":false,"fork":false,"pushed_at":"2026-03-30T13:46:29.000Z","size":184,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T09:38:59.315Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zernio-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T15:33:28.000Z","updated_at":"2026-03-30T13:46:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"bc387ff6-a268-4c68-a86d-1228b8cc6b80","html_url":"https://github.com/zernio-dev/chat-sdk-adapter","commit_stats":null,"previous_names":["zernio-dev/chat-sdk-adapter"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/zernio-dev/chat-sdk-adapter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zernio-dev%2Fchat-sdk-adapter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zernio-dev%2Fchat-sdk-adapter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zernio-dev%2Fchat-sdk-adapter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zernio-dev%2Fchat-sdk-adapter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zernio-dev","download_url":"https://codeload.github.com/zernio-dev/chat-sdk-adapter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zernio-dev%2Fchat-sdk-adapter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31431451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T08:13:15.228Z","status":"ssl_error","status_checked_at":"2026-04-05T08:13:11.839Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T09:23:35.309Z","updated_at":"2026-04-05T10:00:43.676Z","avatar_url":"https://github.com/zernio-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @zernio/chat-sdk-adapter\n\n[![npm](https://img.shields.io/npm/v/@zernio/chat-sdk-adapter)](https://www.npmjs.com/package/@zernio/chat-sdk-adapter) [![Listed on chat-sdk.dev](https://img.shields.io/badge/chat--sdk.dev-vendor%20official-black)](https://chat-sdk.dev/adapters/zernio) [![CI](https://github.com/zernio-dev/chat-sdk-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/zernio-dev/chat-sdk-adapter/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nOfficial [Zernio](https://zernio.com) adapter for [Chat SDK](https://chat-sdk.dev). Build chatbots that work across **Instagram, Facebook, Twitter/X, Telegram, WhatsApp, Bluesky, and Reddit** through a single integration.\n\nEven with native Chat SDK adapters for each platform, you'd still need to apply to Meta's developer program, go through App Review, get WhatsApp Business verification, apply for X elevated access, and more. With Zernio, your users connect accounts in a dashboard and you get one API key. No developer programs, no app reviews, no token management.\n\n## Installation\n\n```bash\nnpm install @zernio/chat-sdk-adapter chat\n```\n\n## Quick Start\n\n```typescript\nimport { Chat } from \"chat\";\nimport { createZernioAdapter } from \"@zernio/chat-sdk-adapter\";\n\nconst bot = new Chat({\n  adapters: {\n    zernio: createZernioAdapter(),\n  },\n  onNewMessage: async ({ thread, message }) =\u003e {\n    // This handler fires for messages from ALL connected platforms\n    const platform = message.raw.platform; // \"instagram\", \"telegram\", etc.\n    await thread.post(`Hello from ${platform}!`);\n  },\n});\n```\n\n### Next.js Webhook Route\n\n```typescript\n// app/api/chat-webhook/route.ts\nimport { bot } from \"@/lib/bot\";\n\nexport async function POST(request: Request) {\n  return bot.webhooks.zernio(request);\n}\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `ZERNIO_API_KEY` | Yes | Your Zernio API key for sending messages |\n| `ZERNIO_WEBHOOK_SECRET` | Recommended | HMAC-SHA256 secret for verifying inbound webhooks |\n| `ZERNIO_API_BASE_URL` | No | Override API base URL (default: `https://zernio.com/api`) |\n| `ZERNIO_BOT_NAME` | No | Bot display name (default: `\"Zernio Bot\"`) |\n\n### Explicit Configuration\n\n```typescript\nconst adapter = createZernioAdapter({\n  apiKey: \"your-api-key\",\n  webhookSecret: \"your-webhook-secret\",\n  baseUrl: \"https://zernio.com/api\",\n  botName: \"My Bot\",\n});\n```\n\n## Setup\n\n### 1. Get a Zernio API Key\n\nSign up at [zernio.com](https://zernio.com) and create an API key from the dashboard. Make sure the key has **read-write** permissions.\n\n### 2. Connect Social Accounts\n\nConnect the social accounts you want your bot to handle through the Zernio dashboard or API.\n\n### 3. Configure a Webhook\n\nCreate a webhook in your Zernio dashboard pointing to your bot's webhook endpoint:\n\n- **URL**: `https://your-app.com/api/chat-webhook`\n- **Events**: Select `message.received` and `comment.received`\n- **Secret**: Set a strong secret and pass it as `ZERNIO_WEBHOOK_SECRET`\n\n### 4. Enable the Inbox Addon\n\nThe inbox addon must be enabled on your Zernio account to receive message webhooks.\n\n## How It Works\n\n```\nIncoming message flow:\n  User sends DM on Instagram/Telegram/etc.\n    -\u003e Platform delivers to Zernio\n    -\u003e Zernio fires message.received webhook\n    -\u003e Adapter verifies signature \u0026 parses payload\n    -\u003e chat-sdk processes message through your handlers\n\nOutgoing message flow:\n  Your handler calls thread.post(\"Hello!\")\n    -\u003e Adapter calls Zernio REST API\n    -\u003e Zernio delivers to the correct platform\n    -\u003e User receives the message on Instagram/Telegram/etc.\n```\n\n## Thread ID Format\n\nThread IDs follow the format `zernio:{accountId}:{conversationId}`:\n\n- `accountId`: The Zernio social account ID (which platform account received the message)\n- `conversationId`: The Zernio conversation ID (the specific DM thread)\n- For comments: `zernio:{accountId}:comment:{postId}`\n\n```typescript\nimport { ZernioAdapter } from \"@zernio/chat-sdk-adapter\";\n\n// Decode a thread ID to get platform-specific details\nconst adapter = new ZernioAdapter({ apiKey: \"...\" });\nconst { accountId, conversationId } = adapter.decodeThreadId(threadId);\n```\n\n## Supported Features\n\n| Feature | Supported | Notes |\n|---------|-----------|-------|\n| Send messages | Yes | Text messages across all platforms |\n| Rich messages (cards) | Yes | Buttons and templates on FB, IG, Telegram, WhatsApp |\n| Edit messages | Partial | Telegram only |\n| Delete messages | Partial | Telegram, X (full delete); Bluesky, Reddit (self-only) |\n| Reactions | Partial | Telegram and WhatsApp (add/remove emoji) |\n| Typing indicators | Partial | Facebook Messenger and Telegram |\n| AI streaming | Partial | Post+edit on Telegram; single post on others |\n| File attachments | Yes | Via media upload endpoint |\n| Fetch messages | Yes | Full conversation history |\n| Fetch thread info | Yes | Participant details, platform, status |\n| Webhook verification | Yes | HMAC-SHA256 signature |\n| Comment webhooks | Yes | `comment.received` routed through handlers |\n\n### Platform Support Matrix\n\n| Feature | FB | IG | Telegram | WhatsApp | X | Bluesky | Reddit |\n|---------|----|----|----------|----------|---|---------|--------|\n| Send text | Y | Y | Y | Y | Y | Y | Y |\n| Buttons | Y | Y | Y | Y | - | - | - |\n| Typing | Y | - | Y | - | - | - | - |\n| Delete | - | - | Y | - | Y | Self | Self |\n| Reactions | - | - | Y | Y | - | - | - |\n| Media | Y | Y | Y | Y | Y | - | - |\n| Edit | - | - | Y | - | - | - | - |\n\n## Rich Messages\n\nThe adapter maps chat-sdk `Card` elements to native platform formats instead of rendering as fallback text:\n\n```typescript\nimport { Card, Button, Actions, Text } from \"chat\";\n\nawait thread.post(\n  Card({\n    title: \"Order #1234\",\n    subtitle: \"Total: $50.00\",\n    imageUrl: \"https://example.com/product.jpg\",\n    children: [\n      Text(\"Your order is ready for pickup.\"),\n      Actions([\n        Button({ id: \"confirm\", label: \"Confirm\", style: \"primary\" }),\n        LinkButton({ label: \"Track Order\", url: \"https://example.com/track\" }),\n      ]),\n    ],\n  })\n);\n// Renders as interactive card on FB/IG/Telegram/WhatsApp\n// Falls back to text on X/Bluesky/Reddit\n```\n\n## AI Streaming\n\nStream AI responses with the post+edit pattern (works best on Telegram):\n\n```typescript\nimport { generateText } from \"ai\";\nimport { openai } from \"@ai-sdk/openai\";\n\nonNewMessage: async ({ thread, message }) =\u003e {\n  const result = await generateText({\n    model: openai(\"gpt-4o\"),\n    prompt: message.text,\n  });\n\n  // On Telegram: posts initial message, edits as tokens arrive\n  // On other platforms: collects full response, posts once\n  await thread.stream(result.textStream);\n}\n```\n\n## Platform-Specific Data\n\nAccess the underlying platform through the raw message:\n\n```typescript\nonNewMessage: async ({ message }) =\u003e {\n  const raw = message.raw;\n\n  // Check which platform the message came from\n  console.log(raw.platform); // \"instagram\", \"facebook\", \"telegram\", etc.\n\n  // Access platform-specific sender info\n  if (raw.sender.instagramProfile) {\n    console.log(`Follower count: ${raw.sender.instagramProfile.followerCount}`);\n    console.log(`Is verified: ${raw.sender.instagramProfile.isVerified}`);\n  }\n\n  // WhatsApp phone number\n  if (raw.sender.phoneNumber) {\n    console.log(`Phone: ${raw.sender.phoneNumber}`);\n  }\n}\n```\n\n## API Client\n\nThe adapter exports a standalone API client for direct Zernio API calls:\n\n```typescript\nimport { ZernioApiClient } from \"@zernio/chat-sdk-adapter\";\n\nconst client = new ZernioApiClient(\"your-api-key\", \"https://zernio.com/api\");\n\n// List conversations\nconst { data, pagination } = await client.listConversations({\n  platform: \"instagram\",\n  status: \"active\",\n  limit: 20,\n});\n\n// Fetch messages\nconst messages = await client.fetchMessages(conversationId, accountId);\n\n// Send typing indicator\nawait client.sendTyping(conversationId, accountId);\n\n// Add reaction\nawait client.addReaction(conversationId, messageId, accountId, \"👍\");\n\n// Upload media\nconst { url } = await client.uploadMedia(fileBuffer, \"image/jpeg\");\n```\n\n## Webhook Verification\n\nThe adapter automatically verifies webhook signatures when `webhookSecret` is configured. You can also use the verification utility directly:\n\n```typescript\nimport { verifyWebhookSignature } from \"@zernio/chat-sdk-adapter\";\n\nconst isValid = verifyWebhookSignature(rawBody, signature, secret);\n```\n\n## Error Handling\n\nThe adapter maps Zernio API errors to standard chat-sdk error classes:\n\n| HTTP Status | Error Class | Description |\n|-------------|------------|-------------|\n| 401 | `AuthenticationError` | Invalid or expired API key |\n| 403 | `PermissionError` | Read-only key, missing addon, etc. |\n| 404 | `ResourceNotFoundError` | Conversation or message not found |\n| 429 | `AdapterRateLimitError` | Rate limit hit (includes `retryAfter`) |\n| 5xx | `NetworkError` | Server error |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzernio-dev%2Fchat-sdk-adapter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzernio-dev%2Fchat-sdk-adapter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzernio-dev%2Fchat-sdk-adapter/lists"}