Can I use WhatsApp Business as a CLI?

Yes. KosmoKrator exposes a WhatsApp Business CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose WhatsApp Business through MCP?

Yes. The KosmoKrator MCP gateway can expose selected WhatsApp Business tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are WhatsApp Business credentials stored?

WhatsApp Business credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for WhatsApp Business MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

WhatsApp Business Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the WhatsApp Business KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.whatsapp.*. Use lua_read_doc("integrations.whatsapp") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic WhatsApp Business workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.whatsapp.send_text_message({to = "example_to", body = "example_body", preview_url = true}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("whatsapp"))' --json
kosmo integrations:lua --eval 'print(docs.read("whatsapp.send_text_message"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local whatsapp = app.integrations.whatsapp
local result = whatsapp.send_text_message({to = "example_to", body = "example_body", preview_url = true})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.whatsapp, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.whatsapp.default.* or app.integrations.whatsapp.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need WhatsApp Business, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

WhatsApp Business Lua API Reference

Namespace: app.integrations.whatsapp

This package wraps the WhatsApp Business Platform Graph API. Configure an access_token for all calls, a phone_number_id for message/media/profile operations, and a whatsapp_business_account_id for template, phone-number listing, and webhook subscription operations.

Messages

send_message

Send a text message within an active customer-service window.

local result = app.integrations.whatsapp.send_message({
  to = "15551234567",
  body = "Your order has shipped.",
  preview_url = false
})

print(result.messages[1].id)

send_template

Send a pre-approved template message, usually used to start a conversation.

local result = app.integrations.whatsapp.send_template({
  to = "15551234567",
  template_name = "hello_world",
  language = "en_US"
})

send_message_payload

Send any official Cloud API message payload. Use this for media, location, contacts, reaction, interactive, catalog, or future message types.

local result = app.integrations.whatsapp.send_message_payload({
  payload = {
    to = "15551234567",
    type = "image",
    image = { link = "https://example.test/image.jpg" }
  }
})

mark_message_read

app.integrations.whatsapp.mark_message_read({
  message_id = "wamid.HBgM..."
})

get_message

Retrieves a message or Graph object by ID. Meta may return limited fields for message IDs; webhook payloads are still the primary source for message content and delivery statuses.

local message = app.integrations.whatsapp.get_message({
  message_id = "wamid.HBgM...",
  fields = "id"
})

Contacts

check_contacts

Validate phone numbers through the official /{phone-number-id}/contacts endpoint. The legacy list_contacts slug is kept as an alias for this validation behavior because Cloud API does not expose a contact listing edge.

local result = app.integrations.whatsapp.check_contacts({
  contacts = { "15551234567", "15557654321" }
})

Media

upload_media

Upload a readable local file and receive a WhatsApp media ID.

local media = app.integrations.whatsapp.upload_media({
  file_path = "/tmp/invoice.pdf",
  mime_type = "application/pdf"
})

get_media

Get media metadata and a temporary download URL.

local media = app.integrations.whatsapp.get_media({
  media_id = "1234567890"
})

delete_media

app.integrations.whatsapp.delete_media({ media_id = "1234567890" })

Message Templates

Template tools use the configured whatsapp_business_account_id, not the phone number ID.

list_templates

local page = app.integrations.whatsapp.list_templates({
  limit = 50,
  status = "APPROVED"
})

for _, template in ipairs(page.data or {}) do
  print(template.name .. " " .. template.status)
end

get_template

local template = app.integrations.whatsapp.get_template({
  template_id = "1234567890"
})

create_template

local created = app.integrations.whatsapp.create_template({
  template = {
    name = "order_update",
    language = "en_US",
    category = "UTILITY",
    components = {
      { type = "BODY", text = "Order {{1}} is {{2}}." }
    }
  }
})

update_template

app.integrations.whatsapp.update_template({
  template_id = "1234567890",
  template = {
    components = {
      { type = "BODY", text = "Order {{1}} status: {{2}}." }
    }
  }
})

delete_template

app.integrations.whatsapp.delete_template({
  name = "order_update",
  template_id = "1234567890"
})

Phone Numbers

local numbers = app.integrations.whatsapp.list_phone_numbers({ limit = 25 })

local number = app.integrations.whatsapp.get_phone_number({
  phone_number_id = "1234567890"
})

Registration helpers map to Meta’s phone-number lifecycle endpoints: request_verification_code, verify_code, register_phone_number, and deregister_phone_number.

app.integrations.whatsapp.request_verification_code({
  code_method = "SMS",
  language = "en"
})

Business Profile

local profile = app.integrations.whatsapp.get_business_profile({})

app.integrations.whatsapp.update_business_profile({
  profile = {
    about = "Support and order updates",
    email = "support@example.test",
    websites = { "https://example.test" },
    vertical = "ECOMMERCE"
  }
})

Webhook Subscriptions

app.integrations.whatsapp.subscribe_app({})
local apps = app.integrations.whatsapp.list_subscribed_apps({})
app.integrations.whatsapp.unsubscribe_app({})

Raw Graph API Helpers

Use these only for WhatsApp Graph API endpoints that are not yet modeled as first-class tools. Paths must be relative; full URLs and parent-directory segments are rejected.

local me = app.integrations.whatsapp.api_get({
  path = "/me",
  params = { fields = "id,name" }
})

local response = app.integrations.whatsapp.api_post({
  path = "/1234567890/subscribed_apps",
  payload = {}
})

Multi-Account Usage

app.integrations.whatsapp.send_message({ to = "15551234567", body = "Hello" })
app.integrations.whatsapp.support.send_template({
  to = "15551234567",
  template_name = "hello_world",
  language = "en_US"
})

Raw agent markdown

# WhatsApp Business Lua API Reference

Namespace: `app.integrations.whatsapp`

This package wraps the WhatsApp Business Platform Graph API. Configure an
`access_token` for all calls, a `phone_number_id` for message/media/profile
operations, and a `whatsapp_business_account_id` for template, phone-number
listing, and webhook subscription operations.

## Messages

### send_message

Send a text message within an active customer-service window.

```lua
local result = app.integrations.whatsapp.send_message({
  to = "15551234567",
  body = "Your order has shipped.",
  preview_url = false
})

print(result.messages[1].id)
```

### send_template

Send a pre-approved template message, usually used to start a conversation.

```lua
local result = app.integrations.whatsapp.send_template({
  to = "15551234567",
  template_name = "hello_world",
  language = "en_US"
})
```

### send_message_payload

Send any official Cloud API message payload. Use this for media, location,
contacts, reaction, interactive, catalog, or future message types.

```lua
local result = app.integrations.whatsapp.send_message_payload({
  payload = {
    to = "15551234567",
    type = "image",
    image = { link = "https://example.test/image.jpg" }
  }
})
```

### mark_message_read

```lua
app.integrations.whatsapp.mark_message_read({
  message_id = "wamid.HBgM..."
})
```

### get_message

Retrieves a message or Graph object by ID. Meta may return limited fields for
message IDs; webhook payloads are still the primary source for message content
and delivery statuses.

```lua
local message = app.integrations.whatsapp.get_message({
  message_id = "wamid.HBgM...",
  fields = "id"
})
```

## Contacts

### check_contacts

Validate phone numbers through the official `/{phone-number-id}/contacts`
endpoint. The legacy `list_contacts` slug is kept as an alias for this
validation behavior because Cloud API does not expose a contact listing edge.

```lua
local result = app.integrations.whatsapp.check_contacts({
  contacts = { "15551234567", "15557654321" }
})
```

## Media

### upload_media

Upload a readable local file and receive a WhatsApp media ID.

```lua
local media = app.integrations.whatsapp.upload_media({
  file_path = "/tmp/invoice.pdf",
  mime_type = "application/pdf"
})
```

### get_media

Get media metadata and a temporary download URL.

```lua
local media = app.integrations.whatsapp.get_media({
  media_id = "1234567890"
})
```

### delete_media

```lua
app.integrations.whatsapp.delete_media({ media_id = "1234567890" })
```

## Message Templates

Template tools use the configured `whatsapp_business_account_id`, not the phone
number ID.

### list_templates

```lua
local page = app.integrations.whatsapp.list_templates({
  limit = 50,
  status = "APPROVED"
})

for _, template in ipairs(page.data or {}) do
  print(template.name .. " " .. template.status)
end
```

### get_template

```lua
local template = app.integrations.whatsapp.get_template({
  template_id = "1234567890"
})
```

### create_template

```lua
local created = app.integrations.whatsapp.create_template({
  template = {
    name = "order_update",
    language = "en_US",
    category = "UTILITY",
    components = {
      { type = "BODY", text = "Order {{1}} is {{2}}." }
    }
  }
})
```

### update_template

```lua
app.integrations.whatsapp.update_template({
  template_id = "1234567890",
  template = {
    components = {
      { type = "BODY", text = "Order {{1}} status: {{2}}." }
    }
  }
})
```

### delete_template

```lua
app.integrations.whatsapp.delete_template({
  name = "order_update",
  template_id = "1234567890"
})
```

## Phone Numbers

```lua
local numbers = app.integrations.whatsapp.list_phone_numbers({ limit = 25 })

local number = app.integrations.whatsapp.get_phone_number({
  phone_number_id = "1234567890"
})
```

Registration helpers map to Meta's phone-number lifecycle endpoints:
`request_verification_code`, `verify_code`, `register_phone_number`, and
`deregister_phone_number`.

```lua
app.integrations.whatsapp.request_verification_code({
  code_method = "SMS",
  language = "en"
})
```

## Business Profile

```lua
local profile = app.integrations.whatsapp.get_business_profile({})

app.integrations.whatsapp.update_business_profile({
  profile = {
    about = "Support and order updates",
    email = "support@example.test",
    websites = { "https://example.test" },
    vertical = "ECOMMERCE"
  }
})
```

## Webhook Subscriptions

```lua
app.integrations.whatsapp.subscribe_app({})
local apps = app.integrations.whatsapp.list_subscribed_apps({})
app.integrations.whatsapp.unsubscribe_app({})
```

## Raw Graph API Helpers

Use these only for WhatsApp Graph API endpoints that are not yet modeled as
first-class tools. Paths must be relative; full URLs and parent-directory
segments are rejected.

```lua
local me = app.integrations.whatsapp.api_get({
  path = "/me",
  params = { fields = "id,name" }
})

local response = app.integrations.whatsapp.api_post({
  path = "/1234567890/subscribed_apps",
  payload = {}
})
```

## Multi-Account Usage

```lua
app.integrations.whatsapp.send_message({ to = "15551234567", body = "Hello" })
app.integrations.whatsapp.support.send_template({
  to = "15551234567",
  template_name = "hello_world",
  language = "en_US"
})
```

Metadata-derived Lua example

local result = app.integrations.whatsapp.send_text_message({to = "example_to", body = "example_body", preview_url = true})
print(result)

Functions

send_text_message Write

Send a text message to a WhatsApp recipient. Use this for replying within an existing 24-hour customer service window. For new conversations, use the send_template tool instead.

Lua path: app.integrations.whatsapp.send_text_message
Full name: whatsapp.whatsapp_send_message

Parameter	Type	Required	Description
`to`	string	yes	Recipient phone number in international format without + (e.g. "15551234567").
`body`	string	yes	Text content of the message (max 4096 characters).
`preview_url`	boolean	no	Whether to render URLs as link previews in the message (default: false).

send_template_message Write

Send a template-based WhatsApp message. Use this to initiate new conversations outside the 24-hour window. The template must be pre-approved in the WhatsApp Business Manager.

Lua path: app.integrations.whatsapp.send_template_message
Full name: whatsapp.whatsapp_send_template

Parameter	Type	Required	Description
`to`	string	yes	Recipient phone number in international format without + (e.g. "15551234567").
`template_name`	string	yes	Name of the approved WhatsApp template (e.g. "hello_world").
`language`	string	no	Language code for the template (e.g. "en_US", "en"). Defaults to "en".
`components`	array	no	Template components as an array of objects with type and parameters. Pass as a JSON string or array.

send_message_payload Write

Send any official WhatsApp Cloud API message payload to the configured phone number.

Lua path: app.integrations.whatsapp.send_message_payload
Full name: whatsapp.whatsapp_send_message_payload

Parameter	Type	Required	Description
`payload`	object	yes	Cloud API message payload without messaging_product.

mark_message_read Write

Mark an inbound WhatsApp message as read using its message ID.

Lua path: app.integrations.whatsapp.mark_message_read
Full name: whatsapp.whatsapp_mark_message_read

Parameter	Type	Required	Description
`message_id`	string	yes	Inbound WhatsApp message ID.

get_message_object Read

Retrieve a specific WhatsApp message or Graph object by ID with optional fields.

Lua path: app.integrations.whatsapp.get_message_object
Full name: whatsapp.whatsapp_get_message

Parameter	Type	Required	Description
`message_id`	string	yes	The WhatsApp message ID or Graph object ID.
`fields`	string	no	Optional comma-separated Graph fields to request.

check_contacts Read

Validate one or more phone numbers through the WhatsApp Cloud API contacts endpoint.

Lua path: app.integrations.whatsapp.check_contacts
Full name: whatsapp.whatsapp_check_contacts

Parameter	Type	Required	Description
`contacts`	array	yes	Phone numbers in international format without +.

check_contacts_legacy Read

Validate WhatsApp contacts for the configured business phone number. Legacy slug for check_contacts.

Lua path: app.integrations.whatsapp.check_contacts_legacy
Full name: whatsapp.whatsapp_list_contacts

Parameter	Type	Required	Description
`contacts`	array	yes	Phone numbers in international format without +.

upload_media Write

Upload a local image, video, audio, sticker, or document file to WhatsApp media storage.

Lua path: app.integrations.whatsapp.upload_media
Full name: whatsapp.whatsapp_upload_media

Parameter	Type	Required	Description
`file_path`	string	yes	Readable local file path.
`mime_type`	string	yes	MIME type such as image/jpeg or application/pdf.

get_media Read

Get WhatsApp media metadata and the temporary download URL for a media ID.

Lua path: app.integrations.whatsapp.get_media
Full name: whatsapp.whatsapp_get_media

Parameter	Type	Required	Description
`media_id`	string	yes	WhatsApp media ID.

delete_media Write

Delete an uploaded WhatsApp media object by media ID.

Lua path: app.integrations.whatsapp.delete_media
Full name: whatsapp.whatsapp_delete_media

Parameter	Type	Required	Description
`media_id`	string	yes	WhatsApp media ID.

list_templates Read

List approved WhatsApp message templates. Templates are required to initiate new conversations outside the 24-hour service window.

Lua path: app.integrations.whatsapp.list_templates
Full name: whatsapp.whatsapp_list_templates

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of templates to return (default: 100).
`after`	string	no	Cursor for pagination.
`status`	string	no	Optional template status filter such as APPROVED, PENDING, or REJECTED.
`name`	string	no	Optional template name filter.

get_template Read

Get a WhatsApp message template by Graph template ID.

Lua path: app.integrations.whatsapp.get_template
Full name: whatsapp.whatsapp_get_template

Parameter	Type	Required	Description
`template_id`	string	yes	Message template Graph ID.

create_template Write

Create a WhatsApp message template on the configured WhatsApp Business Account.

Lua path: app.integrations.whatsapp.create_template
Full name: whatsapp.whatsapp_create_template

Parameter	Type	Required	Description
`template`	object	yes	Template creation payload with name, language, category, and components.

update_template Write

Update a WhatsApp message template by Graph template ID.

Lua path: app.integrations.whatsapp.update_template
Full name: whatsapp.whatsapp_update_template

Parameter	Type	Required	Description
`template_id`	string	yes	Message template Graph ID.
`template`	object	yes	Template update payload.

delete_template Write

Delete a WhatsApp message template by name and optional template ID.

Lua path: app.integrations.whatsapp.delete_template
Full name: whatsapp.whatsapp_delete_template

Parameter	Type	Required	Description
`name`	string	yes	Template name.
`template_id`	string	no	Optional template ID for a specific language variant.

get_phone_number Read

Get phone number metadata such as display number, verified name, quality rating, and throughput.

Lua path: app.integrations.whatsapp.get_phone_number
Full name: whatsapp.whatsapp_get_phone_number

Parameter	Type	Required	Description
`phone_number_id`	string	no	Optional phone number ID. Defaults to the configured phone number.

list_phone_numbers Read

List phone numbers attached to the configured WhatsApp Business Account.

Lua path: app.integrations.whatsapp.list_phone_numbers
Full name: whatsapp.whatsapp_list_phone_numbers

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of phone numbers to return.
`after`	string	no	Pagination cursor.

request_verification_code Write

Request a WhatsApp phone-number verification code by SMS or voice.

Lua path: app.integrations.whatsapp.request_verification_code
Full name: whatsapp.whatsapp_request_verification_code

Parameter	Type	Required	Description
`code_method`	string	yes	Delivery method.
`language`	string	no	Language code for the verification message. Defaults to en.
`phone_number_id`	string	no	Optional phone number ID. Defaults to configured phone number.

verify_code Write

Verify a WhatsApp phone-number registration code.

Lua path: app.integrations.whatsapp.verify_code
Full name: whatsapp.whatsapp_verify_code

Parameter	Type	Required	Description
`code`	string	yes	Verification code from Meta.
`phone_number_id`	string	no	Optional phone number ID. Defaults to configured phone number.

register_phone_number Write

Lua path: app.integrations.whatsapp.register_phone_number
Full name: whatsapp.whatsapp_register_phone_number

Parameter	Type	Required	Description
`pin`	string	yes	Two-step verification PIN.
`phone_number_id`	string	no	Optional phone number ID. Defaults to configured phone number.

deregister_phone_number Write

Deregister a WhatsApp phone number from Cloud API use.

Lua path: app.integrations.whatsapp.deregister_phone_number
Full name: whatsapp.whatsapp_deregister_phone_number

Parameter	Type	Required	Description
`phone_number_id`	string	no	Optional phone number ID. Defaults to configured phone number.

get_business_profile Read

Get the WhatsApp business profile for the configured phone number.

Lua path: app.integrations.whatsapp.get_business_profile
Full name: whatsapp.whatsapp_get_business_profile

Parameter	Type	Required	Description
`fields`	string	no	Comma-separated business profile fields.

update_business_profile Write

Update the WhatsApp business profile fields for the configured phone number.

Lua path: app.integrations.whatsapp.update_business_profile
Full name: whatsapp.whatsapp_update_business_profile

Parameter	Type	Required	Description
`profile`	object	yes	Business profile fields such as about, address, description, email, websites, vertical, and profile_picture_handle.

list_subscribed Read

List apps subscribed to the configured WhatsApp Business Account webhook events.

Lua path: app.integrations.whatsapp.list_subscribed
Full name: whatsapp.whatsapp_list_subscribed_apps

Parameter	Type	Required	Description
No parameters.

subscribe Write

Subscribe the configured app to WhatsApp Business Account webhook events.

Lua path: app.integrations.whatsapp.subscribe
Full name: whatsapp.whatsapp_subscribe_app

Parameter	Type	Required	Description
No parameters.

unsubscribe Write

Unsubscribe the configured app from WhatsApp Business Account webhook events.

Lua path: app.integrations.whatsapp.unsubscribe
Full name: whatsapp.whatsapp_unsubscribe_app

Parameter	Type	Required	Description
No parameters.

get_current_user Read

Get the authenticated WhatsApp Business user info - name, email, and business ID. Useful for verifying which account is connected.

Lua path: app.integrations.whatsapp.get_current_user
Full name: whatsapp.whatsapp_get_current_user

Parameter	Type	Required	Description
No parameters.

api_get Read

Call a safe relative Meta Graph API path with GET for WhatsApp endpoints not yet modeled as first-class tools.

Lua path: app.integrations.whatsapp.api_get
Full name: whatsapp.whatsapp_api_get

Parameter	Type	Required	Description
`path`	string	yes	Relative Graph API path, such as /me or /{waba_id}/message_templates.
`params`	object	no	Query parameters.

api_post Write

Call a safe relative Meta Graph API path with POST for WhatsApp endpoints not yet modeled as first-class tools.

Lua path: app.integrations.whatsapp.api_post
Full name: whatsapp.whatsapp_api_post

Parameter	Type	Required	Description
`path`	string	yes	Relative Graph API path.
`payload`	object	no	JSON request body.
`params`	object	no	Query parameters.

api_delete Write

Call a safe relative Meta Graph API path with DELETE for WhatsApp endpoints not yet modeled as first-class tools.

Lua path: app.integrations.whatsapp.api_delete
Full name: whatsapp.whatsapp_api_delete

Parameter	Type	Required	Description
`path`	string	yes	Relative Graph API path.
`params`	object	no	Query parameters.