Getting Started with TelcoAPI¶

This guide will help you get started with TelcoAPI, a modern telecommunications protocol integration platform.

Overview¶

TelcoAPI provides seamless integration with various telecommunications protocols including: - SS7 Protocol Family (MAP, CAMEL, INAP, TCAP) - Diameter Protocol Family (Base, Gx, Rx, Rf, Ro/Gy) - IPX/GRX Protocols - SIP Protocol

Prerequisites¶

Before you begin, ensure you have:

Python 3.8 or higher installed
pip package manager
Virtual environment tool (venv)
Basic understanding of telecommunications protocols
Access to your telecom network elements

Installation¶

Create a virtual environment:
```
python -m venv .venv
```

Activate the virtual environment:

# On Windows
.venv\Scripts\activate

# On Unix or MacOS
source .venv/bin/activate

Install TelcoAPI:
```
pip install telcoapi
```

Quick Start Examples¶

1. SS7 MAP Example¶

from telcoapi.ss7 import MAPClient

# Initialize MAP client
client = MAPClient(
    host="your-ss7-gateway.com",
    point_code="1-1-1",
    subsystem=8  # MSC
)

# Send SendAuthenticationInfo request
async def authenticate_subscriber():
    response = await client.send_authentication_info(
        imsi="123456789012345"
    )
    print(f"Authentication vectors: {response.auth_vectors}")

2. Diameter Example¶

from telcoapi.diameter import DiameterClient

# Initialize Diameter client
client = DiameterClient(
    host="your-diameter-peer.com",
    port=3868,
    realm="example.com"
)

# Send Credit-Control-Request
async def request_credit():
    response = await client.send_credit_control_request(
        session_id="session-123",
        subscription_id="[email protected]",
        requested_units=100
    )
    print(f"Granted units: {response.granted_units}")

Basic Configuration¶

Create a config.yaml file:

telcoapi:
  ss7:
    point_code: "1-1-1"
    subsystem: 8
    routing_context: 100
    network_indicator: 2

  diameter:
    host: "client.example.com"
    realm: "example.com"
    vendor_id: 10415
    product_name: "TelcoAPI Client"

  security:
    tls_enabled: true
    cert_file: "/path/to/cert.pem"
    key_file: "/path/to/key.pem"

Next Steps¶

Review the Protocol Documentation for detailed information about each protocol
Check the API Reference for complete API details
Follow the Best Practices for production deployments
Explore Integration Guides for vendor-specific information

Common Issues¶

Connection Issues¶

SS7 Connectivity
Verify point code configuration
Check SCTP association status
Confirm network routing
Diameter Connectivity
Verify peer configuration
Check TLS certificates if enabled
Confirm network routing and firewall rules

Error Handling¶

from telcoapi.exceptions import TelcoAPIError

try:
    response = await client.send_request()
except TelcoAPIError as e:
    if e.code == "NETWORK_ERROR":
        print("Network connectivity issue")
    elif e.code == "PROTOCOL_ERROR":
        print("Protocol-level error")
    else:
        print(f"Unexpected error: {e}")