TypeScript SDK

Installation

npm install itellicoai

yarn add itellicoai

pnpm add itellicoai

Requirements

Node.js 18.10.0+
Full TypeScript support

Get Your API Key

To use the SDK, you will need an API key from your itellicoAI dashboard:

Navigate to API Keys

Go to Developers → API Keys

Create Key

Click Create API Key

Copy Key

Copy the generated key — it is only shown once

Store your API key securely using environment variables. Never commit it to version control.

Quick Start

import Itellicoai from 'itellicoai';

// Initialize client
const client = new Itellicoai({
  apiKey: 'your-api-key',
});

// Create an agent
const agent = await client.agents.create('your-account-id', {
  name: 'Customer Support Agent',
  model: {
    provider: 'openai',
    model: 'gpt-4o-mini',
  },
  voice: {
    provider: 'elevenlabs',
    voice_id: 'EXAVITQu4vr4xnSDxMaL',
  },
  transcriber: {
    provider: 'deepgram',
    model: 'nova-2:general',
    language: 'en-US',
  },
  initial_message: {
    mode: 'fixed_message',
    message: 'Hello! How can I assist you today?',
    delay_ms: 1000,
  },
  max_duration_seconds: 1800,
  tags: ['support', 'customer-service'],
});

console.log(`Created agent: ${agent.id}`);

SDK Operations

Agent Management

List Agents

const agents = await client.agents.list('account_id');

agents.items.forEach(agent => {
  console.log(`${agent.name} - ${agent.id}`);
});

Retrieve Agent

const agent = await client.agents.retrieve('agent_123abc', {
  account_id: 'account_id',
});

console.log(`Agent name: ${agent.name}`);
console.log(`Model: ${agent.model.model}`);

Update Agent

const updatedAgent = await client.agents.update('agent_123abc', {
  account_id: 'account_id',
  name: 'Updated Support Agent',
  note: 'Updated prompt notes for the support team',
});

Archive Agent

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'your-api-key',
});

await client.agents.archive('agent_id', { account_id: 'me' });

Conversations

List Conversations

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'your-api-key'
});

const conversations = await client.accounts.listConversations('account_id');

console.log(`Total conversations: ${conversations.count}`);

conversations.items.forEach((conv: any) => {
  console.log(`Conversation ID: ${conv.conversation_id}`);
  console.log(`Contact: ${conv.contact_number}`);
  console.log(`Duration: ${conv.duration_seconds}s`);
  console.log(`Status: ${conv.status}`);
  console.log(`Agent ID: ${conv.agent_id}`);
});

Phone Numbers

List Phone Numbers

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'your-api-key',
});

const phoneNumbers = await client.accounts.phoneNumbers.list('account_id');

console.log(phoneNumbers.count);

Create Phone Number

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'your-api-key',
});

const phoneNumber = await client.accounts.phoneNumbers.create('account_id', {
  sip_trunk_id: 'sip_trunk_id',
});

console.log(phoneNumber.id);

Get Phone Number

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'your-api-key',
});

const phoneNumber = await client.accounts.phoneNumbers.retrieve(
  'phone_number_id',
  { account_id: 'account_id' }
);

console.log(phoneNumber.id);

Update Phone Number

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'your-api-key',
});

const phoneNumber = await client.accounts.phoneNumbers.update(
  'phone_number_id',
  {
    account_id: 'account_id',
    name: 'Support line',
  }
);

console.log(phoneNumber.id);

Delete Phone Number

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'your-api-key',
});

await client.accounts.phoneNumbers.delete(
  'phone_number_id',
  { account_id: 'account_id' }
);

Providers

List Models

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'My API Key',
});

const response = await client.accounts.providers.listModels('account_id');

console.log(response);

List Transcribers

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'My API Key',
});

const response = await client.accounts.providers.listTranscribers('account_id');

console.log(response);

List Voices

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'My API Key',
});

const response = await client.accounts.providers.listVoices('account_id', { provider: 'elevenlabs' });

console.log(response);

SIP Trunks

List SIP Trunks

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'My API Key',
});

const sipTrunks = await client.accounts.sipTrunks.list('account_id');

console.log(sipTrunks.count);

Create SIP Trunk

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'My API Key',
});

const sipTrunk = await client.accounts.sipTrunks.create('account_id', {
  name: 'Main SIP trunk',
});

console.log(sipTrunk.id);

Get SIP Trunk

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'My API Key',
});

const sipTrunk = await client.accounts.sipTrunks.retrieve('sip_trunk_id', { account_id: 'account_id' });

console.log(sipTrunk.id);

Update SIP Trunk

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'My API Key',
});

const sipTrunk = await client.accounts.sipTrunks.update('sip_trunk_id', { account_id: 'account_id' });

console.log(sipTrunk.id);

Delete SIP Trunk

import Itellicoai from 'itellicoai';

const client = new Itellicoai({
  apiKey: 'My API Key',
});

await client.accounts.sipTrunks.delete('sip_trunk_id', { account_id: 'account_id' });

Analytics

Get Usage Analytics

const response = await client.accounts.analytics.getUsage('account_id');

console.log(response.meta);

Subaccounts

List Subaccounts

const subaccounts = await client.accounts.subaccounts.list('account_id');

console.log(subaccounts.count);

Create Subaccount

const account = await client.accounts.subaccounts.create('account_id', {
  name: 'name',
});

console.log(account.id);

Get Subaccount

const account = await client.accounts.subaccounts.retrieve(
  'subaccount_id',
  { account_id: 'account_id' }
);

console.log(account.id);

Update Subaccount

const account = await client.accounts.subaccounts.update(
  'subaccount_id',
  {
    account_id: 'account_id',
    name: 'Updated subaccount name',
  }
);

console.log(account.id);

Error Handling

import Itellicoai, {
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  APIError,
} from 'itellicoai';

const client = new Itellicoai({ apiKey: 'your-api-key' });

try {
  const agent = await client.agents.retrieve('agent_123abc', {
    account_id: 'account_id',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.error('Agent not found');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded');
  } else if (error instanceof APIError) {
    console.error(`API error: ${error.message}`);
  }
}

Environment Variables

import Itellicoai from 'itellicoai';

// API key automatically loaded from ITELLICOAI_API_KEY env var
const client = new Itellicoai();

// Or set explicitly
const client = new Itellicoai({
  apiKey: process.env.ITELLICOAI_API_KEY,
});

TypeScript Types

Full TypeScript definitions included:

import Itellicoai from 'itellicoai';

const createAgent = async (
  params: Itellicoai.AgentCreateParams
): Promise<Itellicoai.AgentResponse> => {
  const client = new Itellicoai();
  return await client.agents.create('account_id', params);
};

Resources

NPM Package

Install from NPM

GitHub Repository

View source code on GitHub

API Reference

Browse REST API documentation

Overview

Server SDKs

TypeScript SDK

Installation

Requirements

Get Your API Key

Quick Start

SDK Operations

List Agents

Retrieve Agent

Update Agent

Archive Agent

List Conversations

List Phone Numbers

Create Phone Number

Get Phone Number

Update Phone Number

Delete Phone Number

List Models

List Transcribers

List Voices

List SIP Trunks

Create SIP Trunk

Get SIP Trunk

Update SIP Trunk

Delete SIP Trunk

Get Usage Analytics

List Subaccounts

Create Subaccount

Get Subaccount

Update Subaccount

Error Handling

Environment Variables

TypeScript Types

Resources

NPM Package

GitHub Repository

API Reference

​Installation

​Requirements

​Get Your API Key

​Quick Start

​SDK Operations

​List Agents

​Retrieve Agent

​Update Agent

​Archive Agent

​List Conversations

​List Phone Numbers

​Create Phone Number

​Get Phone Number

​Update Phone Number

​Delete Phone Number

​List Models

​List Transcribers

​List Voices

​List SIP Trunks

​Create SIP Trunk

​Get SIP Trunk

​Update SIP Trunk

​Delete SIP Trunk

​Get Usage Analytics

​List Subaccounts

​Create Subaccount

​Get Subaccount

​Update Subaccount

​Error Handling

​Environment Variables

​TypeScript Types

​Resources

NPM Package

GitHub Repository

API Reference

Installation

Requirements

Get Your API Key

Quick Start

SDK Operations

List Agents

Retrieve Agent

Update Agent

Archive Agent

List Conversations

List Phone Numbers

Create Phone Number

Get Phone Number

Update Phone Number

Delete Phone Number

List Models

List Transcribers

List Voices

List SIP Trunks

Create SIP Trunk

Get SIP Trunk

Update SIP Trunk

Delete SIP Trunk

Get Usage Analytics

List Subaccounts

Create Subaccount

Get Subaccount

Update Subaccount

Error Handling

Environment Variables

TypeScript Types

Resources