Quickstart

Overview

Formi's Universal WebSocket Adapter is a powerful translation layer that sits between your telephony provider and our AI core. Think of it as a universal power adapter for voice streams: it takes the specific protocol and audio format from any of our supported providers and converts it into a standard format that Formi can understand, all in real-time.

This is made possible by a configuration-driven design. Instead of you writing custom code, our team pre-builds and maintains a library of integrations. This allows for the rapid, "plug-and-play" integration of popular third-party telephony platforms. You simply select a provider from our supported list and configure your agent with the necessary credentials.

The diagram below illustrates this flow. The Adapter Layer uses pre-built rules to process the live call from your provider.

How It Works: Connecting Your Provider

You don't need to build or maintain any translation logic. To connect your telephony provider, you discover which vendors we support via an API call and then assign that configuration to your AI agent.

1. Discover Available Vendors

First, retrieve the up-to-date list of telephony providers that Formi supports. Make a GET request to the /connection_configuration/vendors endpoint. The response will include each vendor_name and its params schema, which dynamically tells you exactly which credentials are required for a successful connection.

Example Request:

Example Response:
This response shows that Twilio SMS is a supported vendor and its params schema defines that account_sid and auth_token are required.

{
  "success": true,
  "message": "Connection vendors fetched successfully",
  "payload": {
    "vendors": [
      {
        "vendor_id": 8,
        "vendor_name": "twilio",
        "description": "Twilio",
        "params": {
          "type": "object",
          "required": [
            "channels",
            "encoding",
            "bit_depth",
            "sample_rate",
            "subprotocol",
            "chunk_size_ms",
            "ping_interval",
            "connection_timeout",
            "requires_subprotocol",
            "initial_message_is_text"
          ],
          "properties": {
            "channels": {
              "enum": [
                1
              ],
              "type": "integer",
              "default": 1,
              "maximum": 2,
              "minimum": 1,
              "description": "Number of audio channels (1=mono, 2=stereo)"
            },
            "encoding": {
              "enum": [
                "ulaw",
                "alaw",
                "pcm_16_le",
                "base64_pcm"
              ],
              "type": "string",
              "default": "ulaw",
              "description": "Audio encoding format"
            },
            "bit_depth": {
              "enum": [
                8,
                16
              ],
              "type": "integer",
              "default": 8,
              "maximum": 16,
              "minimum": 8,
              "description": "Bit depth of audio samples"
            },
            "sample_rate": {
              "enum": [
                8000,
                16000,
                24000,
                48000
              ],
              "type": "integer",
              "default": 8000,
              "maximum": 48000,
              "minimum": 8000,
              "description": "Sample rate in Hz"
            },
            "subprotocol": {
              "enum": [
                "echo-protocol",
                "binary",
                "json"
              ],
              "type": "string",
              "default": "echo-protocol",
              "description": "WebSocket subprotocol to use"
            },
            "chunk_size_ms": {
              "enum": [
                20,
                40,
                60
              ],
              "type": "integer",
              "default": 20,
              "maximum": 100,
              "minimum": 10,
              "description": "Audio chunk size in milliseconds"
            },
            "ping_interval": {
              "enum": [
                20,
                30,
                60
              ],
              "type": "integer",
              "default": 20,
              "maximum": 120,
              "minimum": 10,
              "description": "Ping interval in seconds"
            },
            "connection_timeout": {
              "enum": [
                30,
                60,
                120
              ],
              "type": "integer",
              "default": 30,
              "maximum": 300,
              "minimum": 10,
              "description": "Connection timeout in seconds"
            },
            "requires_subprotocol": {
              "type": "boolean",
              "default": true,
              "description": "Whether a subprotocol is required"
            },
            "initial_message_is_text": {
              "type": "boolean",
              "default": true,
              "description": "Whether the initial message is text"
            }
          },
          "additionalProperties": false
        }
      }
    ]
  }
}

Don't See Your Provider?
If your telephony provider is not in the list returned by the API, please contact our support team. We are constantly adding new integrations and can work with you to get your provider added to our platform.

2. Configure Your Agent

Once you have the vendor_name (e.g., "twilio") and its required schema, you can connect it to a specific AI agent. Make a POST request to the /connection_configuration/agents/{agent_id}/connection_config endpoint.

You must specify the provider's name in the connection_provider query parameter. The request body must be a JSON object that conforms to the params schema you retrieved in the previous step.

Example: Configuring an Agent to Use Twilio

Request Body:

{
  "channels": 1,
  "encoding": "ulaw",
  "bit_depth": 8,
  "sample_rate": 8000,
  "subprotocol": "binary",
  "chunk_size_ms": 60,
  "ping_interval": 20,
  "connection_timeout": 120,
  "requires_subprotocol": true,
  "initial_message_is_text": true,
  "twilio_account_sid":"<your_account_sid>",
  "twilio_auth_token":"<your_auth_token>",
}

Our system validates your request body against the vendor's schema. Once this is set, your agent is ready to handle calls from your provider.

Next Steps

Setting up credentials on the Formi platform is not enough. You also need to configure settings from your telephony provider's side so that websocket handshakes can be performed and the connection completed.

Example Integration - Twilio

See a complete, real-world example of integrating Twilio via TwiML and WebSockets.

Example Integration - Exotel

Follow our reference implementation for connecting your Exotel account using WebSockets.

Overview#

How It Works: Connecting Your Provider#

1. Discover Available Vendors#

2. Configure Your Agent#

Next Steps#

Overview

How It Works: Connecting Your Provider

1. Discover Available Vendors

2. Configure Your Agent

Next Steps