Getting started

This guide explains how to establish and maintain a WebSocket connection to the Soccer Football API real-time service.

Connection URL

There is two connection urls:

wss://ws-eu.soccerfootball.info/?token=YOUR_WEBSOCKET_TOKEN

wss://ws-as.soccerfootball.info/?token=YOUR_WEBSOCKET_TOKEN

You must use the connection URL in response of /v1/ws/new call.

Connection flow

1. GET /v1/ws/new → Obtain WebSocket token

2. Connect to WSS → Establish WebSocket connection

3. Subscribe to channels → Start receiving events

4. Handle events → Process incoming messages

5. Renew token → Before expiration (every ~25 minutes)

---

Step-by-step guide

Step 1 — Obtain a WebSocket token

Call the /v1/ws/new endpoint to generate a new WebSocket token.

curl --request GET \
    --url 'https://api.soccerfootball.info/v1/ws/new/?t=YOUR_API_TOKEN'

The response contains everything you need to connect:

{
  "status": 200,
  "errors": [],
  "pagination": [],
  "result": [
    {
      "is_new": true,
      "token": "abc123xyz789...",
      "server": "wss://ws-eu.soccerfootball.info/?token=abc123xyz789...",
      "max_connections": 2,
      "max_subscribe_per_connection": 2,
      "allowed_channels": ["MAIN"],
      "expires_at": "2024-01-15 14:30:00"
    }
  ]
}

Save the token and use the server URL to connect. Note the expires_at timestamp — you will need to renew the token before this time.

Step 2 — Connect to WebSocket

Use the server URL from the previous response to establish a WebSocket connection:

const ws = new WebSocket("wss://ws-eu.soccerfootball.info/?token=abc123xyz789...");

ws.onopen = () => {
  console.log("Connected!");
};

Step 3 — Subscribe to a channel

Once connected, subscribe to the channels you need. For example, to receive all match events on the MAIN channel:

ws.send(JSON.stringify({
  "action": "subscribe",
  "channel": "MAIN",
  "scope": "all"
}));

You can also subscribe to a specific match or league:

// Subscribe to a specific match
ws.send(JSON.stringify({
  "action": "subscribe",
  "channel": "MAIN",
  "scope": "match",
  "id": "b01d28ac92221034"
}));

// Subscribe to a specific league
ws.send(JSON.stringify({
  "action": "subscribe",
  "channel": "MAIN",
  "scope": "league",
  "id": "f2b16fa54cb525d"
}));

The server confirms each subscription:

{
  "type": "subscribed",
  "channel": "MAIN",
  "scope": "all",
  "id": null,
  "topicKey": "MAIN:all",
  "message": "Successfully subscribed"
}

Step 4 — Handle events

Process incoming messages based on their type:

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case 'match_start':
      console.log(`Match started: ${msg.data.teamA.name} vs ${msg.data.teamB.name}`);
      break;
    case 'goal':
      console.log(`GOAL! Score: ${msg.data.score} at ${msg.data.timer}'`);
      break;
    case 'halftime':
      console.log(`Halftime: ${msg.data.score}`);
      break;
    case 'match_end':
      console.log(`Full time: ${msg.data.finalScore}`);
      break;
    case 'pong':
      // Keep-alive response
      break;
    case 'subscribed':
      console.log(`Subscribed to: ${msg.topicKey}`);
      break;
    case 'error':
      console.error(`Error: ${msg.message}`);
      break;
  }
};

Step 5 — Renew token before expiration

WebSocket tokens expire after approximately 25 minutes. You must call the /v1/ws/renew endpoint before the token expires to keep your connection alive.

Best practice: set a timer to renew 5 minutes before the expires_at timestamp.

// Renew the token via REST API
async function renewToken(apiToken, wsToken) {
  const response = await fetch(
    `https://api.soccerfootball.info/v1/ws/renew/?t=${apiToken}&wid=${wsToken}`
  );
  const data = await response.json();

  if (data.result[0].renewed) {
    console.log("Token renewed, new expiration:", data.result[0].expires_at);
  }
}

// Schedule renewal 5 minutes before expiration
const expiresAt = new Date("2024-01-15T14:30:00Z");
const renewAt = expiresAt.getTime() - (5 * 60 * 1000); // 5 minutes before
const delay = renewAt - Date.now();

setTimeout(() => {
  renewToken("YOUR_API_TOKEN", "abc123xyz789...");
}, delay);

---

Complete example

A full working example combining all steps: obtain token, connect, subscribe, handle events, keep-alive ping, and token renewal.

const API_TOKEN = "YOUR_API_TOKEN";

// Step 1 — Obtain token
async function start() {
  const res = await fetch(`https://api.soccerfootball.info/v1/ws/new/?t=${API_TOKEN}`);
  const json = await res.json();
  const { token, server, expires_at } = json.result[0];

  // Step 2 — Connect
  const ws = new WebSocket(server);

  ws.onopen = () => {
    console.log("Connected!");

    // Step 3 — Subscribe to MAIN channel
    ws.send(JSON.stringify({ action: "subscribe", channel: "MAIN", scope: "all" }));
  };

  // Step 4 — Handle events
  ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);
    console.log(`[${msg.type}]`, msg.channel || "", msg.data || msg.message || "");
  };

  ws.onerror = (err) => console.error("WebSocket error:", err);

  ws.onclose = (event) => {
    console.log(`Connection closed: ${event.code} - ${event.reason}`);
    // Implement reconnection logic here if needed
  };

  // Keep-alive ping every 30 seconds
  const pingInterval = setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({ action: "ping" }));
    }
  }, 30000);

  // Step 5 — Schedule token renewal 5 minutes before expiration
  const expiresAtMs = new Date(expires_at).getTime();
  const renewDelay = expiresAtMs - Date.now() - (5 * 60 * 1000);

  if (renewDelay > 0) {
    setTimeout(async () => {
      const renewRes = await fetch(
        `https://api.soccerfootball.info/v1/ws/renew/?t=${API_TOKEN}&wid=${token}`
      );
      const renewJson = await renewRes.json();
      console.log("Token renewed:", renewJson.result[0].expires_at);
    }, renewDelay);
  }
}

start();

---

MAIN_REALTIME channel (MEGA plan 🟩 only)

If you subscribe to the MAIN_REALTIME channel, the messages contain IDs that are specific to the realtime data source and differ from the standard REST API IDs. To map these realtime IDs to the corresponding REST IDs, use the following endpoints:

• /v1/live/ws — live matches with ID mapping

• /v1/championships/ws — championships with ID mapping

• /v1/teams/ws — teams with ID mapping

All other channels (MAIN, STATS, ODDS, STATS_REALTIME, ODDS_REALTIME) already use REST IDs — no mapping is needed.