PreçosDocs
Entrar / CadastrarEntrar

REFERÊNCIA DE EVENTOS · FIREHOSE AO VIVO · TRANSMITINDO AGORA

Todo o vocabulário de eventos do TikTok LIVE

Chat. Presentes. Curtidas. Entradas. Seguidores. Batalhas. Inscrições. Todo evento das lives do TikTok chega por um único WebSocket, com metadados completos. O feed abaixo é o firehose público real, agora mesmo - não é uma simulação.

Pegar uma chave de avaliação de 7 diasLer a documentação

Feed de eventos ao vivo

0 eventos no buffer · live pública real

Esperando o próximo evento ao vivo...

O firehose público é mascarado, mas cada evento é um push real de uma sala real do TikTok LIVE. Conecte com a sua própria chave para receber o payload completo, sem máscara (usuários reais, avatares reais, diamantes reais) - a única coisa que muda entre os planos é o limite de conexões simultâneas.

Assine o firehose na sua stack

Escolha a linguagem. Copie. Rode. Chave sandbox em /pricing.

import { TiktokLiveClient } from '@tiktool/live'

const client = new TiktokLiveClient({
  apiKey: process.env.TIKTOOL_API_KEY,
  uniqueId: 'tiktok_handle_here',
})

client.on('gift', (e) => {
  console.log(`${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount} diamonds)`)
})

client.on('chat', (e) => console.log(`${e.user.uniqueId}: ${e.comment}`))
client.on('member', (e) => console.log(`+ join ${e.user.uniqueId}`))
client.on('like', (e) => console.log(`+ ${e.likeCount} likes`))
client.on('linkMicBattle', (e) => console.log('battle update', e.battleUsers))

await client.connect()

Cada evento, o que dispara e o que vem no payload

Todos os eventos usam o envelope { event: string, data: object }. Abaixo: cada tipo de evento e os dados que ele traz.

chatMuito frequente

Dispara quando um espectador envia uma mensagem no chat. O evento mais comum.

userObjectuniqueId, nickname, profilePictureUrl, badges
commentStringO texto da mensagem
userIdStringID numérico do usuário no TikTok
{
  "event": "chat",
  "data": {
    "user": {
      "uniqueId": "viewer42",
      "nickname": "Viewer 42"
    },
    "comment": "Hello!",
    "userId": "7123456789"
  }
}

giftModerada

Dispara quando um espectador envia um presente virtual. Inclui nome do presente, valor em diamantes e dados de sequência.

userObjectQuem enviou
giftNameStringex.: "Rosa", "Galáxia"
giftIdNumberID numérico do presente
diamondCountNumberValor em diamantes
repeatCountNumberContagem da sequência
repeatEndBooleanTrue quando a sequência termina
{
  "event": "gift",
  "data": {
    "user": {
      "uniqueId": "big_fan"
    },
    "giftName": "Rose",
    "giftId": 5655,
    "diamondCount": 1,
    "repeatCount": 5,
    "repeatEnd": true
  }
}

likeMuito frequente

Dispara quando um espectador toca no botão de curtir. Inclui o total acumulado de curtidas.

userObjectQuem curtiu
likeCountNumberContagem deste evento
totalLikeCountNumberTotal da live
{
  "event": "like",
  "data": {
    "user": {
      "uniqueId": "liker1"
    },
    "likeCount": 15,
    "totalLikeCount": 12500
  }
}

memberModerada

Dispara quando um espectador entra na sala da live.

userObjectUsuário que entrou
{
  "event": "member",
  "data": {
    "user": {
      "uniqueId": "new_viewer",
      "nickname": "New Viewer"
    }
  }
}

followBaixa

Dispara quando um espectador segue o streamer durante a live.

userObjectUsuário que seguiu
{
  "event": "follow",
  "data": {
    "user": {
      "uniqueId": "new_follower"
    }
  }
}

shareBaixa

Dispara quando um espectador compartilha a live.

userObjectUsuário que compartilhou
{
  "event": "share",
  "data": {
    "user": {
      "uniqueId": "sharer"
    }
  }
}

roomUserSeqPeriódica

Atualização periódica do número de espectadores. A principal forma de acompanhar os espectadores em tempo real. O SDK também emite como viewer_count (alias, mesmo payload).

viewerCountNumberEspectadores ao vivo agora
topViewersArrayOrdenados por engajamento
{
  "event": "roomUserSeq",
  "data": {
    "viewerCount": 1234,
    "topViewers": [
      {
        "user": {
          "uniqueId": "top_fan"
        },
        "coinCount": 5000
      }
    ]
  }
}

subscribeRara

Dispara quando um espectador se inscreve no streamer.

userObjectInscrito
{
  "event": "subscribe",
  "data": {
    "user": {
      "uniqueId": "subscriber1"
    }
  }
}

linkMicBattleDurante batalhas

Dispara quando uma batalha do TikTok LIVE começa, atualiza ou termina. Inclui placar + participantes.

battleUsersArrayParticipantes com placar
typeNumber1=início, 2=atualização, 3=fim
{
  "event": "linkMicBattle",
  "data": {
    "type": 1,
    "battleUsers": [
      {
        "uniqueId": "streamer1"
      },
      {
        "uniqueId": "streamer2"
      }
    ]
  }
}

roomPinRara

Dispara quando o streamer fixa uma mensagem do chat.

pinnedMessageObjectConteúdo da mensagem + quem enviou
{
  "event": "roomPin",
  "data": {
    "pinnedMessage": {
      "text": "Welcome!",
      "user": {
        "uniqueId": "streamer"
      }
    }
  }
}

Perguntas frequentes

Preciso de um plano pago para receber eventos?

Não para avaliar. A chave Sandbox funciona por 7 dias e entrega o payload real completo dos eventos (usuários reais, diamantes reais etc.) - o seu cliente assina o WebSocket upstream com o próprio cookie do TikTok. Durante a avaliação os limites são 3 conexões WebSocket simultâneas e 5.000 requisições REST/dia. Depois de 7 dias é preciso um plano pago; o Basic, por $7/semana, dá 20 WS simultâneos + 10.000 req/dia.

Qual evento dispara mais em uma live movimentada?

`like` e `chat` dominam em frequência. `gift` é o sinal de maior valor por evento.

Posso assinar vários criadores do TikTok ao mesmo tempo?

Pode. Abra um WebSocket por uniqueId. O plano Pro permite 50 WS simultâneos, o Ultra 250.

Como detecto quando uma sequência de presentes termina?

Só presentes com sequência (`giftType` 1) fazem sequência: fique de olho em `repeatEnd === true`, ou feche você mesmo quando nenhum frame novo chegar por alguns segundos, e use o maior `repeatCount`. Os outros presentes nunca mandam frame de fim: um envio em quantidade, como 8x, é um único frame com `repeatCount` 8, então conte assim que ele chegar. Em qualquer caso, o total de diamantes = `diamondCount * repeatCount`.

Qual é a latência em relação à live de verdade?

Os eventos chegam ~150-400ms depois de disparar no TikTok. Mais rápido que o próprio vídeo da live na maioria das CDNs.

As batalhas disparam para os dois criadores?

Sim. Conecte em qualquer um dos criadores da batalha - os dois recebem o mesmo evento `linkMicBattle` com os dois `battleUsers` preenchidos.