Full Support Flow

​

Who Is Who

​

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────────┐
│  EXTERNAL APP (e.g. Homebridge)                                                  │
│  • Owns: end users, auth, product logic                                          │
│  • Backend: creates support conversations, issues SDK tokens (Vocantly API)    │
│  • Frontend: embeds Vocantly SDK; user gets token + conversation_id            │
└─────────────────────────────────────────────────────────────────────────────────┘
         │ REST (create support conv, issue token)    │ WebSocket (chat)
         ▼                                            ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│  VOCANTLY                                                                      │
│  • NestJS: auth, apps, conversations, support inbox, persistence                 │
│  • Go Realtime: WebSocket, rooms, presence, typing; persists via Node            │
│  • Dashboard: agents see support inbox, reply in MessageThread                   │
│  • SDK: headless; used by Homebridge frontend for end-user chat                  │
└─────────────────────────────────────────────────────────────────────────────────┘

​

Phase 1: Company Sign Up on Vocantly

1. Register — POST /api/v1/auth/register with email, password, first_name, last_name, company_name, company_slug, etc. Creates one User (owner) and one Tenant; the user is linked as OWNER.
2. Verify email (if enabled) — POST /api/v1/auth/verify-email with OTP or token.
3. Login — POST /api/v1/auth/login with email, password. Response: access_token (JWT), refresh_token. Use Authorization: Bearer <access_token> for all dashboard API calls.

​

Phase 2: App and Support Setup

​

Create an app

• Endpoint: POST /api/v1/apps
• Body: name, environment ("prod" | "dev")
• Response: id (App ID), public_key (pk_…), secret_key (sk_…). Store all three on your backend; the secret is only returned once.

​

Create departments (optional)

• Endpoint: POST /api/v1/departments
• Used for routing support conversations to the right team.

​

Invite team members

• Endpoint: POST /api/v1/tenants/me/invitations with email, role (admin | member | agent).
• An invitation is created (valid 7 days) and an email is sent with an accept link.
• See Team members & Invitations for the full invite flow.

​

Add agents

• After users have joined the tenant (via invite-accept or as owner), promote them: POST /api/v1/agents with user_id, optional department_ids, max_active_chats.
• See Team members overview for roles and Support routing for assignment.

​

Phase 3: External App (e.g. Homebridge) Integration

• Backend: Talks to Vocantly with API key (and optionally JWT for conversation create).
• Frontend: Gets token and conversation_id from their backend and uses the Vocantly JS SDK.

​

Phase 4: End User Asks for Support

​

Homebridge backend: create support conversation

• Endpoint: POST /api/v1/conversations
• Auth: Authorization: Bearer <JWT> (dashboard service account).
• Body (support with customer linking):

{
  "type": "support",
  "title": "Support Request",
  "customer_external_id": "user_123",
  "customer_name": "Jane Doe",
  "customer_email": "jane@example.com",
  "customer_phone": "+1234567890"
}

• Important: customer_external_id must match the ID used when issuing the SDK token for this user.
• Response: Conversation object including id (conversation_id).

​

Homebridge backend: issue SDK token

• Endpoint: POST /api/v1/apps/:appId/tokens
• Auth: JWT or API key (X-Api-Key, X-Api-Secret).
• Body: { "external_user_id": "user_123", "name": "Jane Doe", "email": "jane@example.com" }
• Response: token, expires_in, user_id.

​

Homebridge backend: respond to frontend

​

Homebridge frontend: open chat with SDK

import { Vocantly } from '@vocantly/sdk';

const sdk = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  token,
  debug: true,
});

await sdk.connect();
await sdk.conversations.join(conversationId);

const convo = sdk.conversations.get(conversationId);
convo.on('message', (msg) => { /* show in UI */ });
convo.sendMessage('Hi, I need help with my payment schedule.');

​

Phase 5: Agent Handles the Conversation

• Agent logs in to the Vocantly dashboard with POST /api/v1/auth/login.
• Support inbox: GET /api/v1/support/inbox — list of support conversations (queued, assigned, active, closed).
• Assign / accept: GET /api/v1/support/queue, POST /api/v1/support/:conversationId/assign, POST /api/v1/support/:conversationId/accept.
• Chat: Agent opens the conversation in the dashboard; messages flow over the same WebSocket; end user sees replies in the app via the SDK.
• Close / transfer: POST /api/v1/support/:conversationId/close, POST /api/v1/support/:conversationId/reopen, POST /api/v1/support/:conversationId/transfer (owner/admin only).

​

Phase 6: Message and Realtime Flow

1. End user sends a message → SDK → Go realtime → room → delivered to agent.
2. Go calls NestJS to persist: POST /api/v1/internal/messages.
3. Agent reply from dashboard → same WebSocket path → end user’s SDK receives via convo.on('message').
4. Delivery/read receipts: Go persists via POST /api/v1/internal/receipts; UI can use GET /api/v1/conversations/:conversationId/receipts.

​

API Quick Reference

​

Limitations and Notes

• Invite flow: OWNER/ADMIN invite by email; invitee accepts via link (log in and accept, or create account with token + password + name). Then they can be promoted to agent.
• Support conversation create: Currently JWT-only. For full customer linking, the creating context may need app_id (future: API-key-based create-support endpoint).
• Idempotency: For “one open support conversation per user,” implement your own logic (e.g. store conversation_id per user and reuse until closed).
• Dashboard: The Vocantly dashboard is the agent UI. External apps only embed the SDK for the end user chat.

​

Summary: Homebridge Integration Checklist

1. Vocantly: Sign up → create app → create departments (optional) → invite team members → invitees accept via email link → promote users to agents.
2. Homebridge backend: Store App ID + keys; create support conversation (JWT); issue token; expose endpoint that returns { token, conversation_id }.
3. Homebridge frontend: Use SDK; on “Contact support,” get token + conversation_id from backend, then connect() → join(conversationId) → sendMessage / on('message').
4. Agents: Use Vocantly dashboard to open support inbox, assign/accept, reply, and close conversations.