Referência de Funções

Esta página documenta as funções FLOIP personalizadas disponíveis no Journey Builder da Turn. Essas funções estendem a especificação FLOIP padrão com funcionalidades específicas da Turn.

Controle

wait()

Pausa a execução da jornada por uma duração especificada antes de continuar para o próximo bloco.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`seconds`	integer \| expression	Sim	Número de segundos para aguardar

Retorna: Nenhum valor é retornado; o bloco apenas introduz um atraso.

Exemplo:

card MyCard do
  # Wait for 5 seconds before continuing
  wait(5)
  text("This message appears after the delay")
end

card PacedConversation do
  text("Let me check that for you...")
  wait(3)
  text("Here's what I found!")
end

Notas: Útil para espaçar mensagens, simular atrasos de digitação ou limitar a taxa de envio.

mark_as_read()

Marca uma mensagem do WhatsApp como lida e opcionalmente mostra um indicador de digitação.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`message_id`	expression	Sim	O ID da mensagem a marcar como lida (ex: @event.message.id)
`show_typing`	boolean	Não	Se deve mostrar um indicador de digitação (padrão: false)

Retorna: Nenhum valor é retornado; esta é uma operação fire-and-forget.

Exemplo:

card MyCard do
  # Simply mark the message as read
  mark_as_read(@event.message.id)
end

card WithTypingIndicator do
  # Mark as read and show typing indicator to simulate bot composing
  mark_as_read(@event.message.id, show_typing: true)
  wait(3)
  text("Here's the information you requested...")
end

Notas: O indicador de digitação desaparece automaticamente após 25 segundos ou quando a próxima mensagem é enviada. A jornada continua independentemente de a chamada da API ter sucesso.

post_reaction()

Publica uma reação com emoji em uma mensagem do WhatsApp, ou remove uma reação existente.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`emoji`	string	Sim	O emoji para reagir (use string vazia para remover reação)
`message_id`	expression	Sim	O ID da mensagem para reagir (ex: @event.message.id)

Retorna: Nenhum valor é retornado; esta é uma operação fire-and-forget.

Exemplo:

card MyCard do
  # React with thumbs up to the triggering message
  post_reaction(@event.message.id, "👍")
end

card AcknowledgeAndProcess do
  # React to acknowledge receipt
  post_reaction(@event.message.id, "👀")
  # Process the request...
  text("Processing your request...")
end

card RemoveReaction do
  # Remove an existing reaction by passing empty emoji
  post_reaction(@event.message.id, "")
end

Notas: Passe uma string vazia como emoji para remover uma reação existente. A jornada continua independentemente de a chamada da API ter sucesso.

Integração

app()

Chama uma função em um app Lua instalado e retorna o resultado.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`app_name`	string	Sim	O nome da definição do app a chamar
`args`	list	Sim	Lista de argumentos para passar à função (suporta expressões)
`function_name`	string	Sim	O nome da função a executar

Retorna: Um mapa com result (valor de retorno da função) e success (booleano). Também armazenado na variável app_result.

Exemplo:

card MyCard do
  # Call a function in a Lua app with arguments
  result = app("calculator", "add_numbers", ["10", "20"])
  text("Result: @(result.result)")
end

card WithExpressions do
  # Use expressions to pass dynamic values
  result = app("my_app", "process_data", ["@(contact.name)", "@(event.message.text)"])

  # Check if the call succeeded
  result when result.success do
    text("Success: @(result.result)")
  end

  result when not result.success do
    text("Error: @(result.result)")
  end
end

card UsingAppResult do
  # Results are also stored in the app_result variable
  app("weather", "get_forecast", ["@(contact.city)"])
  text("The weather is: @(app_result.result)")
end

Notas: O app deve estar instalado e habilitado. Argumentos de função suportam expressões que são avaliadas em tempo de execução.

get() / post() / ...

Faz uma requisição HTTP para uma URL externa e armazena a resposta no contexto da jornada.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`body`	string \| list	Não	Corpo da requisição (string para JSON, lista de pares para form data)
`cache_ttl`	integer	Não	TTL do cache em milissegundos (padrão: 60000)
`headers`	list	Sim	Lista de pares [chave, valor] para cabeçalhos HTTP
`method`	string	Sim	Método HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE
`mode`	string	Sim	sync (aguarda resposta) ou async (dispara e esquece)
`query`	list	Não	Lista de pares [chave, valor] para parâmetros de query
`timeout`	integer	Sim	Timeout da requisição em milissegundos (máx 20000)
`url`	expression	Sim	A URL a chamar (suporta expressões)

Retorna: Um mapa com url (URL requisitada), status (código de status HTTP), body (corpo da resposta, parseado como JSON se aplicável), headers, query e mode.

Exemplo:

card MyCard do
  # Simple GET request
  response = get("https://api.example.com/users")

  # GET with query parameters and custom timeout
  response = get("https://api.example.com/search",
    query: [["q", "@(contact.name)"], ["limit", "10"]],
    headers: [["Authorization", "Bearer @(secrets.api_token)"]],
    timeout: 10000
  )

  # POST with JSON body
  response = post("https://api.example.com/data",
    body: %{name: @(contact.name), phone: @(contact.urn)},
    headers: [
      ["Content-Type", "application/json"],
      ["Authorization", "Bearer @(secrets.api_token)"]
    ]
  )

  # POST with plain text body
  response = post("https://api.example.com/log",
    body: "User @(contact.name) completed action",
    headers: [["Content-Type", "text/plain; charset=utf-8"]]
  )

  # Fire-and-forget async request (doesn't wait for response)
  post("https://api.example.com/events",
    body: %{event: "user_action"},
    headers: [["Content-Type", "application/json"]],
    mode: "async"
  )

  # Access response fields
  text("Status: @(response.status)")
  text("Body: @(response.body)")
end

# Branching based on response status
card CheckStatus, then: HandleResponse do
  response = get("https://api.example.com/status")
end

card HandleResponse when response.status == 200 do
  text("Success: @(response.body.message)")
end

card HandleResponse when response.status != 200 do
  text("Error: @(response.body)")
end

Notas: Métodos HTTP suportados: get(), post(), put(), patch(), delete(), head(), options(), trace(). Timeout padrão é 5 segundos, máximo é 20 segundos. Modo padrão é sync.

IA (Agnóstico de Fornecedor)

ai_add_function()

Adiciona uma definição de função ao contexto de IA para chamadas de ferramentas.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	O objeto de conexão de IA
`description`	expression	Sim	Descrição da função para a IA
`name`	expression	Sim	Nome da função
`parameters`	expression	Sim	JSON Schema definindo os parâmetros da função

Retorna: Objeto de conexão atualizado com a definição da função adicionada.

Exemplo:

card MyCard do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))

  # Add a function the AI can call
  ai = ai_add_function(ai, "make_booking", "Book an appointment for the user", parse_json("""
  {
    "type": "object",
    "properties": {
      "date": {"type": "string", "description": "Appointment date in YYYY-MM-DD format"},
      "time": {"type": "string", "description": "Appointment time in HH:MM format"},
      "service": {"type": "string", "enum": ["consultation", "followup", "checkup"]}
    },
    "required": ["date", "time", "service"]
  }
  """))

  ai = ai_add_message(ai, "user", @(event.message.text))
  result = ai_chat_completion(ai)

  # Check if the AI called a function
  result when result.response.functions != [] do
    # Handle the function call
    text("Booking confirmed!")
  end
end

Notas: Os parâmetros devem ser um objeto JSON Schema válido. A IA chamará a função quando apropriado e retornará os argumentos em result.response.functions.

ai_add_image()

Adiciona uma imagem ao contexto de IA para modelos com capacidade de visão.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	O objeto de conexão de IA
`image_url`	expression	Sim	URL da imagem (URL pública ou data URI)
`max_tokens`	expression	Não	Máximo de tokens para a resposta
`prompt`	expression	Sim	Prompt de texto descrevendo o que fazer com a imagem
`role`	expression	Sim	Papel da mensagem (tipicamente user)

Retorna: Objeto de conexão atualizado com a mensagem de imagem adicionada.

Exemplo:

card MyCard do
  ai = ai_add_image(ai, "user", "Describe this image", @(event.message.image.url), 300)
end

ai_add_message()

Adiciona uma única mensagem ao contexto de conversa da IA.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	O objeto de conexão de IA
`message`	expression	Sim	O conteúdo da mensagem
`role`	expression	Sim	Papel da mensagem (system, user ou assistant)

Retorna: Objeto de conexão atualizado com a nova mensagem adicionada.

Exemplo:

card MyCard do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))

  # Add a system message to set the AI's behavior
  ai = ai_add_message(ai, "system", "You are a helpful customer support agent.")

  # Add the user's message
  ai = ai_add_message(ai, "user", @(event.message.text))

  # Get the AI response
  result = ai_chat_completion(ai)
  text(@(result.response))
end

Notas: Papéis: system (instruções), user (entrada do cliente), assistant (respostas da IA para contexto).

ai_add_messages()

Adiciona múltiplas mensagens ao contexto de conversa da IA.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	O objeto de conexão de IA
`messages`	expression	Sim	Lista de conteúdos de mensagens
`role`	expression	Sim	Papel da mensagem (system, user ou assistant)

Retorna: Objeto de conexão atualizado com as novas mensagens adicionadas.

Exemplo:

card MyCard do
  ai = ai_add_messages(ai, "user", ["Hello", "How are you?"])
end

ai_agent()

Executa um agente de IA com intents, skills e memória de conversa para interações complexas.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	O objeto de conexão de IA
`contact_fields`	expression	Não	Campos de contato para incluir no contexto
`data`	expression	Sim	Contexto de dados adicional para o agente
`instructions`	expression	Sim	Instruções do sistema para o agente
`intents`	expression	Sim	Lista de intents que o agente pode reconhecer
`skills`	list	Não	Lista de skills que o agente pode chamar. Inclui skills de conhecimento (conteúdo estático) e skills de código (funções Lua). Veja Skills de Agentes IA.

Retorna: Resposta do agente com action (intent reconhecida ou 'continue_conversation'), response (texto da IA para exibir), status (código HTTP) e error (booleano).

Exemplo:

# Padrão de loop de conversa do agente
# O card do agente chama a si mesmo para criar uma conversa multi-turno

card Agent do
  ai = ai_assistant("assistant-uuid")
  ai = ai_conversation_memory(ai, "journey")

  # Define intents the agent can recognize
  intents = parse_json("""
  [
    {"id": "book_appointment", "name": "Book Appointment", "description": "When the user wants to schedule an appointment"},
    {"id": "get_info", "name": "Get Information", "description": "When the user asks about hours or services"}
  ]
  """)

  # Data to collect from the user (empty list if not collecting data)
  data_to_collect = parse_json("[]")

  agent_result = ai_agent(ai, "You are a friendly booking assistant. Help users schedule appointments.", intents, data_to_collect)

  # Handle errors
  then(ErrorCard when agent_result.error == true)

  # Handle end of conversation
  then(EndCard when agent_result.action == "end_conversation")

  # Handle recognized intents - route to specific flows
  then(BookAppointment when agent_result.action == "book_appointment")
  then(GetInfo when agent_result.action == "get_info")

  # Display the agent's response and wait for user input
  ask("@agent_result.response")

  # Loop back to continue the conversation
  then(Agent when agent_result.action == "continue_conversation")
end

card ErrorCard do
  text("Sorry, something went wrong. Please try again later.")
end

card EndCard do
  text("Thank you for chatting! Have a great day.")
end

card BookAppointment do
  run_stack("booking-flow-uuid")
end

card GetInfo do
  text("We're open Monday-Friday, 9am-5pm at 123 Main St.")
end

Notas: Crie loops de conversa fazendo o card do agente chamar a si mesmo quando action for 'continue_conversation'. Use ask() para exibir a resposta e aguardar entrada do usuário. Ações embutidas: submit_recognized_intent() dispara roteamento de intent, end_conversation() encerra o loop.

ai_chat_completion()

Executa uma requisição de chat completion com todas as mensagens e funções na conexão.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	O objeto de conexão de IA com mensagens
`json_schema`	map	Não	JSON Schema para saída estruturada (quando response_format é json_object)
`response_format`	string	Não	Formato de resposta (text ou json_object)

Retorna: Um mapa com status, error e response (contendo sentences, functions, combined e value).

Exemplo:

card MyCard do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))
  ai = ai_add_message(ai, "system", "You are a helpful assistant.")
  ai = ai_add_message(ai, "user", @(event.message.text))

  result = ai_chat_completion(ai)

  # result contains:
  # %{
  #   "status" => 200,
  #   "error" => false,
  #   "response" => %{
  #     "__value__" => "Hello! How can I help you today?",
  #     "sentences" => ["Hello!", "How can I help you today?"],
  #     "functions" => [],
  #     "combined" => [...]
  #   }
  # }

  text(@(result.response))
end

card WithJsonResponse do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))
  ai = ai_add_message(ai, "user", "List 3 colors")

  # Request JSON response format
  result = ai_chat_completion(ai, response_format: "json_object")
end

Notas: O campo value contém a resposta de texto completa. Use response_format: "json_object" para saída JSON estruturada.

ai_connect()

Cria um objeto de conexão de IA para qualquer fornecedor suportado (OpenAI, Anthropic, Google, etc.).

Configuração:

Campo	Tipo	Obrigatório	Descrição
`model`	expression	Sim	O modelo de IA a usar (ex: gpt-4, claude-3-opus)
`token`	expression	Sim	Token de API para autenticação
`vendor`	expression	Sim	Identificador do fornecedor de IA (openai, anthropic, google, etc.)

Retorna: Um objeto de conexão com type, token, model, vendor, messages, functions e max_tokens.

Exemplo:

card MyCard do
  # Connect to OpenAI
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))
end

card AnthropicExample do
  # Connect to Anthropic Claude
  ai = ai_connect("anthropic", "claude-3-opus-20240229", @(secrets.anthropic_token))
end

card MetaExample do
  # Connect to Meta Llama
  ai = ai_connect("meta_ai", "llama-3", @(secrets.meta_ai_token))
end

Notas: Fornecedores suportados: openai, anthropic, google, meta_ai. Use o nome de modelo apropriado para cada fornecedor.

ai_assistant()

Cria uma conexão com um Assistente de IA pré-configurado.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`uuid`	expression	Sim	UUID do assistente para conectar

Retorna: Um objeto de conexão com detalhes do assistente, vendor, messages, functions e max_tokens.

Exemplo:

card MyCard do
  ai = ai_assistant("assistant-uuid")
end

ai_conversation_memory()

Configura as definições de memória de conversa para a conexão de IA.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	O objeto de conexão de IA
`memory_setting`	expression	Sim	Modo de memória: journey (escopo de sessão), longterm ou none

Retorna: Objeto de conexão atualizado com configurações de memória.

Exemplo:

card MyCard do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))

  # Use long-term memory (persists across sessions)
  ai = ai_conversation_memory(ai, "longterm")

  ai = ai_add_message(ai, "user", @(event.message.text))
  result = ai_chat_completion(ai)
end

card SessionMemory do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))

  # Use journey-scoped memory (clears when journey ends)
  ai = ai_conversation_memory(ai, "journey")
end

card NoMemory do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))

  # Disable memory (each interaction is independent)
  ai = ai_conversation_memory(ai, "none")
end

Notas: Modos de memória: journey (padrão, escopo de sessão), longterm (persiste entre sessões para o contato), none (sem estado).

ai_text_classification()

Classifica entrada do usuário em categorias predefinidas usando IA.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	O objeto de conexão de IA
`options`	expression	Sim	Lista de opções de classificação
`system_prompt`	expression	Sim	Instruções para classificação
`user_input`	expression	Sim	O texto a classificar

Retorna: Resultado da classificação com a opção selecionada.

Exemplo:

card MyCard do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))

  # Classify user sentiment
  result = ai_text_classification(
    ai,
    @(event.message.text),
    "Classify the sentiment of this customer message",
    ["positive", "negative", "neutral"]
  )

  result when result == "negative" do
    text("I'm sorry you're having trouble. Let me connect you with support.")
  end

  result when result == "positive" do
    text("Great to hear! How else can I help?")
  end
end

card LanguageDetection do
  ai = ai_connect("openai", "gpt-4", @(secrets.openai_token))

  # Detect the language of the message
  language = ai_text_classification(
    ai,
    @(event.message.text),
    "Detect the language of this text",
    ["english", "spanish", "french", "portuguese", "other"]
  )
end

Notas: Retorna uma das opções fornecidas. Útil para roteamento, análise de sentimento, detecção de idioma e classificação de intent.

OpenAI (Legado)

openai_add_image()

Obsoleto: Use ai_add_image() em vez disso.

Adiciona uma imagem ao contexto OpenAI para uso com a API Vision.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	Objeto de conexão OpenAI
`max_tokens`	expression	Sim	Máximo de tokens para a resposta
`message`	expression	Sim	Prompt de texto para a imagem
`role`	expression	Sim	Papel da mensagem (tipicamente user)
`url`	expression	Sim	URL da imagem

Retorna: Objeto de conexão atualizado com a mensagem de imagem adicionada.

Exemplo:

card MyCard do
  openai = openai_add_image(openai, "user", "What's in this image?", @(image_url), 300)
end

openai_connect()

Obsoleto: Use ai_connect() em vez disso.

Cria um objeto de conexão OpenAI para uso com outros blocos OpenAI.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`model`	expression	Sim	Nome do modelo OpenAI (ex: gpt-4, gpt-3.5-turbo)
`token`	expression	Sim	Token de API OpenAI

Retorna: Um objeto de conexão com type, token, model, messages, functions, max_tokens e vendor.

Exemplo:

card MyCard do
  openai = openai_connect(@(secrets.openai_token), "gpt-4")
end

openai_connect_assistant()

Obsoleto: Use ai_assistant() em vez disso.

Cria uma conexão com um Assistente OpenAI usando o UUID da sessão como ID do thread.

Retorna: Um objeto de conexão com detalhes do thread do assistente.

Exemplo:

card MyCard do
  openai = openai_connect_assistant()
end

openai_create_speech()

Gera áudio de fala a partir de texto usando a API de text-to-speech da OpenAI.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	Objeto de conexão OpenAI
`model`	expression	Sim	Modelo TTS (tts-1 ou tts-1-hd)
`text`	expression	Sim	Texto para converter em fala
`voice`	expression	Sim	Voz a usar (alloy, echo, fable, onyx, nova, shimmer)

Retorna: Um objeto de anexo com external_id para uso em mensagens de áudio.

Exemplo:

card MyCard do
  openai = openai_connect(@(secrets.openai_token), "gpt-4")

  # Generate speech from text
  speech = openai_create_speech(openai, "Hello! How can I help you today?", "nova", "tts-1")

  # Send the audio to the user
  audio(@(speech.external_id))
end

card DynamicVoiceResponse do
  openai = openai_connect(@(secrets.openai_token), "gpt-4")

  # Use a variable for the text
  speech = openai_create_speech(openai, @(ai_response), "alloy", "tts-1-hd")
  audio(@(speech.external_id))
end

Notas: Vozes disponíveis: alloy, echo, fable, onyx, nova, shimmer. Modelos: tts-1 (mais rápido) ou tts-1-hd (maior qualidade).

openai_transcribe()

Transcreve áudio para texto usando a API Whisper da OpenAI.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	Objeto de conexão OpenAI
`language`	expression	Sim	Código do idioma (ex: en, es, fr)
`prompt`	expression	Sim	Prompt para guiar a transcrição (pode ser string vazia)
`url`	expression	Sim	URL do arquivo de áudio a transcrever

Retorna: Texto transcrito do arquivo de áudio.

Exemplo:

card MyCard do
  openai = openai_connect(@(secrets.openai_token), "gpt-4")

  # Transcribe audio from a voice message
  transcription = openai_transcribe(openai, @(event.message.audio.url), "", "en")
  text("You said: @(transcription)")
end

card WithPromptHint do
  openai = openai_connect(@(secrets.openai_token), "gpt-4")

  # Use a prompt to guide transcription (useful for domain-specific terms)
  transcription = openai_transcribe(
    openai,
    @(event.message.audio.url),
    "Medical terminology including diagnoses and prescriptions",
    "en"
  )
end

card SpanishTranscription do
  openai = openai_connect(@(secrets.openai_token), "gpt-4")

  # Transcribe Spanish audio
  transcription = openai_transcribe(openai, @(event.message.audio.url), "", "es")
end

Notas: Usa o modelo Whisper da OpenAI. O prompt pode conter termos específicos do domínio para melhorar a precisão. Códigos de idioma seguem ISO 639-1 (en, es, fr, etc.).

Lelapa AI

lelapa_connect()

Cria uma conexão com os serviços de IA VulaVula da Lelapa.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`token`	expression	Sim	Token de API Lelapa

Retorna: Um objeto de conexão com type e token.

Exemplo:

card MyCard do
  # Create a Lelapa connection using your API token from secrets
  lelapa = lelapa_connect(@(secrets.lelapa_token))

  # Now use the connection with other Lelapa blocks
  sentiment = lelapa_sentiment_analysis(lelapa, @(event.message.text))
end

lelapa_entity_recognition()

Identifica entidades nomeadas (pessoas, locais, etc.) em texto usando NER da Lelapa.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	Objeto de conexão Lelapa
`text`	expression	Sim	Texto para analisar (máx 180 tokens)

Retorna: Lista de entidades com tipo de entidade, palavra, posições de início e fim.

Exemplo:

card MyCard do
  lelapa = lelapa_connect(@(secrets.lelapa_token))
  entities = lelapa_entity_recognition(lelapa, @(event.message.text))

  # entities is a list like:
  # [
  #   %{"entity" => "person", "word" => "Ramaphosa", "start" => 10, "end" => 19},
  #   %{"entity" => "location", "word" => "Emfuleni Municipality", "start" => 33, "end" => 54}
  # ]
end

Notas: Suporta múltiplos idiomas sul-africanos. Limitado a 180 tokens por requisição. Tipos de entidade incluem: person, location, organization.

lelapa_intent_classification()

Classifica entrada do usuário em intents especificadas com exemplos mínimos de treinamento.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	Objeto de conexão Lelapa
`examples`	expression	Sim	Lista de pares [intent, exemplo] para treinamento
`input`	expression	Sim	Texto a classificar

Retorna: Mapa com value (intent), intent e score.

Exemplo:

card MyCard do
  lelapa = lelapa_connect(@(secrets.lelapa_token))

  # Provide examples for each intent (supports multiple languages)
  result = lelapa_intent_classification(lelapa, @(event.message.text), [
    ["greeting", "Hello!"],
    ["greeting", "Hi there!"],
    ["greeting", "Habari yako?"],
    ["goodbye", "Goodbye!"],
    ["goodbye", "See you later!"],
    ["goodbye", "Kwaheri"]
  ])

  # result contains:
  # %{"__value__" => "greeting", "intent" => "greeting", "score" => 0.74}
  text("Detected intent: @(result.intent) with confidence @(result.score)")
end

Notas: Suporta múltiplos idiomas com aprendizado few-shot. Forneça pelo menos 2-3 exemplos por intent para melhores resultados.

lelapa_sentiment_analysis()

Analisa sentimento (positivo, negativo, neutro) em texto.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	Objeto de conexão Lelapa
`text`	expression	Sim	Texto para analisar

Retorna: Mapa com value (label), label, score, text e sentiments (para análise de múltiplas sentenças).

Exemplo:

card MyCard do
  lelapa = lelapa_connect(@(secrets.lelapa_token))
  sentiment = lelapa_sentiment_analysis(lelapa, @(event.message.text))

  # sentiment contains:
  # %{
  #   "__value__" => "positive",
  #   "label" => "positive",
  #   "score" => 0.99,
  #   "text" => "am happy",
  #   "sentiments" => [...]  # detailed breakdown for multi-sentence text
  # }

  sentiment when sentiment.label == "negative" do
    text("I'm sorry to hear that. How can I help?")
  end
end

Notas: Labels são: positive, negative, neutral. Para texto com múltiplas sentenças, o array sentiments contém análise por sentença.

lelapa_translate()

Traduz texto entre idiomas sul-africanos usando a API de tradução da Lelapa.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`connection`	expression	Sim	Objeto de conexão Lelapa
`source_lang`	expression	Sim	Código do idioma de origem (ex: zul_Latn, eng_Latn)
`target_lang`	expression	Sim	Código do idioma de destino
`text`	expression	Sim	Texto para traduzir

Retorna: Mapa com value (texto traduzido) e array translation.

Exemplo:

card MyCard do
  lelapa = lelapa_connect(@(secrets.lelapa_token))

  # Translate from Zulu to English
  translated = lelapa_translate(lelapa, @(event.message.text), "zul_Latn", "eng_Latn")
  # translated.__value__ = "This sentence is written in Zulu."

  text("Translation: @(translated)")
end

card TranslateToZulu do
  lelapa = lelapa_connect(@(secrets.lelapa_token))

  # Translate from English to Zulu
  translated = lelapa_translate(lelapa, "Hello, how are you?", "eng_Latn", "zul_Latn")
  text(@(translated))
end

Notas: Códigos de idioma suportados: eng_Latn (Inglês), zul_Latn (Zulu), xho_Latn (Xhosa), afr_Latn (Africâner), nso_Latn (Soto do Norte), sot_Latn (Soto do Sul), tsn_Latn (Tswana).

Controle​

wait()​

Whatsapp​

mark_as_read()​

post_reaction()​

Integração​

app()​

get() / post() / ...​

IA (Agnóstico de Fornecedor)​

ai_add_function()​

ai_add_image()​

ai_add_message()​

ai_add_messages()​

ai_agent()​

ai_chat_completion()​

ai_connect()​

ai_assistant()​

ai_conversation_memory()​

ai_text_classification()​

OpenAI (Legado)​

openai_add_image()​

openai_connect()​

openai_connect_assistant()​

openai_create_speech()​

openai_transcribe()​

Lelapa AI​

lelapa_connect()​

lelapa_entity_recognition()​

lelapa_intent_classification()​

lelapa_sentiment_analysis()​

lelapa_translate()​

Controle

wait()

Whatsapp

mark_as_read()

post_reaction()

Integração

app()

get() / post() / ...

IA (Agnóstico de Fornecedor)

ai_add_function()

ai_add_image()

ai_add_message()

ai_add_messages()

ai_agent()

ai_chat_completion()

ai_connect()

ai_assistant()

ai_conversation_memory()

ai_text_classification()

OpenAI (Legado)

openai_add_image()

openai_connect()

openai_connect_assistant()

openai_create_speech()

openai_transcribe()

Lelapa AI

lelapa_connect()

lelapa_entity_recognition()

lelapa_intent_classification()

lelapa_sentiment_analysis()

lelapa_translate()