Diameter Gx API Reference¶

This document describes the REST API endpoints for managing Diameter Gx interface interactions in the TelcoAPI platform.

Endpoints¶

Create Credit Control Request (CCR)¶

POST /v1/diameter/gx/ccr

Request Body:

{
  "session_id": "telco.api.com;1234567890;1",
  "destination_realm": "pcrf.operator.com",
  "destination_host": "pcrf1.operator.com",
  "cc_request_type": "INITIAL",
  "cc_request_number": 0,
  "subscription": {
    "imsi": "234150123456789",
    "msisdn": "447123456789",
    "ip_can_type": "3GPP-EPS",
    "rat_type": "EUTRAN",
    "access_network_charging_address": "10.0.0.1"
  },
  "qos_information": {
    "qci": 9,
    "max_requested_bandwidth_ul": 1000000,
    "max_requested_bandwidth_dl": 2000000,
    "guaranteed_bitrate_ul": 500000,
    "guaranteed_bitrate_dl": 1000000
  }
}

Response:

{
  "session_id": "telco.api.com;1234567890;1",
  "result_code": 2001,
  "auth_application_id": 16777238,
  "cc_request_type": "INITIAL",
  "cc_request_number": 0,
  "qos_information": {
    "qci": 9,
    "max_authorized_bandwidth_ul": 1000000,
    "max_authorized_bandwidth_dl": 2000000,
    "guaranteed_bitrate_ul": 500000,
    "guaranteed_bitrate_dl": 1000000
  },
  "charging_rule_install": [
    {
      "charging_rule_name": ["video_streaming"],
      "precedence": 1,
      "flow_information": [
        {
          "flow_description": "permit out ip from any to 10.0.0.1/32",
          "flow_direction": "DOWNLINK"
        }
      ]
    }
  ],
  "event_triggers": ["USAGE_REPORT"],
  "usage_monitoring_information": {
    "monitoring_key": "video_key",
    "granted_service_unit": {
      "total_octets": 1000000000
    }
  }
}

Update Session (CCR-U)¶

PUT /v1/diameter/gx/ccr/{session_id}

Request Body:

{
  "cc_request_type": "UPDATE",
  "cc_request_number": 1,
  "usage_monitoring_report": [
    {
      "monitoring_key": "video_key",
      "used_service_unit": {
        "total_octets": 500000000
      }
    }
  ],
  "event_triggers": ["USAGE_THRESHOLD_REACHED"]
}

Response:

{
  "result_code": 2001,
  "session_id": "telco.api.com;1234567890;1",
  "cc_request_type": "UPDATE",
  "cc_request_number": 1,
  "usage_monitoring_information": {
    "monitoring_key": "video_key",
    "granted_service_unit": {
      "total_octets": 500000000
    }
  }
}

Terminate Session (CCR-T)¶

DELETE /v1/diameter/gx/ccr/{session_id}

Request Body:

{
  "cc_request_type": "TERMINATION",
  "cc_request_number": 2,
  "termination_cause": "DIAMETER_LOGOUT"
}

Response:

{
  "result_code": 2001,
  "session_id": "telco.api.com;1234567890;1",
  "cc_request_type": "TERMINATION",
  "cc_request_number": 2
}

Re-Authorization Request (RAR) Webhook¶

The platform will send RAR notifications to your configured webhook endpoint when the PCRF initiates a re-authorization request.

Example webhook payload:

{
  "event": "diameter.gx.rar",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "session_id": "telco.api.com;1234567890;1",
    "re_auth_request_type": "AUTHORIZE_ONLY",
    "charging_rule_install": [
      {
        "charging_rule_name": ["hd_video"],
        "precedence": 2
      }
    ],
    "event_triggers": ["REALLOCATION_OF_CREDIT"]
  }
}

Error Responses¶

Invalid AVP Format¶

{
  "type": "https://api.telco-sec.com/errors/validation-error",
  "title": "Invalid AVP Format",
  "status": 400,
  "detail": "Invalid QCI value. Must be between 1 and 9",
  "instance": "/diameter/gx/ccr"
}

Session Not Found¶

{
  "type": "https://api.telco-sec.com/errors/not-found",
  "title": "Session Not Found",
  "status": 404,
  "detail": "No active session found with ID telco.api.com;1234567890;1",
  "instance": "/diameter/gx/session"
}

PCRF Connection Error¶

{
  "type": "https://api.telco-sec.com/errors/connection-error",
  "title": "PCRF Connection Error",
  "status": 503,
  "detail": "Unable to establish connection with PCRF pcrf1.operator.com",
  "instance": "/diameter/gx/connection"
}

AVP Definitions¶

Common AVPs¶

AVP Name	Code	Type	Description
Session-Id	263	UTF8String	Unique session identifier
Origin-Host	264	DiameterIdentity	Origin host identity
Origin-Realm	296	DiameterIdentity	Origin realm identity
Destination-Realm	283	DiameterIdentity	Destination realm identity
CC-Request-Type	416	Enumerated	Type of credit control request
CC-Request-Number	415	Unsigned32	Credit control request sequence number

Gx Specific AVPs¶

AVP Name	Code	Type	Description
QoS-Information	1016	Grouped	QoS parameters
Charging-Rule-Install	1001	Grouped	PCC rules to be installed
Event-Trigger	1006	Enumerated	Event trigger type
Usage-Monitoring-Information	1067	Grouped	Usage monitoring control information

Rate Limits¶

Plan	Requests per Second	Burst
Basic	10	20
Premium	50	100
Enterprise	200	400