TikTok: transforme resultados de busca em uma lista semanal de temas para o suporte

A equipe de suporte precisa de uma lista de vídeos públicos do TikTok em que as pessoas discutem uma função pouco clara ou fazem perguntas sobre o produto. A busca manual é difícil de repetir de forma consistente, e as respostas da API de busca podem armazenar vídeos em diferentes partes do JSON. Abaixo está um script básico em Python que consulta resultados por palavras-chave, combina as duas estruturas, remove duplicatas por ID e salva os registros encontrados em um CSV.

O que o script vai produzir

O resultado será uma tabela com o ID do vídeo, o link, a descrição, o horário de publicação, o autor e os contadores de interação disponíveis. A equipe de suporte ou de marketing poderá marcar manualmente quais temas exigem uma resposta, uma atualização das instruções ou uma verificação no próprio CRM. A tabela reflete apenas os resultados retornados pela API para as consultas definidas; trate-a como uma amostra de trabalho para análise, não como um catálogo completo de todas as discussões.

O script resolve a coleta e a classificação inicial. Ele não determina automaticamente se uma descrição é uma dúvida, uma reclamação ou uma piada: é melhor adicionar essa classificação após uma revisão manual ou com um classificador separado, registrando o texto original e o motivo da decisão.

O que consultar e como a resposta é estruturada

Para buscar vídeos, a jsonscraper documenta a rota GET /searchVideo no host https://tiktok.evelode.com. O parâmetro obrigatório é keyword; é possível informar count, região, ordenação, período de publicação e o cursor da página seguinte. Por exemplo, a busca pode ser repetida para várias frases predefinidas: o nome de uma função, uma formulação comum de erro e uma pergunta breve sobre configuração. Os parâmetros e seus valores permitidos estão listados na documentação da API do TikTok.

Há uma particularidade importante para o analisador: o array aweme_list pode estar vazio, enquanto os objetos encontrados ficam em search_item_list, cada um contendo aweme_info. Por isso, o processador abaixo verifica as duas formas. Um exemplo de resposta e os campos observados na verificação de 25 de outubro de 2026 constam na especificação primária da jsonscraper; os campos de estatísticas podem estar ausentes, por isso o código não inventa valores.

Prepare a chave e a lista de consultas

Armazene a chave na variável de ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY, e não no arquivo de código-fonte. No terminal do Linux ou macOS, faça assim:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="sua_chave"

Instale a biblioteca de requisições e prepare um arquivo queries.txt com uma expressão de busca por linha, por exemplo, nome do produto configuração e nome da função não funciona. Escolha as formulações de acordo com o idioma do público e mantenha uma lista separada para que as coletas semanais comparem sempre as mesmas consultas.

python -m pip install requests

Faça a coleta e normalize os vídeos encontrados

O exemplo é compatível com Python 3.8 ou superior. Ele faz uma solicitação para cada frase, com um limite de resultados, verifica erros HTTP e o status geral e, em seguida, salva apenas os campos realmente presentes. As correspondências repetidas são combinadas por aweme_id, e todas as consultas em que um vídeo foi encontrado são registradas no campo keywords. O campo separado collected_at_utc registra o horário da coleta para permitir a comparação com execuções futuras.

import csv
import os
import sys
from datetime import datetime, timezone

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("Defina JSONSCRAPER_TIKTOK_LICENSE_KEY")


def get_items(tiktok):
    """Extrai vídeos das duas formas documentadas de resposta da busca."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("Status da API malsucedido para a consulta:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": author.get("unique_id") or author.get("nickname"),
                "play_count": stats.get("play_count"),
                "digg_count": stats.get("digg_count"),
                "comment_count": stats.get("comment_count"),
                "share_count": stats.get("share_count"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Total de vídeos únicos encontrados e salvos:", len(videos))

A solicitação é enviada por meio do parâmetro params, então a biblioteca codifica corretamente as frases de texto na URL. A chave fica no parâmetro de consulta, conforme descrito na documentação; não imprima a URL completa da solicitação nos registros do aplicativo. Para diagnóstico, registre o código da resposta HTTP, o nome da frase pesquisada e o horário da execução, mas exclua segredos e dados pessoais que não sejam necessários para a tarefa.

Como interpretar o CSV sem tirar conclusões indevidas

A coluna keywords contém todas as frases para as quais o vídeo foi encontrado; collected_at_utc permite diferenciar o horário de publicação do horário da coleta. O ID facilita a remoção de duplicatas, e o link permite a verificação por uma pessoa. Um contador vazio significa que o campo estava ausente na resposta específica, não que seu valor fosse zero.

Para uma primeira classificação, adicione à cópia de trabalho do CSV as colunas tema, tipo de sinal, resposta necessária e link para material interno. As opções de tema devem corresponder ao seu produto, por exemplo, instalação, pagamento, compatibilidade ou solução de problemas. Esse esquema transforma a coleta em uma fila de análise e permite verificar a decisão com base no vídeo original.

Agende a coleta

Comece executando o script manualmente e verifique algumas linhas e links. Depois, adicione-o ao cron, a uma tarefa de CI ou a um fluxo de automação capaz de executar um processo Python. Para relatórios regulares, salve cada coleta ou acrescente as linhas a um armazenamento com uma chave única para o vídeo e a data da captura. Assim, a equipe poderá diferenciar novas publicações encontradas de observações repetidas e acompanhar as mudanças nos contadores disponíveis entre as execuções.

O parâmetro cursor é previsto para percorrer os resultados e deve ser transmitido a partir da resposta da chamada anterior. A paginação foi intencionalmente omitida neste exemplo básico: um conjunto limitado de consultas é mais fácil de verificar e reproduzir. Se você adicionar páginas, armazene o cursor sem interpretá-lo, pare de acordo com o indicador de continuidade e defina um limite máximo de chamadas por execução. A solicitação à API retorna uma amostra; não interprete o número de linhas como cobertura completa do TikTok.

Limites práticos de uso

Os resultados da busca são adequados para encontrar vídeos com base em formulações já conhecidas pela equipe. Eles ajudam a reunir material para classificação, mas não substituem as solicitações recebidas, a análise do próprio site ou a verificação do contexto do vídeo. A descrição pode não conter a essência do vídeo, e as métricas disponíveis refletem o estado dos dados no momento da coleta. Registre os temas e as conclusões separadamente dos campos originais para que os funcionários possam revisar a classificação.

Antes de iniciar o monitoramento recorrente, defina quem tem acesso à coleta, por quanto tempo os dados serão armazenados e para que finalidade as informações públicas serão usadas. Armazene apenas os campos necessários para analisar o produto e prefira links para as publicações originais em vez de copiar arquivos de mídia. Para consultar e verificar as opções de integração disponíveis, consulte a página da TikTok Scraper API e a documentação da rota de busca.