MQTT Ingress

MQTT ingress lets you push sports event data into Sportzcast using MQTT JSON messages.

Overview

Ingress supports:

  • REST discovery endpoints (event types and schema definitions)
  • MQTT publish channel for event payloads
  • MQTT status channel for validation/processing feedback

Authentication and access

Ingress requires approved access and valid authentication headers/tokens.

See: API Authentication and Access

REST endpoints (schema discovery)

Get available event types

  • GET https://servicehub.sportzcast.net/external/ingress/event-types
  • Returns supported sports with numeric id values.

Get schema by event type

  • GET https://servicehub.sportzcast.net/external/ingress/event-types/{eventTypeId}/class-definition
  • Returns property names and types for that ingress contract.

Typical error responses:

  • 400 invalid event type id
  • 401 missing/invalid auth
  • 404 event type not found
  • 500 server error

MQTT topics

Publish event data

Publish ingress payloads to:

bot/{botId}/ingress

Where:

  • botId is your numeric bot identifier
  • payload is valid JSON
  • payload includes at least EventId and event-specific fields

Receive status/error feedback

Subscribe to:

bot/{botId}/ingress_status

Status payload contains validation/processing errors.

Common status types:

  • 1 ParseError
  • 2 DeserializationError
  • 3 JsonParseError
  • 4 ProcessingError
  • 5 InvalidField
  • 6 SportEventProcessingError

Connection requirements

  • Protocol: MQTT 3.1.1 or higher
  • QoS: 1 recommended for ingress delivery
  • Keep Alive: 60s recommended (minimum 3s)
  • Clean Session: true recommended for new connections
  • Broker credentials: provided during access onboarding

Enable push permissions first

Before publishing ingress data, support must enable push permissions for:

  • your user
  • each target bot

Without these flags, ingress publish attempts will fail or be rejected.

Basic integration flow

  1. Request and configure access credentials.
  2. Call /event-types to identify your sport id.
  3. Call /event-types/{id}/class-definition to fetch exact contract schema.
  4. Connect to MQTT and subscribe to bot/{botId}/ingress_status.
  5. Publish events to bot/{botId}/ingress.
  6. Monitor status topic and fix schema/validation errors.

Example ingress payloads

Soccer

{
  "EventId": 8,
  "HomeTeamName": "Manchester United",
  "GuestTeamName": "Liverpool",
  "HomeScore": 2,
  "GuestScore": 1,
  "Clock": "40:30",
  "IsClockRunning": true,
  "ClockMode": ":",
  "Period": 1
}

Basketball

{
  "EventId": 3,
  "HomeTeamName": "Lakers",
  "GuestTeamName": "Warriors",
  "HomeScore": 98,
  "GuestScore": 102,
  "Period": 4,
  "Clock": "2:15",
  "IsClockRunning": true,
  "ClockMode": ":"
}