Omnix
Home OmnixGatewayRpc

OmnixGatewayRpc

OmnixGatewayRpc exposes a JSON-RPC gateway for contact lookup/creation, OTP delivery and verification, message delivery, remote agent event relaying, and telephony-related operations such as extension assignment, SIP credential retrieval, call control, and call status lookup. The class delegates most business logic to OmnixGatewayService and TelephonyConnectorService, while one method (sendRemoteAgentResponse) emits a local application event directly.

Endpoints

POST /api/rpc (Method: OmnixGatewayRpc.ping)

  • Description: A simple endpoint to test API key validity and connectivity.

  • Request Body:

    {
  "method": "OmnixGatewayRpc.ping",
  "params": {
    "echo": "optional string"
  }
}

  • Parameters:

    Name Type Required Description
    echo String No An optional string to echo back.

  • Response:

    {
  "success": true,
  "message": "Pong!",
  "echo": null,
  "subscriptionId": "string",
  "userId": "string"
}

  • Example (cURL):

    curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "OmnixGatewayRpc.ping",
    "params": {
      "echo": "hello"
    }
  }'

POST /api/rpc (Method: OmnixGatewayRpc.findOrCreateContact)

  • Description: Finds a contact by their details or creates a new one if not found.

  • Request Body:

    {
  "method": "OmnixGatewayRpc.findOrCreateContact",
  "params": {
    "contactInfo": {
      "contactId": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "[email protected]",
      "sms": "+15551234567",
      "voice": "+15551234567",
      "whatsapp": "+15551234567",
      "context": {}
    }
  }
}

  • Parameters:

    Name Type Required Description
    contactInfo Object Yes Information to identify or create a contact. Provide at least one identifier (contactId, email, sms, etc.).

  • Response:

    {
  "success": true,
  "data": {}
}

    The exact contact shape is returned by OmnixGatewayService._findOrCreateContact(...) and is not defined in this file.

  • Example (cURL):

    curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "OmnixGatewayRpc.findOrCreateContact",
    "params": {
      "contactInfo": {
        "email": "[email protected]",
        "firstName": "Ada",
        "lastName": "Lovelace"
      }
    }
  }'

POST /api/rpc (Method: OmnixGatewayRpc.requestOtp)

  • Description: Requests an OTP to be sent to a contact via specified channels.

  • Request Body:

    {
  "method": "OmnixGatewayRpc.requestOtp",
  "params": {
    "contactInfo": {
      "contactId": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "[email protected]",
      "sms": "+15551234567",
      "voice": "+15551234567",
      "whatsapp": "+15551234567",
      "context": {}
    },
    "channels": ["sms"],
    "templates": {
      "sms": "Your code is {{code}}"
    },
    "expiresInSeconds": 300
  }
}

  • Parameters:

    Name Type Required Description
    contactInfo Object Yes Information to identify or create a contact. Provide at least one identifier (contactId, email, sms, etc.).
    channels Array<"sms" | "email" | "whatsapp"> Yes At least one channel must be provided.
    templates Record<string, String> No Optional message templates for each channel, e.g. { sms: 'Your code is {{code}}' }.
    expiresInSeconds Number No Positive integer expiration window in seconds.

  • Response:

    {
  "success": true,
  "otpRequestId": "string"
}

    The method returns whatever OmnixGatewayService.requestOtp(...) returns. In the inspected service, success yields { success: true, otpRequestId }.

  • Example (cURL):

    curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "OmnixGatewayRpc.requestOtp",
    "params": {
      "contactInfo": {
        "email": "[email protected]"
      },
      "channels": ["email"]
    }
  }'

POST /api/rpc (Method: OmnixGatewayRpc.verifyOtp)

  • Description: Verifies an OTP code using the request ID.

  • Request Body:

    {
  "method": "OmnixGatewayRpc.verifyOtp",
  "params": {
    "otpRequestId": "string",
    "code": "123456",
    "finalize": true
  }
}

  • Parameters:

    Name Type Required Description
    otpRequestId String Yes OTP request identifier; cannot be empty.
    code String Yes OTP code with exactly 6 characters.
    finalize Boolean No Defaults to true. When true, the inspected service marks a successful OTP request as verified.

  • Response:

    {
  "verified": true,
  "identifier": "string",
  "channelType": "string"
}

    The inspected service can also return failure responses such as { verified: false, reason: "..." }.

  • Example (cURL):

    curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "OmnixGatewayRpc.verifyOtp",
    "params": {
      "otpRequestId": "abc123",
      "code": "123456"
    }
  }'

POST /api/rpc (Method: OmnixGatewayRpc.sendTemplatedMessage)

  • Description: Sends a message using a pre-defined template.

  • Request Body:

    {
  "method": "OmnixGatewayRpc.sendTemplatedMessage",
  "params": {
    "contactInfo": {
      "contactId": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "[email protected]",
      "sms": "+15551234567",
      "voice": "+15551234567",
      "whatsapp": "+15551234567",
      "context": {}
    },
    "channelType": "email",
    "templateName": "welcome-message",
    "templateData": {},
    "createConversation": false
  }
}

  • Parameters:

    Name Type Required Description
    contactInfo Object Yes Information to identify or create a contact. Provide at least one identifier (contactId, email, sms, etc.).
    channelType "sms" | "email" | "whatsapp" Yes Channel to use for delivery.
    templateName String Yes Name of the template to render and send.
    templateData Record<string, Any> No Data to fill in the template's Mustache variables.
    createConversation Boolean No Defaults to false. If true, the message is sent through the Unified Inbox conversation flow.

  • Response:

    {
  "success": true
}

  • Example (cURL):

    curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "OmnixGatewayRpc.sendTemplatedMessage",
    "params": {
      "contactInfo": {
        "email": "[email protected]"
      },
      "channelType": "email",
      "templateName": "welcome-message",
      "templateData": {
        "name": "Ada"
      }
    }
  }'

POST /api/rpc (Method: OmnixGatewayRpc.sendSystemMessage)

  • Description: Asynchronously delivers a system message to a specific conversation.

  • Request Body:

    {
  "method": "OmnixGatewayRpc.sendSystemMessage",
  "params": {
    "conversationId": "string",
    "messageBody": "string",
    "subject": "string"
  }
}

  • Parameters:

    Name Type Required Description
    conversationId String Yes The ID of the target conversation in Omnix.
    messageBody String Yes The content of the message to be delivered.
    subject String No The subject line, primarily for email conversations.

  • Response:

    {
  "success": true
}

    The method delegates delivery to UnifiedInboxService.sendSystemMessage(...); this file does not define that service’s payload response.

  • Example (cURL):

    curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "OmnixGatewayRpc.sendSystemMessage",
    "params": {
      "conversationId": "conv_123",
      "messageBody": "Hello from Omnix"
    }
  }'

POST /api/rpc (Method: OmnixGatewayRpc.sendSystemMessageToContact)

  • Description: Asynchronously delivers a system message to a contact on a specific channel type.
  • **Request Body