@vocantly/inbox-client

List EXTERNAL conversations and fetch message history without implementing your own backend route. Use the same API keys as Create EXTERNAL and Issue SDK Token.

Install

npm install @vocantly/inbox-client

Or from this repo (monorepo):

cd packages/vocantly-inbox-client
npm install

Usage

With API keys (dev / server-side)

Security: Do not expose your API secret in frontend code in production. Prefer the getHeaders pattern (your backend returns headers or proxies the request).

import { createInboxClient } from '@vocantly/inbox-client';

const client = createInboxClient({
  apiUrl: 'https://dev.vocantly.com/api/v1',
  apiKey: 'pk_xxxxx',
  apiSecret: 'sk_xxxxx',
});

// List conversations (inbox) for this user
const conversations = await client.listConversations('user_123');

// Fetch message history for a conversation
const { messages, pagination } = await client.getMessages(
  'conversation-uuid',
  'user_123',
  { limit: 20 }
);

// Next page (older messages)
if (pagination.has_next_page && pagination.next_cursor) {
  const next = await client.getMessages(
    'conversation-uuid',
    'user_123',
    { cursor: pagination.next_cursor, limit: 20 }
  );
}

With your backend (recommended in production)

Your backend calls Vocantly with API keys and returns the list/messages. The client only calls your backend:

const client = createInboxClient({
  apiUrl: 'https://your-api.com/api/vocantly', // your backend proxy
  getHeaders: async () => {
    const res = await fetch('/api/chat-credentials');
    const { apiKey, apiSecret } = await res.json();
    return {
      'X-Api-Key': apiKey,
      'X-Api-Secret': apiSecret,
      'Content-Type': 'application/json',
    };
  },
});

const conversations = await client.listConversations('user_123');

API

• createInboxClient(config)

  • config.apiUrl (string) – Base URL (e.g. https://dev.vocantly.com/api/v1).
  • config.apiKey + config.apiSecret (optional) – For direct API key auth.
  • config.getHeaders() (optional) – Async function returning headers (e.g. from your backend). Use instead of apiKey/apiSecret when you don’t want to ship the secret to the client.

• client.listConversations(externalUserId)
  Returns Promise<Conversation[]>.

• client.getMessages(conversationId, externalUserId, options?)
  Options: { cursor?: string, limit?: number } (default limit 20, max 100).
  Returns Promise<{ messages, pagination: { has_next_page, next_cursor, limit } }>.

Backend endpoints

• GET /api/v1/conversations/external?external_user_id=...
• GET /api/v1/conversations/external/:conversationId/messages?external_user_id=...&cursor=...&limit=...

See List EXTERNAL and Get EXTERNAL messages in the docs.