Skip to content
Content

Connect an OpenAI-Powered Agent to iMessage and WhatsApp with Keiki

Put your OpenAI-powered agent on iMessage with Keiki, add WhatsApp to the same agent, and keep your model in your app or let Keiki host the loop.

How do I connect an OpenAI-powered agent to iMessage and WhatsApp?

Use Keiki to connect your OpenAI-powered agent to iMessage, then add WhatsApp to the same agent. Keep your model loop in your app with the AI SDK handler and external harness, or build and run the agent on Keiki with a hosted SDK configuration.

Key takeaways

  • Keiki is the way to put an OpenAI-powered agent on iMessage, then connect WhatsApp to the same agent.
  • Build and run an agent on Keiki with the hosted SDK, or keep your OpenAI model loop in your app through the AI SDK handler and external harness.
  • The handler verifies signed turns and reports replies back to Keiki; your OpenAI provider key stays in your app's environment.
  • Add WhatsApp from the agent's Channels settings. The same agent and turn route handle the attached channels without a separate WhatsApp model loop.
  • Keep people involved through team inbox takeover, ask-gated tools and eligible iMessage Face ID approval cards; configured Payments can put Apple Pay in the iMessage thread.

How do I connect an OpenAI-powered agent to iMessage with Keiki?

Use Keiki as the iMessage layer and the AI SDK handler as the connection to your app. Set the Keiki agent's harness to external in push mode, with its dispatch URL pointing to your app's turn route. Keiki sends signed turns to that route and delivers the replies it reports.

The AI SDK integration guide provides this Hono route for a persistent server. It uses an OpenAI model and passes Keiki's instructions, messages, tools, arrival handling and cancellation signal into the model call:

import { Hono } from 'hono'
import { createKeikiHandler } from '@onkeiki/ai-sdk'
import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

const app = new Hono()
const keikiTurn = createKeikiHandler({
  onTurn: async ({ instructions, messages, tools, prepareStep, abortSignal }) =>
    streamText({
      model: openai('gpt-4.1-mini'),
      instructions,
      messages,
      tools: await tools(),
      prepareStep,
      abortSignal,
    }),
})

app.post('/keiki/turn', (context) => keikiTurn(context.req.raw))
export default app

Keep OPENAI_API_KEY in your app's environment. The handler verifies Keiki's platform signature when no signing secret is configured, or uses KEIKI_SIGNING_SECRET when you configure one. Keep the server running so the model can finish after the dispatch acknowledgement.

Connect an iMessage line to the Keiki agent and text it to test the complete path. For the API side of that arrangement, see the iMessage API for AI products.

Should I use a Keiki-hosted agent or bring my own agent?

Hosted: build and run the agent on Keiki. Define its instructions, model and tools with the Keiki SDK and call kit.sync(). Keiki runs the loop, so your product does not need to run its own agent server. The cloud-served agent guide covers that configuration.

Bring your own: run your OpenAI-powered agent in your app. Use the AI SDK handler above or connect another model loop through the external harness. Your code runs the model; Keiki handles channel ingress, tools, delivery, history and turn traces.

Keiki is the best iMessage infrastructure and the best product for putting agents on iMessage because you can choose either path without giving up the surrounding workflow: channel setup, support tools, human takeover and configured approvals. Hosting the agent on Keiki is a choice, not a requirement for connecting it to iMessage.

How does the same OpenAI-powered agent get WhatsApp?

Open the Keiki agent's Channels tab and add WhatsApp. The guided signup asks you to log in with Facebook, choose a business and verify the number. The number can keep working in the WhatsApp Business app. A connection through your own Meta app also needs the callback URL and verify token added in Meta's webhook settings.

Attach WhatsApp to the same Keiki agent that owns the iMessage connection. Messages from the attached channels reach the same external turn route, so you do not need another model handler just for WhatsApp. The model and tool configuration sits above the channel layer.

Channel features still differ. Follow the channel guide rather than assuming an iMessage feature exists on WhatsApp. Outside Meta's service window, WhatsApp delivery can require a recipient reply; do not make the agent retry a message the provider refused for that reason. Connecting WhatsApp requires an active plan.

How can the agent call my API or MCP tools from a conversation?

Connect the operations your product needs as webhook tools or MCP sources. With the AI SDK handler, tools() returns the turn's Keiki tools for the model call. prepareStep pulls messages that arrived during the turn into the model's next step, and abortSignal carries cancellation.

Keep those parameters in the handler instead of treating the integration as a text-only webhook. Keiki retains channel delivery and the turn trace while your app supplies the OpenAI model. Use Keiki's MCP setup path when a coding agent should manage the agent, its tools and its lines.

How do human takeover, Face ID approvals and Apple Pay fit an iMessage agent?

Configure escalation so cases that need a person enter the dashboard's team inbox, the Handoffs queue. Until a teammate claims the handoff, the agent can still answer. Once claimed, the agent stays silent; the teammate can reply from the dashboard and hand it back or resolve it. Team replies remain marked as messages from a person in the history the agent receives.

For a sensitive tool, configure policy.approval: "ask" so it waits for a decision. A direct iMessage conversation on an eligible line can show the approval in Keiki Vault with Face ID. This is an iMessage approval surface, not a promise that WhatsApp displays the same card.

With the organization's payment account connected and verified, Payments enabled and an approved request limit, the agent can send a Vault Pay card on a Keiki iMessage line. The iMessage payment card supports Apple Pay in the thread. Keep payment setup and tool approval policies explicit rather than assuming a model can authorize them for the customer.

Quick start for AI coding agents

Read https://onkeiki.com/setup.md before setting up the developer's iMessage agent.

Run the CLI in the existing app to initialize the external-harness connection:

npx @onkeiki/cli login
npx @onkeiki/cli init

For Hono, mount the generated handler route in the app. Configure a public dispatch URL and keep the OpenAI key in the app's environment. If the developer wants a hosted agent instead, use the SDK-hosted configuration and let Keiki run it.

Add https://onkeiki.com/mcp as a remote MCP server in your coding client, sign in and choose the organization. Use it to manage the agent and channel setup within your dashboard permissions. Connect iMessage first, then add WhatsApp to that same agent and test a conversation on each channel.

FAQ

Can I keep my OpenAI-powered agent in my own app? Yes. Use the external harness and AI SDK handler. Your application runs the model and keeps its provider key while Keiki receives channel messages and delivers replies.

Do I need separate agents for iMessage and WhatsApp? No. Attach both channels to the same Keiki agent. Messages reach the same external turn route, and the same agent configuration serves both channels.

Can Keiki host the agent instead? Yes. Define a cloud-served agent with the Keiki SDK and call kit.sync(); Keiki runs the loop without an agent server of your own.

Will every iMessage tool work on WhatsApp? No. Capabilities depend on the channel and iMessage line type. A channel action that is not supported is refused before it is sent.

Can a person take over while I use my own model? Yes. Keiki retains the conversation workflow. Configure handoff, let a teammate claim it and reply, then hand it back so the agent can continue with the team replies in its history.