Skip to main content

​
Installation

pip install itellicoai

​
Requirements

  • Python 3.8+
  • Supports both sync and async operations

​
Get Your API Key

To use the SDK, you’ll need an API key from your itellicoAI dashboard:
  1. Navigate to Developers from the sidebar
  2. Click on API Keys
  3. Click Create API Key
  4. Copy the generated key to use with the SDK
API Keys dashboard
API Keys dashboard
Store your API key securely using environment variables. Never commit it to version control.

​
Quick Start

from itellicoai import Itellicoai

# Initialize client
client = Itellicoai(
    api_key="your-api-key"
)

# Create an agent
agent = client.agents.create(
    account_id="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"]
)

print(f"Created agent: {agent.id}")

​
Async Support

import asyncio
from itellicoai import AsyncItellicoAI

async def main():
    client = AsyncItellicoAI(api_key="your-api-key")

    # List agents asynchronously
    agents = await client.agents.list()

    for agent in agents:
        print(f"Agent: {agent.name}")

asyncio.run(main())

​
SDK Operations

Agent Management

​
List Agents

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
agents = client.agents.list(
    account_id="account_id",
)
print(agents.count)

​
Retrieve Agent

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
agent_response = client.agents.retrieve(
    agent_id="agent_id",
    account_id="account_id",
)
print(agent_response.id)

​
Update Agent

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
agent_response = client.agents.update(
    agent_id="agent_id",
    account_id="account_id",
)
print(agent_response.id)

​
Archive Agent

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
client.agents.archive(
    agent_id="agent_id",
    account_id="account_id",
)

​
List Conversations

from itellicoai import Itellicoai

client = Itellicoai(api_key="My API Key")

conversations = client.accounts.list_conversations(
    account_id="account_id"
)

for conv in conversations.items:
    print(f"Conversation ID: {conv.conversation_id}")
    print(f"Contact: {conv.contact_number}")
    print(f"Duration: {conv.duration_seconds}s")
    print(f"Status: {conv.status}")

​
List Phone Numbers

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
phone_numbers = client.accounts.phone_numbers.list(
    account_id="account_id",
)
print(phone_numbers.count)

​
Create Phone Number

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
phone_number = client.accounts.phone_numbers.create(
    account_id="account_id",
    sip_trunk_id="sip_trunk_id",
)
print(phone_number.id)

​
Get Phone Number

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
phone_number = client.accounts.phone_numbers.retrieve(
    phone_number_id="phone_number_id",
    account_id="account_id",
)
print(phone_number.id)

​
Update Phone Number

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
phone_number = client.accounts.phone_numbers.update(
    phone_number_id="phone_number_id",
    account_id="account_id",
)
print(phone_number.id)

​
Delete Phone Number

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)
client.accounts.phone_numbers.delete(
    phone_number_id="phone_number_id",
    account_id="account_id",
)

​
List Models

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)

response = client.accounts.providers.list_models(
    account_id="account_id",
)
print(response)

​
List Transcribers

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)

response = client.accounts.providers.list_transcribers(
    account_id="account_id",
)
print(response)

​
List Voices

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)

response = client.accounts.providers.list_voices(
    account_id="account_id",
    provider="provider",
)
print(response)

​
List SIP Trunks

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)

sip_trunks = client.accounts.sip_trunks.list(
    account_id="account_id",
)
print(sip_trunks.count)

​
Create SIP Trunk

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)

sip_trunk = client.accounts.sip_trunks.create(
    account_id="account_id",
)
print(sip_trunk.id)

​
Get SIP Trunk

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)

sip_trunk = client.accounts.sip_trunks.retrieve(
    sip_trunk_id="sip_trunk_id",
    account_id="account_id",
)
print(sip_trunk.id)

​
Update SIP Trunk

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)

sip_trunk = client.accounts.sip_trunks.update(
    sip_trunk_id="sip_trunk_id",
    account_id="account_id",
)
print(sip_trunk.id)

​
Delete SIP Trunk

from itellicoai import Itellicoai

client = Itellicoai(
    api_key="My API Key",
)

client.accounts.sip_trunks.delete(
    sip_trunk_id="sip_trunk_id",
    account_id="account_id",
)

​
Get Usage Analytics

response = client.accounts.analytics.get_usage(
    account_id="account_id",
)
print(response.meta)

​
List Subaccounts

subaccounts = client.accounts.subaccounts.list(
    account_id="account_id",
)
print(subaccounts.count)

​
Create Subaccount

account = client.accounts.subaccounts.create(
    account_id="account_id",
    name="name",
)
print(account.id)

​
Get Subaccount

account = client.accounts.subaccounts.retrieve(
    subaccount_id="subaccount_id",
    account_id="account_id",
)
print(account.id)

​
Update Subaccount

account = client.accounts.subaccounts.update(
    subaccount_id="subaccount_id",
    account_id="account_id",
)
print(account.id)

​
Error Handling

from itellicoai import ItellicoAI
from itellicoai.exceptions import (
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    APIError
)

client = ItellicoAI(api_key="your-api-key")

try:
    agent = client.agents.retrieve("agent_123abc")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Agent not found")
except RateLimitError:
    print("Rate limit exceeded")
except APIError as e:
    print(f"API error: {e.message}")

​
Environment Variables

import os
from itellicoai import ItellicoAI

# API key automatically loaded from ITELLICO_API_KEY env var
client = ItellicoAI()

# Or set explicitly
client = ItellicoAI(api_key=os.getenv("ITELLICO_API_KEY"))

​
Resources

PyPI Package

Install from PyPI

GitHub Repository

View source code on GitHub

API Reference

REST API documentation