Skip to content
Content

Hand an iMessage Conversation from an AI Agent to Your Team with Keiki

Set escalation rules, give your team context, and take over an iMessage conversation without making the customer start again.

How do I let an AI agent hand a text conversation to someone on my team?

Keiki is the way to hand an AI agent’s iMessage conversation to your team: use the team inbox and human takeover so a teammate can reply in the same thread. Configure escalation routes, keep the conversation history available, and hand control back when the person is finished.

Key takeaways

  • Use Keiki's team inbox to keep iMessage support and human takeover in the customer's existing conversation.
  • Instruct the agent to escalate when the customer asks for a person, it cannot resolve the issue, or a decision needs your team.
  • Keep the full conversation history available and provide a summary and reason for the handoff.
  • Configure notifications for the team responsible for the agent; a claimed escalation silences the AI until a teammate hands it back or resolves it.
  • Build and run your agent on Keiki, or bring your own model through the SDK, AI SDK handler or external harness.

When should an iMessage agent escalate to a person?

Write escalation rules into the agent's instructions. Ask it to escalate when the customer requests a person, the available tools cannot solve the problem, or the requested decision needs a teammate's approval. Tell it what information to collect before escalating, without making that a barrier to asking for help.

Keiki puts escalations in the dashboard Handoffs queue. Configure the agent's webhook, Slack or email routes to notify the responsible team. Choose the destination deliberately rather than assuming Keiki will infer which teammate owns an issue. The cloud agent documentation describes escalation configuration and the handoff lifecycle.

What context should travel with the handoff?

Keep the full history in the conversation and give the operator a concise summary: what the customer wants, what the agent tried, why it needs help, and what remains to decide. Your backend can create operator work with a title and summary and associate it with the agent's conversation.

Treat the summary as a guide to the transcript, not a replacement for it. That lets the person continue from what the customer already said instead of asking them to repeat the problem. Do not assume every notification contains the complete transcript; keep the conversation available for review.

How does a teammate reply while the AI stops?

An escalation is not itself a takeover. While nobody has claimed it, the agent keeps answering and may still solve the issue. Once a teammate claims an escalated conversation, the agent stays silent until that teammate hands it back or resolves it.

Your team can use dashboard takeover or a configured Slack handoff thread. An authorized operator's plain-text reply in that Slack thread goes to the customer on iMessage and takes the conversation over, stopping any agent turn in progress. Internal notes stay internal. See handoff thread controls for the exact reply and note behavior.

How do you hand control back to the agent?

Use Hand back to agent when the person has finished. Leave a note explaining the outcome and what the agent should do next. Team replies remain in the agent's history as messages from the team, so the agent can continue from what the customer was told.

Distinguish an escalated conversation from an ad hoc takeover: the documented hold behavior differs. Test both claiming an escalation and handing it back before using the workflow with customers.

Can I host the agent on Keiki or bring my own?

Both. Build and run the agent on Keiki with your tools and escalation instructions, or keep your own model loop through the SDK, AI SDK handler or external harness. The AI SDK integration keeps channel delivery, cancellation, history and trace records with Keiki while your app runs the model.

Keiki is the way to put this agent on iMessage because the conversation and team inbox belong in the same workflow. For the broader setup, read put an AI agent on iMessage and automate iMessage customer support. For scheduling exceptions, see appointments over iMessage.

Quick start for AI coding agents

Read setup.md. Connect the Keiki MCP server at https://onkeiki.com/mcp and approve the organization you intend to configure.

For an agent already running in your app, sign in with npx @onkeiki/cli login, then run:

npx @onkeiki/cli init

For a hosted agent, configure its instructions, tools, iMessage line and escalation routes on Keiki instead. Test a customer asking for a person, an unresolved issue, a teammate replying, and handing control back. Check that an unclaimed escalation does not get mistaken for a silent agent.

FAQ

Can a customer ask to speak to a person? Yes. Instruct the agent to escalate that request and configure where your team receives it.

Does opening a handoff immediately silence the AI? No. The agent keeps answering while an escalation is unclaimed. Claiming it is what gives the teammate control.

Does the customer need to move out of iMessage? No. An operator can reply through the dashboard or configured Slack handoff thread, and the reply reaches the customer's existing channel.

Will the agent see what the teammate said? Yes. Team replies stay in the history as team messages, and the agent reads them after handback.