SS7 Protocol Examples¶

TCAP Examples¶

Basic TCAP Transaction¶

from telcoapi.ss7 import tcap

# Initialize TCAP component
tcap_handler = tcap.TCAPHandler(
    ssn=146,  # Subsystem number
    gt="1234567890"  # Global title
)

# Begin transaction
transaction = tcap_handler.begin_transaction(
    called_party="9876543210",
    dialog_type=tcap.DialogType.STRUCTURED
)

# Add component
transaction.add_component(
    invoke_id=1,
    operation_code=32,  # Example operation code
    parameters={
        "subscriberInfo": "123456789"
    }
)

# Send the message
transaction.send()

# Wait for response
response = transaction.wait_for_response(timeout=5)
print(f"Received response: {response}")

TCAP Dialog with Multiple Components¶

# Create multiple components in a single dialog
dialog = tcap_handler.create_dialog()

# Add first component
dialog.add_invoke(
    operation=tcap.Operation.SEND_ROUTING_INFO,
    parameters={
        "msisdn": "1234567890",
        "gmsc": "0987654321"
    }
)

# Add second component
dialog.add_invoke(
    operation=tcap.Operation.PROVIDE_ROAMING_NUMBER,
    parameters={
        "imsi": "123456789012345",
        "msc": "9876543210"
    }
)

# Begin transaction with multiple components
dialog.begin()

MAP Examples¶

Location Update¶

from telcoapi.ss7 import map

# Initialize MAP service
map_service = map.MAPService(
    hlr_gt="1234567890",
    vlr_gt="0987654321"
)

# Send Update Location request
response = map_service.update_location(
    imsi="123456789012345",
    vlr_number="1234567890",
    msc_number="0987654321"
)

print(f"Location update response: {response}")

Send Authentication Info¶

# Request authentication vectors
auth_info = map_service.send_authentication_info(
    imsi="123456789012345",
    num_vectors=5
)

for vector in auth_info.vectors:
    print(f"RAND: {vector.rand}")
    print(f"SRES: {vector.sres}")
    print(f"Kc: {vector.kc}")

CAMEL Examples¶

Initial DP Operation¶

from telcoapi.ss7 import camel

# Initialize CAMEL service
camel_service = camel.CAMELService(
    gsmscf_address="1234567890"
)

# Send InitialDP
response = camel_service.initial_dp(
    service_key=100,
    called_party_number="9876543210",
    calling_party_number="1234567890",
    imsi="123456789012345"
)

print(f"InitialDP response: {response}")

Apply Charging Operation¶

# Send Apply Charging operation
charging_result = camel_service.apply_charging(
    time_duration_charging={
        "max_call_period_duration": 300,  # 5 minutes
        "audible_indicator": True,
        "tone_duration": 10
    }
)

print(f"Charging result: {charging_result}")

INAP Examples¶

Initial DP Service Example¶

from telcoapi.ss7 import inap

# Initialize INAP service
inap_service = inap.INAPService(
    scp_address="1234567890"
)

# Send InitialDP
response = inap_service.initial_dp(
    service_key=200,
    called_party_number="9876543210",
    calling_party_number="1234567890"
)

print(f"InitialDP response: {response}")

Connect Operation¶

# Send Connect operation
connect_result = inap_service.connect(
    destination_routing_address="9876543210",
    call_segments=[{
        "leg_id": 1,
        "notification_requested": True
    }]
)

print(f"Connect operation result: {connect_result}")

Error Handling¶

All examples above can be enhanced with proper error handling:

from telcoapi.ss7.exceptions import TCAPError, MAPError, CAMELError, INAPError

try:
    # Your SS7 protocol operation here
    result = service.operation()
except TCAPError as e:
    print(f"TCAP error occurred: {e}")
except MAPError as e:
    print(f"MAP error occurred: {e}")
except CAMELError as e:
    print(f"CAMEL error occurred: {e}")
except INAPError as e:
    print(f"INAP error occurred: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Best Practices¶

Always implement proper error handling
Set appropriate timeouts for operations
Use connection pooling for better performance
Implement retry mechanisms for transient failures
Monitor transaction rates and response times
Log all operations for troubleshooting
Implement circuit breakers for fault tolerance
Use secure connections when possible
Validate all input parameters
Implement proper cleanup of resources

Mobile Authentication¶

Send Authentication Info (SAI)¶

// Request authentication vectors from HLR
const saiRequest = {
  dialogType: 'BEGIN',
  components: [{
    type: 'invoke',
    operationCode: 'sendAuthenticationInfo',
    parameter: {
      imsi: '123450000000001',
      numberOfRequestedVectors: 5,
      requestingNodeType: 'vlr'
    }
  }]
};

try {
  const response = await client.ss7.sendTCAP(saiRequest);
  const { authenticationSets } = response.components[0].parameter;
  console.log(`Received ${authenticationSets.length} auth vectors`);
} catch (error) {
  console.error('SAI failed:', error);
}

Update Location (UL)¶

// Update subscriber location in HLR
const ulRequest = {
  dialogType: 'BEGIN',
  components: [{
    type: 'invoke',
    operationCode: 'updateLocation',
    parameter: {
      imsi: '123450000000001',
      mscNumber: '19195550123',
      vlrNumber: '19195550124',
      currentLocation: {
        ageOfLocationInformation: 0,
        locationInformation: {
          cellGlobalId: {
            mcc: '234',
            mnc: '15',
            lac: 1234,
            cellId: 5678
          }
        }
      }
    }
  }]
};

await client.ss7.sendTCAP(ulRequest);

SMS Operations¶

Mobile Originated SMS¶

// Send SMS from mobile device
const moSmsRequest = {
  dialogType: 'BEGIN',
  components: [{
    type: 'invoke',
    operationCode: 'mo-forwardSM',
    parameter: {
      sm_RP_DA: {
        serviceCentreAddressDA: '19195550100'
      },
      sm_RP_OA: {
        msisdn: '19195550200'
      },
      sm_RP_UI: {
        protocolId: 0,
        dataCodingScheme: 0,
        userDataLength: 10,
        shortMessage: Buffer.from('Hello World').toString('base64')
      }
    }
  }]
};

const response = await client.ss7.sendTCAP(moSmsRequest);

Mobile Terminated SMS¶

// Deliver SMS to mobile device
const mtSmsRequest = {
  dialogType: 'BEGIN',
  components: [{
    type: 'invoke',
    operationCode: 'mt-forwardSM',
    parameter: {
      sm_RP_DA: {
        imsi: '123450000000001'
      },
      sm_RP_OA: {
        serviceCentreAddressOA: '19195550100'
      },
      sm_RP_UI: {
        protocolId: 0,
        dataCodingScheme: 0,
        userDataLength: 14,
        shortMessage: Buffer.from('Message received').toString('base64')
      }
    }
  }]
};

await client.ss7.sendTCAP(mtSmsRequest);

ISUP Call Control¶

Initial Address Message (IAM)¶

// Initiate a call
const iamRequest = {
  cic: 1,
  natureOfConnectionIndicators: {
    satelliteIndicator: 'no-satellite',
    continuityCheckIndicator: 'not-required',
    echoControlDeviceIndicator: 'not-included'
  },
  forwardCallIndicators: {
    nationalInternationalCallIndicator: 'international',
    endToEndMethodIndicator: 'no-method-available',
    interworkingIndicator: 'no-interworking',
    endToEndInformationIndicator: 'no-end-to-end-information',
    isdnUserPartIndicator: 'isdn-all-the-way',
    isdnUserPartPreferenceIndicator: 'preferred'
  },
  callingPartyCategory: 'ordinary-subscriber',
  transmissionMediumRequirement: 'speech',
  calledPartyNumber: {
    natureOfAddressIndicator: 'international-number',
    numberingPlanIndicator: 'isdn-telephony',
    address: '442071234567'
  },
  callingPartyNumber: {
    natureOfAddressIndicator: 'international-number',
    numberingPlanIndicator: 'isdn-telephony',
    address: '14085550123',
    screeningIndicator: 'network-provided',
    addressPresentationRestricted: false
  }
};

await client.ss7.isup.sendIAM(iamRequest);

Answer Message (ANM)¶

// Answer the call
const anmRequest = {
  cic: 1,
  backwardCallIndicators: {
    chargeIndicator: 'charge',
    calledPartyStatusIndicator: 'subscriber-free',
    calledPartyCategoryIndicator: 'ordinary-subscriber',
    endToEndMethodIndicator: 'no-method-available'
  },
  connectedNumber: {
    natureOfAddressIndicator: 'international-number',
    numberingPlanIndicator: 'isdn-telephony',
    address: '442071234567'
  }
};

await client.ss7.isup.sendANM(anmRequest);

SCCP Routing¶

Global Title Translation¶

// Configure GTT rules
const gttConfig = {
  selector: 0,
  globalTitleIndicator: '0100',
  rules: [
    {
      prefix: '1919',  // US numbers
      translation: {
        pointCode: '2-2-2',
        subsystemNumber: 8,
        newGlobalTitle: {
          tt: 0,
          np: 1,
          nai: 4,
          address: '1919'
        }
      }
    },
    {
      prefix: '4420',  // UK numbers
      translation: {
        pointCode: '3-3-3',
        subsystemNumber: 8,
        newGlobalTitle: {
          tt: 0,
          np: 1,
          nai: 4,
          address: '4420'
        }
      }
    }
  ]
};

await client.ss7.configureGTT(gttConfig);

Load Balancing¶

// Configure load balancing for multiple destinations
const loadBalancingConfig = {
  mode: 'weighted-round-robin',
  destinations: [
    {
      pointCode: '2-2-2',
      weight: 2,
      subsystemNumber: 8
    },
    {
      pointCode: '2-2-3',
      weight: 1,
      subsystemNumber: 8
    }
  ],
  failover: {
    enabled: true,
    maxRetries: 3,
    timeout: 2000
  }
};

await client.ss7.configureLoadBalancing(loadBalancingConfig);

Network Management¶

Link Set Management¶

// Configure SS7 linksets
const linkSetConfig = {
  name: 'primary-linkset',
  adjacentPointCode: '2-2-2',
  links: [
    {
      code: 0,
      slc: 0,
      linkType: 'A',
      priority: 1
    },
    {
      code: 1,
      slc: 1,
      linkType: 'A',
      priority: 1
    }
  ],
  timing: {
    t1: 12000,  // Alignment ready timer
    t2: 11500,  // Not aligned timer
    t3: 11500,  // Aligned timer
    t4: 11500,  // Emergency proving timer
    t5: 800,    // Sending SIB timer
    t7: 1000    // Excessive delay timer
  }
};

await client.ss7.configureLinkSet(linkSetConfig);

Traffic Management¶

// Configure traffic management
const trafficConfig = {
  congestionControl: {
    levels: [
      { threshold: 70, actions: ['throttle-new-traffic'] },
      { threshold: 85, actions: ['reject-new-traffic'] },
      { threshold: 95, actions: ['reject-all-traffic'] }
    ]
  },
  loadSharing: {
    mode: 'sls-based',
    slsRotation: true
  },
  screening: {
    rules: [
      {
        type: 'dpc-based',
        pattern: '1-1-*',
        action: 'allow'
      },
      {
        type: 'si-based',
        pattern: 'sccp',
        action: 'allow'
      }
    ]
  }
};

await client.ss7.configureTrafficManagement(trafficConfig);

Monitoring and Debugging¶

Message Tracing¶

// Enable detailed message tracing
client.ss7.on('message', (msg) => {
  console.log({
    timestamp: new Date().toISOString(),
    direction: msg.direction,
    type: msg.type,
    opc: msg.opc,
    dpc: msg.dpc,
    sls: msg.sls,
    payload: msg.payload
  });
});

Performance Metrics¶

// Monitor performance metrics
client.ss7.on('metrics', (metrics) => {
  console.log({
    timestamp: new Date().toISOString(),
    messageRate: metrics.messageRate,
    avgResponseTime: metrics.avgResponseTime,
    errorRate: metrics.errorRate,
    congestionLevel: metrics.congestionLevel,
    linksetStatus: metrics.linksetStatus
  });
});