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.

Mensagens

send_content()

Envia um card de conteúdo (modelo de mensagem pré-definido) da biblioteca de conteúdo da Turn.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`content.uuid`	uuid	Sim	UUID do card de conteúdo a enviar
`content.wait_for_input`	boolean \| expression	Sim	Se deve aguardar a entrada do usuário após o envio

Exemplo:

card Card do
  send_content("content-uuid-here")
  # Or wait for response:
  resp = send_content("content-uuid-here", true)
end

add_label()

Adiciona um rótulo a uma mensagem no contexto atual.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`labels`	list	Sim	Lista de rótulos a aplicar
`message`	string	Sim	A referência da mensagem a rotular

Exemplo:

card Card do
  add_label("important")
  add_label(operator)
end

text()

Envia uma mensagem de texto ao usuário.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`prompt`	string	Sim	O conteúdo da mensagem a enviar

Exemplo:

card Greetings do
  text("Hello @contact.name!")
  text("Welcome to our service.")
end

Entrada

ask()

Solicita ao usuário uma resposta de texto livre com limite de caracteres opcional.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`max_response_characters`	number	Não	Comprimento máximo permitido da resposta
`prompt`	string	Sim	A pergunta a fazer ao usuário

Retorna: O texto da resposta digitado pelo usuário

Exemplo:

card AskName, then: Greetings do
  name = ask("What's your name?")
end

card Greetings do
  text("Hello @name!")
end

buttons()

Apresenta ao usuário um conjunto de opções como botões e aguarda que ele selecione uma.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`choices`	list	Sim	Lista de opções de botão (nomes de cards ou pares [valor, rótulo])
`prompt`	string	Sim	O texto da mensagem exibido com os botões

Retorna: Mapa com value, name, index e label da opção selecionada

Exemplo:

card ReadDocument do
  buttons([Accept, Decline]) do
    text("Please read and accept the terms")
    document("https://example.org/terms.pdf")
  end
end

card Accept do
  text("Thank you for accepting!")
end

Controle

log()

Registra uma mensagem no log do sistema para fins de depuração.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`message`	string	Sim	A mensagem a registrar

Exemplo:

card Card do
  log("user not opted in for follow ups")
  log("hello @today()")
end

run_stack()

Executa outra jornada (stack) e retorna ao fluxo atual quando concluída.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`flow_id`	uuid	Sim	UUID do fluxo a executar

Exemplo:

card Card do
  run_stack("10dca9d0-3f0b-11ed-b878-0242ac120002")
end

schedule_stack()

Agenda uma jornada para ser executada em um momento futuro, ou cancela uma jornada previamente agendada.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`flow_id`	uuid	Sim	UUID do fluxo a agendar
`schedule_at`	datetime	Não	Datetime específico para executar o fluxo
`schedule_in`	integer	Não	Número de segundos no futuro para executar o fluxo

Exemplo:

card Card do
  # Schedule to run in 1 hour
  schedule_stack("10dca9d0-3f0b-11ed-b878-0242ac120002", in: 3600)

  # Or schedule at a specific time
  schedule_stack("some-uuid", at: datetime_add(now(), 2, "D"))
end

Notas: É preciso fornecer schedule_at ou schedule_in. Para cancelar, forneça apenas flow_id.

wait()

Introduz um atraso no fluxo da jornada para controlar o tempo entre ações.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`seconds`	integer \| expression	Sim	Número de segundos para aguardar (suporta expressões)

Exemplo:

card DelayCard do
  text("Starting delay...")
  wait(2)
  text("Delay completed!")
end

Contato

update_contact()

Atualiza uma ou mais propriedades no contato atual.

Exemplo:

card SavePreferences do
  update_contact(name: "Boaty", surname: "McBoatFace")
  update_contact(opted_in: true)
end

Dados

update_dictionary()

Atualiza um par chave-valor em uma variável de dicionário.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	A chave a definir
`reference`	string	Sim	A variável de dicionário a atualizar
`value`	expression	Sim	A expressão de valor a avaliar e armazenar

Exemplo:

card Deposit do
  update_dictionary(account, "balance", account.balance + 1)
  text("You've deposited $1")
end

Chat

assign_chat_to()

Atribui o chat atual a um usuário ou fila.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`assign_to`	string	Sim	E-mail do usuário para atribuir o chat

Exemplo:

card Card do
  assign_chat_to("support@example.com")
end

call_permission_request()

Solicita permissão para ligar para o usuário via o recurso nativo de permissão de chamada do WhatsApp.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`call_permission_request.text`	string	Sim	O texto da mensagem pedindo ao usuário que conceda permissão de chamada

Retorna: A resposta de permissão de chamada do usuário

Exemplo:

card RequestPermission do
  granted = call_permission_request("Can we call you to assist?")
end

card ThankYou do
  text("Thank you!")
end

whatsapp_cta()

Envia uma mensagem de URL Call-to-Action (CTA) interativa do WhatsApp com um botão tocável que abre uma URL.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`cta_url.cta`	string	Sim	Texto do botão de call-to-action
`cta_url.footer`	string	Não	Texto de rodapé opcional
`cta_url.header`	object	Não	Objeto de cabeçalho opcional com um `type` ("text", "image", "video" ou "document") e um `value`
`cta_url.text`	string	Sim	Texto do corpo da mensagem
`cta_url.url`	string	Sim	A URL que o botão abre

Retorna: Nada; mensagens de URL CTA não aguardam a entrada do usuário

Exemplo:

card Card do
  whatsapp_cta("Visit our site", "https://example.com") do
    text("Tap the button below to learn more")
  end
end

catalog()

Exibe um catálogo de produtos do WhatsApp permitindo que os usuários naveguem e peçam produtos.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`catalog.footer`	string	Não	Texto de rodapé opcional
`catalog.text`	string	Sim	O texto do corpo do catálogo

Retorna: O pedido/seleção do usuário a partir do catálogo

Exemplo:

card Card do
  catalog("Check out our products!") do
    footer("Visit our store")
  end
end

request_contact_info()

Solicita o número de telefone do usuário via o recurso nativo de compartilhamento de contato do WhatsApp.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`request_contact_info.text`	string	Sim	O texto da mensagem pedindo ao usuário que compartilhe seu número de telefone

Retorna: "already_shared" quando o número já estava registrado, "shared" para qualquer resposta ao prompt

Exemplo:

card RequestContactInfo do
  ref_RequestContactInfo = request_contact_info("Please share your phone number so we can help you.")
  then(AlreadyHadIt when ref_RequestContactInfo == "already_shared")
  then(ThankYou when ref_RequestContactInfo == "shared" and contact.whatsapp_id != null)
end

card AlreadyHadIt do
  text("Let's continue.")
end

card ThankYou do
  text("Thank you for sharing your number!")
end

request_location()

Solicita a localização do usuário via o recurso nativo de compartilhamento de localização do WhatsApp.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`request_location.text`	string	Sim	O texto da mensagem pedindo ao usuário que compartilhe sua localização

Retorna: Os dados de localização compartilhados pelo usuário

Exemplo:

card RequestLocation do
  location = request_location("Please share your location")
end

card ThankYou, when: "@input.location != nil" do
  text("Thank you for sharing your location!")
end

whatsapp_flow()

Envia um WhatsApp Flow (formulário interativo) para coleta nativa de dados no WhatsApp.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`flow.cta`	string	Sim	Texto do botão de call-to-action
`flow.footer`	string	Não	Texto de rodapé opcional
`flow.header`	string	Não	Texto de cabeçalho opcional
`flow.id`	string	Sim	O ID do WhatsApp Flow
`flow.screen`	string	Sim	A tela a exibir
`flow.text`	string	Sim	Texto do corpo da mensagem

Retorna: Dados JSON capturados pelo WhatsApp Flow

Exemplo:

card Card do
  whatsapp_flow("Start Survey", "flow-id", "WELCOME") do
    text("Please complete our survey")
  end
end

send_message_template()

Envia um modelo de mensagem do WhatsApp com parâmetros dinâmicos.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`template.components`	list	Sim	Lista de componentes do modelo com parâmetros
`template.language.code`	string	Sim	Código do idioma do modelo
`template.name`	string	Sim	O nome do modelo

Retorna: O JSON enviado quando o modelo tem um botão de flow, caso contrário um mapa com value e index quando o modelo tem botões de resposta

Exemplo:

card Card do
  send_message_template("template_name", "en", ["param-1", "param-2"])
end

video_call_request()

Envia uma mensagem de chamada de vídeo do WhatsApp com um botão de chamada que o usuário pode tocar para ligar para a empresa.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`video_call_request.display_text`	string	Não	Rótulo opcional para o botão de chamada (padrão: "Call Now")
`video_call_request.text`	string	Sim	O corpo da mensagem pedindo ao usuário que ligue

Retorna: nil

Exemplo:

card OfferCall do
  video_call_request("Tap below to call us", display_text: "Call support")
end

card NextStep do
  text("We look forward to your call!")
end

voice_call_request()

Envia uma mensagem de chamada de voz do WhatsApp com um botão de chamada que o usuário pode tocar para ligar para a empresa.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`voice_call_request.display_text`	string	Não	Rótulo opcional para o botão de chamada (padrão: "Call Now")
`voice_call_request.text`	string	Sim	O corpo da mensagem pedindo ao usuário que ligue

Retorna: nil

Exemplo:

card OfferCall do
  voice_call_request("Tap below to call us", display_text: "Call support")
end

card NextStep do
  text("We look forward to your call!")
end

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

conversion()

Envia eventos de conversão para a Conversions API da Meta para otimização e medição de anúncios.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`conversion.event_name`	string	Sim	O nome do evento de conversão (ex: "Purchase", "Lead")
`conversion.optional_fields`	map	Não	Campos opcionais como event_id, event_source_url
`conversion.user_data`	map	Sim	Dados do usuário para correspondência (e-mail, telefone, etc.)

Exemplo:

card Card do
  conversion("Purchase", phone: "+1234567890", email: "user@example.com")
end

get() / post() / put() / patch() / delete()

Faz requisições HTTP para APIs externas. Suporta os métodos GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS e TRACE.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`body`	string \| list	Não	Corpo da requisição (string ou pares chave-valor)
`headers`	list	Sim	Lista de pares [chave, valor] para cabeçalhos
`method`	string	Sim	Método HTTP (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE)
`mode`	string	Sim	Modo de execução "sync" ou "async"
`query`	list	Não	Lista de pares [chave, valor] para parâmetros de query
`timeout`	number	Sim	Timeout da requisição em milissegundos (máx 20000)
`url`	string	Sim	A URL a chamar

Retorna: Mapa com url, status, body, query, mode e headers da resposta

Exemplo:

card MyCard do
  response = get("https://api.example.org/data",
    timeout: 5000,
    query: [["id", "@contact.id"]]
  )
  text("Status: @response.status")
end

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.

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, 'end_conversation' ou 'continue_conversation' para uso interno do loop), response (texto da IA enviado ao usuário), status (código HTTP) e error (booleano).

Exemplo:

# Agent card that handles its own conversation loop.
# ai_agent() sends its own messages and waits for user input on its own.
# It only returns to the flow when an action is recognized (intent,
# end_conversation, or error).

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")
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: O agente gerencia seu próprio loop de conversa. Ele envia mensagens, aguarda a entrada do usuário e só retorna ao fluxo quando uma ação é produzida (intent reconhecida ou end_conversation). 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_model()

Cria uma conexão diretamente com um fornecedor/modelo de IA, usando as credenciais configuradas da organização para esse fornecedor (sem necessidade de assistente).

Configuração:

Campo	Tipo	Obrigatório	Descrição
`model`	expression	Sim	Identificador do modelo para o fornecedor escolhido
`vendor`	expression	Sim	Identificador do fornecedor de IA (ex: "openai", "anthropic", "gemini")

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

Exemplo:

card MyCard do
  ai = ai_model("anthropic", "claude-sonnet-4-6")
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_stt()

Transcreve áudio para texto usando um provedor STT configurado (OpenAI embutido ou um adaptador instalado via app).

Configuração:

Campo	Tipo	Obrigatório	Descrição
`stt_model`	expression	Não	ID de modelo específico do provedor (ex: "whisper-1", "scribe_v1").
`stt_options`	map	Não	Opções específicas do provedor encaminhadas ao adaptador (ex: `language`, `prompt`, extras do fornecedor).
`stt_provider`	expression	Não	ID do provedor STT. Use "openai" (embutido, padrão) ou "app:app_name:adapter_name" para um adaptador fornecido por app.
`url`	expression	Sim	URL (ou id externo do anexo) do áudio a transcrever

Retorna: A string de transcrição combinada.

Exemplo:

card Listen do
  url = attachment_url(event.message.audio.id)
  text = ai_stt(url,
    stt_provider: "openai",
    stt_model: "whisper-1",
    stt_options: parse_json("""
    {"language": "en"}
    """)
  )
end

ai_tts()

Gera áudio de fala a partir de texto usando um provedor TTS configurado (OpenAI embutido ou um adaptador instalado via app).

Configuração:

Campo	Tipo	Obrigatório	Descrição
`text`	expression	Sim	Texto para converter em fala
`tts_model`	expression	Não	ID de modelo específico do provedor (ex: "gpt-4o-mini-tts", "tts-1").
`tts_options`	map	Não	Opções específicas do provedor encaminhadas ao adaptador (ex: `stability` do ElevenLabs).
`tts_provider`	expression	Não	ID do provedor TTS. Use "openai" (embutido, padrão) ou "app:app_name:adapter_name" para um adaptador fornecido por app.
`tts_voice`	expression	Não	ID de voz específico do provedor (ex: "alloy", "nova").

Retorna: Um objeto de anexo com external_id para uso em mensagens audio().

Exemplo:

card SaySomething do
  speech = ai_tts("Hello there!",
    tts_provider: "openai",
    tts_voice: "alloy",
    tts_model: "gpt-4o-mini-tts"
  )
  audio(@(speech.external_id))
end

card UseAppVendor do
  speech = ai_tts("Welcome",
    tts_provider: "app:elevenlabs:default",
    tts_voice: "Rachel",
    tts_options: parse_json("""
    {"stability": 0.5}
    """)
  )
  audio(@(speech.external_id))
end

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

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).

Analytics

track_event()

Emite um evento de analytics para o ClickHouse para rastreamento de métricas.

Configuração:

Campo	Tipo	Obrigatório	Descrição
`dimensions`	map	Não	Mapa opcional de nomes de dimensões para expressões, usado para filtragem/agrupamento
`metric_name`	string	Sim	O nome da métrica a rastrear (ex.: "appointment/booked")

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

Exemplo:

card TrackBooking do
  track_event("appointment/booked")
end

card TrackWithDimensions do
  track_event("csat/score/submitted",
    clinic_id: clinic_id, doctor: "Frank"
  )
end

Notas: Os eventos são enfileirados para inserção no ClickHouse. A jornada continua independentemente de a emissão do evento ser bem-sucedida.

Mensagens​

send_content()​

add_label()​

text()​

Entrada​

ask()​

buttons()​

Controle​

log()​

run_stack()​

schedule_stack()​

wait()​

Contato​

update_contact()​

Dados​

update_dictionary()​

Chat​

assign_chat_to()​

WhatsApp​

call_permission_request()​

whatsapp_cta()​

catalog()​

request_contact_info()​

request_location()​

whatsapp_flow()​

send_message_template()​

video_call_request()​

voice_call_request()​

mark_as_read()​

post_reaction()​

Integração​

conversion()​

get() / post() / put() / patch() / delete()​

app()​

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_model()​

ai_conversation_memory()​

ai_stt()​

ai_tts()​

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()​

Analytics​

track_event()​

Mensagens

send_content()

add_label()

text()

Entrada

ask()

buttons()

Controle

log()

run_stack()

schedule_stack()

wait()

Contato

update_contact()

Dados

update_dictionary()

Chat

assign_chat_to()

WhatsApp

call_permission_request()

whatsapp_cta()

catalog()

request_contact_info()

request_location()

whatsapp_flow()

send_message_template()

video_call_request()

voice_call_request()

mark_as_read()

post_reaction()

Integração

conversion()

get() / post() / put() / patch() / delete()

app()

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_model()

ai_conversation_memory()

ai_stt()

ai_tts()

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()

Analytics

track_event()