itellicoAI Documentation

Installation

npm install itellicoai

Requirements

Node.js 18.10.0+
Full TypeScript support

Get Your API Key

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

Navigate to Developers from the sidebar
Click on API Keys
Click Create API Key
Copy the generated key to use with the SDK

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({
  accountId: 'your-account-id',
  name: 'Customer Support Agent',
  model: {
    provider: 'openai',
    model: 'gpt-4o-mini',
  },
  voice: {
    provider: 'elevenlabs',
    voiceId: 'EXAVITQu4vr4xnSDxMaL',
  },
  transcriber: {
    provider: 'deepgram',
    model: 'nova-2:general',
    language: 'en-US',
  },
  initialMessage: {
    mode: 'fixed_message',
    message: 'Hello! How can I assist you today?',
    delayMs: 1000,
  },
  maxDurationSeconds: 1800,
  tags: ['support', 'customer-service'],
});

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

SDK Operations

Agent Management

List Agents

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

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

Retrieve Agent

const agent = await client.agents.retrieve('agent_123abc');

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

Update Agent

const updatedAgent = await client.agents.update('agent_123abc', {
  name: 'Updated Support Agent',
  instructions: 'You are a helpful customer support agent...',
});

Archive Agent

import { Itellicoai } from 'itellicoai';


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', {
  limit: 10
});

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', {
  sipTrunkId: '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(
  'account_id',
  'phone_number_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(
  'account_id',
  'phone_number_id'
);

console.log(phoneNumber.id);

Delete Phone Number

import { Itellicoai } from 'itellicoai';

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

await client.accounts.phoneNumbers.delete(
  'account_id',
  'phone_number_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: 'provider' });

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');

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(
  'account_id',
  'subaccount_id'
);

console.log(account.id);

Update Subaccount

const account = await client.accounts.subaccounts.update(
  'account_id',
  'subaccount_id'
);

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');
} 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 ITELLICO_API_KEY env var
const client = new ItellicoAI();

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

TypeScript Types

Full TypeScript definitions included:

import type {
  Agent,
  AgentCreateParams,
  AgentUpdateParams,
  Conversation,
  PhoneNumber,
} from 'itellicoai';

const createAgent = async (
  params: AgentCreateParams
): Promise<Agent> => {
  const client = new ItellicoAI();
  return await client.agents.create(params);
};

Resources

NPM Package

Install from NPM

GitHub Repository

View source code on GitHub

API Reference

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

Overview

Server SDKs

​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