Ak Add Integration

Add a Messaging Integration

Use this skill to add a messaging platform integration to your Agent Kernel project.

Instructions for the Agent

When the user wants to add a messaging integration, follow this workflow:

Step 1: Identify the Project

Check the user's current project for:

• An existing pyproject.toml with agentkernel dependency
• An agent definition file (e.g., app.py, server.py, demo.py)
• An existing config.yaml

If not found, suggest using the ak-init skill first.

Step 2: Ask Which Integration

Which messaging platform would you like to integrate?

1. Slack — Bot that responds in Slack channels and threads
2. WhatsApp — Bot via WhatsApp Business API (Meta)
3. Facebook Messenger — Bot via Messenger Platform (Meta)
4. Instagram — Bot via Instagram Messaging API (Meta)
5. Telegram — Bot via Telegram Bot API
6. Teams — Bot via Microsoft Teams (Azure Bot Framework)
7. Gmail — Email-based agent via Gmail API (polling)

Step 3: Generate Changes

The snippets below mount each integration with IOHandler.run(...), the local/containerized pipeline. If the project deploys on AWS Lambda (the ak-serverless Terraform module), host the same handler in the request-handler Lambda instead, and add the platform extra to both the request-handler and the response-handler packages (agentkernel[aws,<platform>], not the api extra):

# lambda_request_handler.py
from agentkernel.aws import Lambda, LambdaWebhookHost
from agentkernel.integration.adapter import WebhookRESTRequestHandler
from agentkernel.slack import SlackInboundAdapter  # or the platform's inbound adapter

slack = LambdaWebhookHost(WebhookRESTRequestHandler(SlackInboundAdapter()))


@Lambda.register("/slack/events", method="POST")  # the adapter's webhook_path
def slack_events(event, context):
    return slack.handle(event, context)


handler = Lambda.handler

• WhatsApp, Messenger and Instagram also register the handshake: Lambda.register("/<platform>/webhook", method="GET")(host.challenge).

• It needs queue_mode = true, execution_mode = "rest_sync" or "rest_async", execution.queues.type: sqs in config.yaml, and a response store (create_dynamodb_response_store = true).

• Declare the webhook route in Terraform: gateway_endpoints = [{ path = "/slack/events", method = "POST" }] (WhatsApp, Messenger and Instagram also need GET on their path for the handshake).

• Put the platform credentials in both request_handler.environment_variables and response_handler.environment_variables. WhatsApp, Messenger and Instagram need their app_secret and Telegram its webhook_secret: LambdaWebhookHost refuses to start without them.

• Behind an API Gateway authorizer, pass bypass=WebhookRouteMatcher.for_integrations("<platform>") to APIGatewayAuthorizer and set result_ttl_in_seconds = 0 (see the ak-cloud-deploy skill, AWS Serverless).

• Gmail (polling) is not supported on Lambda.

For Slack

1. Update pyproject.toml dependencies:

Add slack to the extras:

dependencies = [
    "agentkernel[openai,api,slack]>=0.9.5",
]

2. Update config.yaml:

slack:
  agent_acknowledgement: "I'm processing your request"
  # agent: general  # Optional: specify which agent handles Slack messages

3. Update the server file:

from agentkernel.integration.adapter import WebhookRESTRequestHandler
from agentkernel.pipeline import IOHandler
from agentkernel.slack import SlackInboundAdapter
# ... existing agent imports and definitions ...

if __name__ == "__main__":
    IOHandler.run(handlers=[WebhookRESTRequestHandler(SlackInboundAdapter())])

4. Environment variables needed:

export SLACK_BOT_TOKEN="xoxb-..."          # Bot User OAuth Token
export SLACK_SIGNING_SECRET="..."          # App signing secret

5. Setup instructions:

• Create a Slack App at https://api.slack.com/apps
• Enable Event Subscriptions → set Request URL to https://<your-domain>/slack/events
• Subscribe to bot events: message.channels, message.groups, message.im, message.mpim
• Install the app to your workspace
• Copy Bot Token and Signing Secret to environment variables

For WhatsApp

1. Update pyproject.toml:

dependencies = [
    "agentkernel[openai,api,whatsapp]>=0.9.5",
]

2. Update config.yaml:

whatsapp:
  verify_token: "your-verify-token"
  # agent: general
  # access_token and phone_number_id set via env vars

3. Update the server file:

from agentkernel.integration.adapter import WebhookRESTRequestHandler
from agentkernel.pipeline import IOHandler
from agentkernel.whatsapp import WhatsAppInboundAdapter
# ... existing agent imports and definitions ...

if __name__ == "__main__":
    IOHandler.run(handlers=[WebhookRESTRequestHandler(WhatsAppInboundAdapter())])

4. Environment variables:

export AK_WHATSAPP__ACCESS_TOKEN="..."         # WhatsApp Business API access token
export AK_WHATSAPP__PHONE_NUMBER_ID="..."      # Phone number ID from Meta
export AK_WHATSAPP__APP_SECRET="..."           # App secret for signature verification

5. Setup instructions:

• Create a Meta App at https://developers.facebook.com
• Set up WhatsApp Business API
• Configure webhook URL: https://<your-domain>/whatsapp/webhook
• Set verify token to match your config.yaml

For Facebook Messenger

1. Update pyproject.toml:

dependencies = [
    "agentkernel[openai,api,messenger]>=0.9.5",
]

2. Update config.yaml:

messenger:
  verify_token: "your-verify-token"
  # agent: general

3. Update the server file:

from agentkernel.integration.adapter import WebhookRESTRequestHandler
from agentkernel.pipeline import IOHandler
from agentkernel.messenger import MessengerInboundAdapter
# ... existing agent imports and definitions ...

if __name__ == "__main__":
    IOHandler.run(handlers=[WebhookRESTRequestHandler(MessengerInboundAdapter())])

4. Environment variables:

export AK_MESSENGER__ACCESS_TOKEN="..."
export AK_MESSENGER__APP_SECRET="..."

5. Setup instructions:

• Create a Meta App and add Messenger product
• Configure webhook: https://<your-domain>/messenger/webhook
• Subscribe to messages events