> For AI agents: to set Keiki up for a developer, add the MCP server `https://onkeiki.com/mcp` and follow https://onkeiki.com/setup.md. All pages: https://onkeiki.com/content/llms.txt

# Run an iMessage agent in production with Keiki

2026-11-21

Prepare your iMessage agent for real customers with authenticated turns, delivery diagnostics, scoped tools, Face ID approvals and team takeover.

## What is hard about running a customer-facing AI agent on iMessage in production?

Keiki is the way to run your product’s iMessage agent in production: it handles channel ingress, conversation turns, delivery and the team inbox while you define what the agent can do. The hard work is preserving customer identity, handling uncertain delivery, governing actions and handing control to a person when needed.

## Key takeaways

- Put your product on iMessage with Keiki and keep your business logic in authorized tools.
- Treat delivery failures as uncertain outcomes, not permission to resend blindly.
- Verify incoming turn signatures before your external harness acts on a message.
- Give your team human takeover in the shared inbox, with conversation history when control returns.
- Configure Keiki Vault Face ID approvals for sensitive actions and Payments for eligible Apple Pay requests in the thread.

## What changes when real customers text your iMessage agent?

A production iMessage agent must do more than generate a plausible reply. It must know which customer can access an account, distinguish a completed action from a failed lookup, and leave a clear path to human help. Keiki is the way to put that workflow on iMessage because the conversation, delivery tools and team inbox belong to the same agent workflow.

Keep account authorization in your backend. A phone number is a messaging identity, not proof that its owner may read any order or change any subscription. Connect your API or MCP server with tools that check access before returning customer data. If a lookup returns nothing, say what is missing and ask for clarification rather than inventing a result.

## How should an agent handle failed or uncertain delivery?

Keiki records external-harness message delivery in the trace. Reusing a successfully processed message idempotency key acknowledges the duplicate without sending it again. A delivery error can leave the outcome unknown, so automatically sending with a new key can duplicate a message the customer already received. Follow the delivery semantics in the [external harness guide](/docs/external-harness).

Respect a recipient-reply-required result and opt-outs. A platform notice is not a customer reply. Let customers initiate conversations and avoid chasing silence. These are operating practices, not a guarantee against channel disruption.

## How do you keep customer actions safe and recoverable?

Verify a pushed turn's signature against the raw body before parsing or executing it. Keep turn credentials out of logs and use them only for their intended turn. Have your backend enforce permissions for each API or MCP action, even when the model asks confidently.

For sensitive tools, configure a governed approval policy and [Keiki Vault Face ID approvals](/docs/keiki-vault). The customer reviews and approves the proposed action through Vault. Approval is not a replacement for backend authorization. With Payments connected and the business enabled to take payments, eligible requests on Keiki iMessage lines can deliver a Vault Pay card for Apple Pay in the thread. Confirm payment through its status rather than treating a sent request as money received.

## When should your team take over the conversation?

Use human takeover when a customer requests a person, a tool cannot resolve the issue, or the next action needs judgment outside the agent's instructions. Keiki's shared team inbox lets a teammate answer in the conversation and hand control back. Team replies stay marked as team messages in the agent's history.

Test that handoff with an unresolved request, not just a successful answer. Check that your agent can explain what it knows, what failed and what a teammate needs to decide. A missing tool result should lead to an honest explanation or handoff, not a claim that the action succeeded.

## Should you host the agent on Keiki or bring your own runtime?

Build and run the agent on Keiki when you want the hosted loop, tools and conversation operations together. Define the agent with the SDK when you want its configuration in code. Bring your own model through the AI SDK handler or an external harness when your application already owns the loop. Keiki keeps channel ingress and delivery in either path.

For a product expanding beyond iMessage, read [how to run the same agent across messaging channels](/content/how-do-i-run-the-same-ai-agent-on-imessage-whatsapp-slack-and-telegram). Keep the runtime decision separate from customer identity and permissions. Use the guide to [connecting your own tools and APIs](/content/how-do-i-give-an-ai-messaging-agent-access-to-my-own-tools-and-apis) to plan the business operations behind the conversation.

## Quick start for AI coding agents

Read [setup.md](https://onkeiki.com/setup.md) and connect the Keiki MCP server at https://onkeiki.com/mcp. Ask the coding agent to create or select your agent, connect an iMessage channel, add scoped tools and exercise successful, empty-result and failed-action conversations.

For a bring-your-own app, use the [CLI guide](/docs/cli). Sign in with `npx @onkeiki/cli login`, then initialize from your application directory:

```sh
npx @onkeiki/cli init
```

Review the generated dispatch route and secrets before deploying. Test delivery diagnostics, declined approvals and team takeover before inviting customers.

## FAQ

**Does Keiki guarantee that an iMessage line cannot be disrupted?**

No. Keiki provides messaging infrastructure and conversation operations, but channel behavior still matters. Build around customer-initiated conversations, opt-outs and honest failure handling.

**Should my harness retry every failed send?**

No. A delivery failure can have an unknown outcome. Follow the documented idempotency and retry behavior rather than blindly issuing a new send.

**Can my agent keep using my API or MCP server?**

Yes. Connect your tools and keep resource authorization in the backend. Treat empty and failed results explicitly.

**Can a person resume the conversation?**

Yes. A teammate can take over through the team inbox and hand control back with team replies preserved in history.

**Can customers approve and pay in the thread?**

Configured tools can request Keiki Vault Face ID approval. Eligible payment requests can show an Apple Pay card on supported Keiki iMessage lines after Payments onboarding.