New Telephony Provider Requirements

Complete requirements for integrating a new telephony provider with Ringg

This document defines the complete requirements for adding a new telephony provider to Ringg. Any provider must satisfy all five capability areas described below. If any capability is missing, the provider cannot be fully integrated.

1. Outbound Call Initiation API

The provider must expose an API to initiate an outbound call. Ringg will call this API with the following parameters:

Parameter	Description	Format	Example
Phone Number (To)	The end user’s phone number to call	E.164	[phone]
DID / From Number	The caller ID / DID number to show	E.164	[phone]
WebSocket URL	The WebSocket URL the provider must connect to for bidirectional audio streaming once the callee answers. Ringg sends this directly in the outbound call request.	WSS	wss://api.ringg.ai/stream/newprovider/{call_id}
Callback / Hangup URL	URL the provider will POST to when the call ends, with call status, duration, and recording URL.	HTTPS	https://api.ringg.ai/callback/newprovider/{call_id}/hangup

How It Works

1. Call Request

   Ringg receives an outbound call request and creates a Call record with telephony credentials, call config, and agent flow config.

2. Provider API Call

   Ringg decrypts the telephony credentials and calls the provider’s outbound API, passing the WebSocket URL directly in the request.

3. Call Placed & WebSocket Connected

   The provider places the call. When the callee answers, the provider immediately connects to the WebSocket URL provided in the original request and begins bidirectional audio streaming.

4. Call Ends

   When the call ends, the provider hits the Callback/Hangup URL with call status and metadata.

5. Post-Call Processing

   Ringg updates the call record and triggers post-call processing (transcription, recording, webhooks, analytics).

Expected Provider API Format

Request

POST https://api.newprovider.com/v1/calls
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "from": "[phone]",
  "to": "[phone]",
  "websocket_url": "wss://api.ringg.ai/stream/newprovider/{call_id}",
  "hangup_url": "https://api.ringg.ai/callback/newprovider/{call_id}/hangup"
}

{
  "call_id": "provider-unique-call-id",
  "status": "queued"
}

Key point: Unlike inbound calls (where the provider hits a webhook and receives the WebSocket URL in the response), for outbound calls Ringg provides the WebSocket URL upfront in the call initiation request itself. The provider must connect to this WebSocket URL as soon as the callee answers — no additional callback/answer URL round-trip is needed.

---

2. Get Call By ID API

The provider must expose an API to fetch call details by call ID. This is used for:

• Verifying call status during/after the call
• Fetching call duration and billing metadata
• Retrieving recording URLs (if recorded by the provider)

Expected API Format

Request

GET https://api.newprovider.com/v1/calls/{call_id}
Authorization: Bearer <api_key>

{
  "call_id": "provider-unique-call-id",
  "status": "completed",
  "duration": 120,
  "from": "[phone]",
  "to": "[phone]",
  "recording_url": "https://recordings.newprovider.com/rec_123.mp3",
  "start_time": "2026-03-12T10:00:00Z",
  "end_time": "2026-03-12T10:02:00Z"
}

How Existing Providers Handle This

Provider	Endpoint	Auth
Plivo	GET /v1/Account/{auth_id}/Call/{call_uuid}/	Basic Auth (auth_id:auth_token)
Twilio	GET /2010-04-01/Accounts/{sid}/Calls/{call_sid}.json	Basic Auth (sid:auth_token)
Exotel	GET /v2_beta/Accounts/{sid}/Calls/{call_sid}.json	Basic Auth (api_key:api_token)
TataTele	GET /v1/live_calls	Bearer Token
Vobiz	GET /api/v1/Account/{auth_id}/Call/{call_uuid}/	Custom Headers (X-Auth-ID, X-Auth-Token)

---

3. Inbound Call Support

For inbound calls, the flow is reversed — the provider calls Ringg when an incoming call arrives.

Required Flow

1. Caller Dials DID

   A caller dials a Ringg DID number. The telephony provider receives the call.

2. Provider Sends Webhook

   The provider sends a webhook to Ringg’s inbound endpoint with call_sid, from_number, and to_number (the DID). The caller must be held in a ringing state during this step.

3. Ringg Returns WebSocket URL

   Ringg looks up the to_number, finds the workspace and agent assigned to this DID, builds the call config, and returns a response containing the WebSocket URL.

4. Audio Streaming Begins

   The provider connects to the WebSocket URL and begins bidirectional audio streaming immediately.

Critical Requirements

Hold in Ringing State

When the provider hits the inbound webhook, it must keep the caller in a ringing/hold state until Ringg responds with the WebSocket URL. The caller should NOT hear silence or get disconnected during this setup time.

WebSocket URL in Response

Ringg returns the WebSocket URL in the response to the provider’s webhook. The format depends on the provider:

XML-based providers (Plivo):

<Response>
  <Stream keepalive="true" audio="true" contentType="audio/x-mulaw">
    wss://api.ringg.ai/stream/newprovider/{call_id}
  </Stream>
</Response>

TwiML-based providers (Twilio):

<Response>
  <Connect>
    <Stream url="wss://api.ringg.ai/stream/newprovider/{call_id}" />
  </Connect>
</Response>

JSON-based providers (others):

{
  "websocket_url": "wss://api.ringg.ai/stream/newprovider/{call_id}"
}

Immediate WebSocket Connection

After receiving the WebSocket URL, the provider must immediately connect and begin bidirectional audio streaming.

Provider must support:

• Webhook/callback mechanism for incoming calls
• Ability to hold the caller in ringing state while setup completes
• Connecting to an external WebSocket URL for audio streaming

---

4. WebSocket Streaming

The provider must support bidirectional WebSocket audio streaming. This is how the AI agent communicates with the caller in real-time.

WebSocket Requirements

Requirement	Details
Protocol	WSS (WebSocket Secure)
Audio Format	PCM 16-bit, mu-law, or a-law (provider-dependent)
Sample Rate	8kHz or 16kHz
Direction	Bidirectional — provider sends caller audio, receives AI agent audio
Latency	Low latency streaming (< 200ms round-trip ideal)

Required WebSocket Message Types

1. Audio Messages

Binary frames containing audio data from the caller.

2. DTMF Events (REQUIRED)

When the caller presses keypad digits during the call, the provider must send DTMF events through the WebSocket. This is critical for IVR-style interactions.

Example DTMF message format:

{
  "event": "dtmf",
  "digit": "5",
  "call_id": "provider-call-id"
}

3. Call Control Events

Start, stop, and hangup signals to manage the call lifecycle.

DTMF is mandatory because Ringg agents use the wait_for_dtmf tool to collect keypad input from callers (e.g., “Press 1 to confirm, Press 2 to cancel”). Without DTMF support, these agent flows will not work.

Reference: TataTele WebSocket Message Format

Use the following as a reference for expected message types:

• Connection established message
• Audio data frames (binary)
• DTMF digit events
• Call state change events (connected, disconnected)
• Metadata messages (call_id, caller info)

---

5. Call Transfer Support

The provider must support transferring an active call to another phone number. The AI agent uses the call_transfer tool to decide when and where to transfer.

Transfer Type

Type	Description
Blind Transfer	Transfer the call to another number without waiting for the target to answer

How Transfer Works

1. AI Decision

   During a call, the AI agent decides to transfer based on conversation context and configured transfer rules.

2. Transfer Command

   The agent calls the call_transfer tool with a target phone number. Ringg sends a transfer command to the provider via their API or WebSocket control message.

3. Call Connected

   The provider connects the caller to the target number. The transfer event is logged for analytics.

Expected Provider API for Transfer

REST API

POST https://api.newprovider.com/v1/calls/{call_id}/transfer
Authorization: Bearer <api_key>

{
  "target_number": "[phone]",
  "transfer_type": "blind"
}

{
  "action": "transfer",
  "target_number": "[phone]",
  "call_id": "provider-call-id"
}

---

Summary Checklist

Before proceeding with integration, confirm your telephony provider supports all of the following:

Capability	Required
Outbound call initiation API (with WebSocket URL parameter)	Yes
Get call by ID API	Yes
Inbound call webhooks with ringing hold	Yes
Bidirectional WebSocket audio streaming	Yes
DTMF events via WebSocket	Yes
Blind call transfer	Yes

Ready to Integrate?

If your provider meets all requirements, contact us at [e-mail] to get started.

Provider Doesn't Meet All Requirements?

No problem! Reach out to us and we’ll work with you to find a way to make it work.