Pular para o conteúdo principal

Solução de Problemas

Solução de Problemas​

Problemas Comuns e Soluções​

Falha na Instalação do App​

  • Verifique manifest.json: Garanta que assets/manifest.json existe e contém JSON válido
  • Verifique campos do manifest: Deve incluir app.name, app.version e app.description
  • Verifique a estrutura do ZIP: O arquivo principal deve ser nomeado {nome_do_app}.lua
  • Verifique o formato da versão: Use versionamento semântico no manifest (ex: 1.0.0, 2.1.3-beta)
  • Remova arquivos de teste: Não inclua arquivos spec/, turn.lua ou .rockspec

Mensagens de erro comuns:

  • :manifest_not_found - Arquivo assets/manifest.json ausente
  • :invalid_manifest_json - JSON malformado no arquivo manifest
  • :invalid_manifest_format - Campos obrigatórios ausentes no manifest

Subscrições de Contato Não Funcionando​

  • Garanta que set_contact_subscriptions() seja chamado no evento install
  • Verifique se os nomes dos campos correspondem exatamente (sensível a maiúsculas)
  • Verifique o valor de retorno para mensagens de erro: 
    local success, reason = turn.app.set_contact_subscriptions(fields)
    if not success then
        turn.logger.error("Subscrição falhou: " .. reason)
    end

Eventos de Jornada Não Disparando​

  • Verifique se o nome da função corresponde entre Jornada e app
  • Verifique o formato de retorno: deve ser "continue" ou "wait", ou "error"
  • Para fluxos assíncronos, armazene e use chat_uuid corretamente: 
    -- Armazena chat_uuid ao iniciar operação assíncrona
    store_webhook_data(webhook_id, data.chat_uuid)

    -- Mais tarde, no manipulador de webhook
    local chat_uuid = retrieve_webhook_data(webhook_id)
    turn.leases.send_input(chat_uuid, result)

Requisições HTTP Falhando​

  • Verifique o formato da URL e garanta que esteja completa (incluindo https://)
  • Verifique se os cabeçalhos estão formatados corretamente: 
    local body, status = turn.http.request({
        url = "https://api.example.com/endpoint",
        method = "POST",
        headers = {
            ["Content-Type"] = "application/json",
            ["Authorization"] = "Bearer " .. token
        },
        body = turn.json.encode(data)
    })

Problemas ao Carregar Módulos​

  • Garanta que os caminhos dos módulos sejam relativos à raiz do ZIP
  • Use barras normais em instruções require: 
    local utils = require("my_app.utils")  -- Correto
    -- NÃO: require("my_app\\utils")       -- Errado
    -- NÃO: require("my_app/utils")        -- Errado

Dicas de Depuração​

  1. Use Logging Extensivamente:

    turn.logger.debug("Iniciando processo com dados: " .. turn.json.encode(data))
    turn.logger.info("Processo concluído com sucesso")
    turn.logger.error("Falha ao processar: " .. error_message)

  2. Verifique os Logs do App: Veja logs na UI Turn → Configurações → Apps → Seu App → Logs

  3. Teste Localmente Primeiro: Use a API mock turn.lua para testes unitários

  4. Trate Valores Nil: Sempre verifique nil antes de usar valores:

    local value = data and data.field or "default"

  5. Valide Dados de Evento: Diferentes eventos têm estruturas de dados diferentes:

    if event == "journey_event" then
        if not data.function_name then
            turn.logger.error("Faltando function_name em journey_event")
            return "error", "Dados de evento de jornada inválidos"
        end
    end

Obtendo Ajuda​

Se você ainda estiver enfrentando problemas:

  1. Verifique os logs do app para mensagens de erro detalhadas
  2. Revise os apps de exemplo para padrões funcionais
  3. Entre em contato com o suporte Turn.io com:
    • O UUID do seu app
    • As mensagens de erro específicas
    • Passos para reproduzir o problema