Omnix
Home AI Agent Handoff

External Integration: Remote AI Agent Relay & Handoff

If you use an external AI agent or natural language engine to power your customer conversations, you can use the Omnix Gateway to receive user messages, relay AI responses, and manage the transition back to human agents when required.

This guide details the integration flow for remote AI bots using sendRemoteAgentResponse and the handoff state machine.

Architecture Overview

 [ End User ] <---> [ Omnix Unified Inbox ] <---> [ Webhook Relay ] <---> [ Your AI Engine ]
                           |
                     (Handoff Trigger)
                           |
                           v
                  [ Human Agent Pool ]

When a conversation is in the bot assignment state, Omnix forwards incoming messages to your configured webhook. Your AI parses the message and returns responses back via the Gateway API.

1. Relaying Bot Responses (sendRemoteAgentResponse)

When your AI engine determines the next message to send to the contact, invoke the sendRemoteAgentResponse method.

Request Example

{
  "method": "OmnixGatewayRpc.sendRemoteAgentResponse",
  "params": {
    "subscriptionId": "sub_123456",
    "conversationId": "conv_998877",
    "message": {
      "body": "I have found 3 flights matching your criteria. Would you like me to book the morning flight?"
    },
    "botMetadata": {
      "intent": "flight_search",
      "confidence": 0.98
    }
  }
}
  • botMetadata: This is logged internally on the conversation timeline. Human agents can view intent tags when auditing bot performance.

2. Managing Human Handoff

If the user asks to speak with a human, or if the AI engine's confidence falls below a certain threshold, the AI engine should trigger a human handoff.

To initiate a handoff, call sendRemoteAgentResponse but pass the action parameters to modify the conversation's state:

Handoff Request Example

{
  "method": "OmnixGatewayRpc.sendRemoteAgentResponse",
  "params": {
    "subscriptionId": "sub_123456",
    "conversationId": "conv_998877",
    "message": {
      "body": "Sure, let me connect you to a live support agent. One moment please..."
    },
    "action": {
      "type": "handoff_to_human",
      "targetQueue": "customer_support",
      "priority": "high"
    }
  }
}

What Happens Next?

  1. Inbox State Shift: Omnix marks the conversation as active (shifting it out of the bot section).
  2. Queueing: The conversation is placed into the specified targetQueue (e.g., customer_support).
  3. Webhook Silence: Future incoming user messages on this thread will no longer trigger your webhook relay until the human agent marks the thread as solved and transfers it back to the bot.

3. Webhook Event Shape (Inbound Message)

When a contact sends a message and a bot is active, your webhook receives an event payload:

{
  "event": "message.received",
  "subscriptionId": "sub_123456",
  "conversation": {
    "conversationId": "conv_998877",
    "channelType": "whatsapp"
  },
  "contact": {
    "contactId": "con_789012"
  },
  "message": {
    "messageId": "msg_000111",
    "body": "I need help with my billing invoice"
  }
}

Your system must respond with a 200 OK immediately, then process the reply asynchronously via sendRemoteAgentResponse.