WhatsApp - Idun Engine

Connect your Idun agent to WhatsApp so users can interact with it through messages.

Prerequisites

A running Idun agent (engine)
A Meta Business account
A WhatsApp Business API app set up in the Meta Developer Portal
Your engine must be publicly reachable (use ngrok for local development)

Setup

Admin UI
Config file

Open the integrations admin page

Navigate to /admin/integrations/ in the running standalone. The channel catalog shows WhatsApp, Discord, Google Chat, Slack, and Microsoft Teams as active channels.

Create the WhatsApp integration

Click WhatsApp and fill in the access token, phone number ID, and verify token.

Field	Value
`access_token`	Meta Graph API permanent access token
`phone_number_id`	WhatsApp Business phone number ID
`verify_token`	Webhook verification token (must match what you set in the Meta App Dashboard)

Save

Save the form. The reload pipeline registers the WhatsApp webhook handler on the running engine.

Create a Meta app

Go to the Meta Developer Portal
Click Create App > select Business type
Fill in the app name and select your Business account
On the app dashboard, add the WhatsApp product

Get your credentials

Go to WhatsApp > API Setup
Copy the following values:
- Phone Number ID: The ID of the phone number you send from
- Permanent Access Token: Generate one under System Users in your Meta Business settings (or use the temporary token for testing)
Choose a Verify Token: Any secret string you will use to verify the webhook

Configure the integration

Add the WhatsApp integration to your engine config:

config.yaml

integrations:
  - provider: "WHATSAPP"
    enabled: true
    config:
      access_token: "EAAxxxxxxx..."
      phone_number_id: "123456789012345"
      verify_token: "my-webhook-verify-secret"
      api_version: "v21.0"

Field	Description
`access_token`	Meta Graph API permanent access token
`phone_number_id`	WhatsApp Business phone number ID from step 2
`verify_token`	Webhook verification token (must match what you configure in the Meta App Dashboard)
`api_version`	(Optional) Meta Graph API version, defaults to `v21.0`

Set up the webhook

Make sure your engine is running and publicly reachable
In the Meta Developer Portal, go to WhatsApp > Configuration
Under Webhook, click Edit and set:
- Callback URL: https://<your-domain>/integrations/whatsapp/webhook
- Verify Token: The same verify_token from your config
Click Verify and Save (Meta sends a GET request to verify the endpoint)
Subscribe to the messages webhook field

Test it

Open WhatsApp on your phone
Send a message to the WhatsApp Business number
Your agent processes the message and replies directly in the chat

With a test phone number, you can only send messages to numbers registered in the Meta Developer Portal under WhatsApp > API Setup > Test Numbers.

How it works

User sends a message to the WhatsApp Business number
Meta POSTs the webhook payload to your engine
Engine verifies the payload structure
Engine invokes the agent with the message text
Engine sends the agent’s reply back via the Meta Graph API

Session tracking: The sender’s phone number is used as the session ID, so conversation context is maintained per user. Webhook verification: On setup, Meta sends a GET request with a challenge token. The engine verifies it against your verify_token and responds automatically.

Next steps

Slack

Connect your agent to Slack DMs and channels.

Discord

Reach the same agent through Discord slash commands.

Production hardening

Secure the engine before exposing webhooks to the public internet.

Documentation Index

​Prerequisites

​Setup

​How it works

​Next steps

Slack

Discord

Production hardening

Prerequisites

Setup

How it works

Next steps