Native Actions

Native Actions allow sending advanced WhatsApp messages during the conversation: interactive buttons, lists, images, synthesized audio, files, and more.

Subtype Overview

`SEND_TEXT`: Simple Text

Sends a text message. Supports variables with $:

{
  "type": "NATIVE",
  "subtype": "SEND_TEXT",
  "text": "Hello $customer_name! Your order #$order_number has been confirmed."
}

When to use: When you need to send text with dynamic formatting outside the natural LLM response flow.

`SEND_BUTTON`: Interactive Buttons

Sends a message with quick-reply buttons (max 3 buttons on WhatsApp):

{
  "type": "NATIVE",
  "subtype": "SEND_BUTTON",
  "text": "How would you like to proceed?",
  "buttons": ["Talk to a human", "View plans", "End"]
}

Button modes

With AI_BUTTONS, you define the quantity and the LLM creates the most appropriate texts for the moment of the conversation.

`SEND_LIST`: Option List

Sends an expanded list of items (more than 3 options, or items with description):

{
  "type": "NATIVE",
  "subtype": "SEND_LIST",
  "text": "Choose the type of service:",
  "items": [
    { "title": "Technical Support", "description": "Product issues" },
    { "title": "Finance", "description": "Invoices and payments" },
    { "title": "Sales", "description": "New contracts and upgrades" },
    { "title": "Cancellation", "description": "Cancel subscription" }
  ]
}

List modes

`SEND_IMAGE`: Image

Sends an image from a public URL:

{
  "type": "NATIVE",
  "subtype": "SEND_IMAGE",
  "url": "https://cdn.company.com/products/$product_id/photo.jpg",
  "caption": "Product: $product_name: $price"
}

The URL and caption support $ variable substitution.

`SEND_AUDIO`: Audio

Sends a pre-recorded audio file (MP3, OGG, etc. format):

{
  "type": "NATIVE",
  "subtype": "SEND_AUDIO",
  "url": "https://cdn.company.com/audios/welcome.ogg"
}

`SEND_FILE`: File/Document

Sends a document to the user (PDF, DOCX, XLSX, etc.):

{
  "type": "NATIVE",
  "subtype": "SEND_FILE",
  "url": "https://cdn.company.com/docs/proposal_$company_id.pdf",
  "filename": "Commercial_Proposal_$company_name.pdf"
}

Both the URL and filename support $ variables.

`GEN_AUDIO`: Text-to-Speech (TTS)

Generates and sends an audio message from text using Text-to-Speech:

{
  "type": "NATIVE",
  "subtype": "GEN_AUDIO",
  "text": "Hello $customer_name, your appointment has been confirmed for $appointment_date at $appointment_time. See you then!"
}

The text supports $ variables. The audio is generated in real time and sent as a voice message.

When to use:

• Important confirmations that deserve audio emphasis
• Users who prefer listening over reading
• Accessibility

`TRANSFER_ASSISTANT`: Transfer to Another Assistant

Transfers the user's session to a different assistant, preserving the conversation history:

{
  "type": "NATIVE",
  "subtype": "TRANSFER_ASSISTANT",
  "assistantId": 42
}

Use cases:

• Transfer from the triage assistant to the sales specialist
• Escalate to the advanced technical support assistant
• Language routing (EN → PT)
• Human handoff via copilot assistant

The assistantId is the numeric ID of the destination assistant, found in Settings → Assistants.

Variable Interpolation in Native Actions

In text fields of Native Actions (text, caption, filename), use $ to insert variables:

"text": "Hello $name! Your balance is $balance. Last updated: $update_date"

Values come from:

1. Trigger parameters (function calling args)
2. ClientData (data sent via API)
3. System variables ($session.id, $company.id, $assistant.id)