@rootel/sdk

Node.js SDK for Rootel Headless partner APIs. Partners use this package from their backend to create isolated customers, generate Rootel agents, attach knowledge, enable tools, create channel connectors, send chat messages, and read conversation intelligence or usage data.

Install

npm install @rootel/sdk

Requirements

• Node.js 18 or newer.
• A Rootel partner API token from Partner Portal -> API & Docs -> API Keys.
• Use this SDK from a backend service. Do not expose partner API tokens in browser code, mobile apps, or customer-facing widgets.

This package has no runtime npm dependencies. It uses the platform fetch and crypto APIs available in modern Node.js.

Quick Start

const { RootelHeadless } = require('@rootel/sdk');

const rootel = new RootelHeadless({
  apiKey: process.env.ROOTEL_API_KEY,
  baseUrl: process.env.ROOTEL_BASE_URL || 'https://rootel-staging.eastus.cloudapp.azure.com/api',
});

async function main() {
  const customer = await rootel.customers.create({
    externalTenantId: 'customer-123',
    name: 'Acme Retail',
    environment: 'sandbox',
  });

  const agent = await rootel.agents.create({
    externalTenantId: 'customer-123',
    name: 'Acme Support Agent',
    prompt: 'Create a helpful support and sales agent for Acme Retail.',
    supportedLanguages: ['en'],
  });

  await rootel.knowledge.addUrl(agent.id, {
    externalTenantId: 'customer-123',
    url: 'https://example.com/help',
  });

  const connector = await rootel.connectors.createExistingBot({
    externalTenantId: 'customer-123',
    agentId: agent.id,
    channel: 'whatsapp',
    name: 'Acme WhatsApp connector',
  });

  console.log({ customer, agent, connector });
}

main().catch(console.error);

Direct Chat Example

const reply = await rootel.chat.send({
  externalTenantId: 'customer-123',
  agentId: 'agent-id-from-create-response',
  customerId: 'end-user-phone-or-stable-id',
  customerName: 'Customer Name',
  channel: 'whatsapp',
  message: 'Hi, can you help me choose a product?',
});

Use a stable customerId for the same end user across web and WhatsApp if you want Rootel memory to follow that user across channels.

Existing Bot / BSP Connector Example

const connector = await rootel.connectors.createExistingBot({
  externalTenantId: 'customer-123',
  agentId: 'agent-id',
  channel: 'whatsapp',
  name: 'Partner inbox connector',
});

const response = await rootel.connectors.forwardMessage(
  connector.endpoint,
  connector.channelConnectorToken,
  {
    customerId: '919999999999',
    message: 'Where is my order?',
    messageId: 'partner-message-id-1',
  }
);

Store channel connector tokens in your backend only. Forward customer messages to Rootel, then send the Rootel response back through your existing BSP, inbox, website, or channel system.

Webhook Example

Use partner webhooks for outbound Rootel events such as agent changes, customer lifecycle changes, connector changes, knowledge ingestion results, opportunities, risks, and delivery failures.

const created = await rootel.webhooks.create({
  url: 'https://partner.example.com/rootel/events',
  description: 'Partner event receiver',
  events: [
    'agent.created',
    'agent.updated',
    'agent.promoted',
    'connector.created',
    'integration.connected',
    'knowledge.ingestion_completed',
    'knowledge.ingestion_failed',
    'tenant.created',
    'tenant.suspended',
    'tenant.resumed',
    'tenant.deleted',
    'opportunity.detected',
    'risk.detected',
    'webhook.delivery_failed'
  ]
});

const availableEvents = await rootel.webhooks.events();
const deliveries = await rootel.webhooks.deliveries();

Rootel shows the webhook signing secret only once when you create or rotate a webhook secret. Store that secret in your backend and verify the x-rootel-signature and x-rootel-timestamp headers on every delivery.

API Groups

• customers: create, list, debug, suspend, resume isolated customer workspaces.
• agents: create agents, read/update generated Rootel configuration, activate/pause/resume, attach specialist agents.
• knowledge: add URLs, upload documents, replace documents, delete documents, check ingestion status.
• tools: list built-in capabilities, assign agent capabilities, create customer OAuth connect links, manage integrations.
• customTools: register partner-hosted HTTPS tools, assign them to customers, execute/request tools, submit async results and read execution logs.
• connectors: create existing-bot connectors, list/revoke connectors, forward messages through connector endpoints.
• chat: send direct messages, human takeover/resume, append human messages.
• intelligence: read conversation intelligence, traces, analytics, opportunities and risks.
• billing: read usage and export billing data.
• webhooks: list supported events, create/update/delete destinations, rotate secrets, replay/test deliveries, and retry failed deliveries.

Custom Tools Example

Custom tools are partner-hosted HTTPS endpoints that Rootel agents can call when the partner wants to use their own systems, such as order lookup, ticket creation, wallet balance, lead routing or custom CRM actions.

await rootel.customTools.register({
  name: 'check_order_status',
  description: 'Checks order status from the partner order management system.',
  inputSchema: {
    type: 'object',
    properties: {
      orderId: { type: 'string' }
    },
    required: ['orderId']
  },
  outputSchema: {
    type: 'object',
    properties: {
      status: { type: 'string' },
      eta: { type: 'string' },
      trackingUrl: { type: 'string' }
    }
  },
  metadata: {
    endpoint: 'https://api.partner.com/rootel/tools/order-status',
    authType: 'bearer'
  }
});

await rootel.customTools.assign('check_order_status', {
  externalTenantIds: ['customer-123']
});

const result = await rootel.customTools.execute('check_order_status', {
  externalTenantId: 'customer-123',
  agentId: 'agent-id',
  conversationId: 'conversation-id',
  arguments: { orderId: 'ORD-1001' }
});

Use rootel.tools for Rootel built-in integrations such as Shopify or Google Sheets. Use rootel.customTools for partner-owned HTTPS capabilities.

Error Handling

API errors throw RootelApiError with status and body fields.

const { RootelApiError } = require('@rootel/sdk');

try {
  await rootel.customers.list();
} catch (error) {
  if (error instanceof RootelApiError) {
    console.error(error.status, error.body);
  } else {
    console.error(error);
  }
}

Security

• Keep ROOTEL_API_KEY on the server.
• ROOTEL_BASE_URL should include the API prefix, for example https://api.rootel.app/api or https://rootel-staging.eastus.cloudapp.azure.com/api.
• Never send partner API tokens to browser widgets, mobile apps, or customer websites.
• Use channel connector tokens only in partner-controlled channel backends.
• Rotate API keys from the Partner Portal if a key is exposed.
• Store webhook signing secrets in backend secret storage and verify delivery signatures.
• Use stable customer and end-user identifiers, but avoid sending unnecessary PII in metadata.

Package Contents

The npm package intentionally ships compiled runtime files and TypeScript definitions only:

• dist/index.js
• dist/index.d.ts
• dist/index.d.ts.map
• README.md
• package.json