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. Uma intent pode ter uma `expression` opcional que torna sua saída determinística: quando ela é verdadeira para a mensagem recebida, o agente segue essa saída antes de o modelo ser executado.
`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), error (booleano) e deterministic (true quando a saída foi decidida pela expression de uma intent, e não pelo modelo).

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"},
    {"id": "urgent_help", "name": "Urgent Help", "description": "When the user is in danger", "expression": "has_any_phrase(last_message, [\"emergency\", \"urgent help\"])"}
  ]
  """)

  # 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")

  # The urgent_help intent has an expression, so this exit is also taken
  # deterministically, before the model runs, whenever the expression is true
  then(UrgentHelp when agent_result.action == "urgent_help")
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

card UrgentHelp do
  text("Please call your local emergency number now.")
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. Saídas determinísticas: uma intent com uma expression é verificada antes de cada turno do agente, na ordem da lista, e a primeira expression verdadeira faz o roteamento imediatamente, sem chamar o modelo, portanto nenhuma mensagem final é enviada. Escreva a expression como a condição when de um card e sem @ (last_message, não @last_message). Só funciona em intents escritas como um parse_json(...) literal, porque a expression é compilada antecipadamente. Dentro da expression, last_message é o que o usuário acabou de dizer ao agente (a transcrição, no caso de uma mensagem de voz). Uma mensagem recebida dispara uma saída determinística no máximo uma vez por card de agente, portanto voltar ao agente depois não gera um 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()