Telephony — Overview - rapida.ai documentation

The assistant-api supports five telephony providers. Each is identified by a string constant in api/assistant-api/internal/channel/telephony/telephony.go.

const (
    Twilio   Telephony = "twilio"
    Exotel   Telephony = "exotel"
    Vonage   Telephony = "vonage"
    Asterisk Telephony = "asterisk"
    SIP      Telephony = "sip"
)

Provider Comparison

Provider	Transport	Audio Format	Region
Twilio	WebSocket (Media Streams)	μ-law 8kHz	Global
Vonage	WebSocket	Linear PCM 16kHz	Global
Exotel	WebSocket	μ-law 8kHz	India / SEA
Asterisk AudioSocket	Raw TCP port 4573	SLIN 16-bit 8kHz	Self-hosted PBX
Asterisk WebSocket	WebSocket (`chan_websocket`)	μ-law 8kHz	Self-hosted PBX
SIP	UDP port 5090 + RTP	PCM	Direct SIP / SIP trunks

Twilio, Vonage, and Exotel are cloud providers — they call your server. PUBLIC_ASSISTANT_HOST must be a publicly reachable HTTPS hostname. For local development, use ngrok.Asterisk connects from your PBX to Rapida — no public URL needed on Asterisk’s side.SIP is a built-in server in assistant-api — any SIP client dials it directly.

URL Routing

All telephony paths follow this pattern (source: api/assistant-api/internal/type/telephony.go):

Path	Method	Auth	Purpose
`/v1/talk/{provider}/call/{assistantId}?x-api-key={apiKey}`	POST / GET	Query param	Inbound call webhook — provider → Rapida
`/v1/talk/{provider}/ctx/{contextId}?x-api-key={apiKey}`	WebSocket	Query param	Bidirectional audio stream
`/v1/talk/{provider}/ctx/{contextId}/event?x-api-key={apiKey}`	POST	Query param	Call status / lifecycle events

All telephony endpoints authenticate via the x-api-key query parameter. Use a project API key (rpd-xxx) scoped to the project that owns the assistant.

func GetContextAnswerPath(provider, contextID string) string {
    return fmt.Sprintf("v1/talk/%s/ctx/%s", provider, contextID)
}
func GetContextEventPath(provider, contextID string) string {
    return fmt.Sprintf("v1/talk/%s/ctx/%s/event", provider, contextID)
}

The contextId is generated on the first webhook hit. It is stored in PostgreSQL and binds together the call session, assistant, conversation, and auth token.

Inbound Call Flow

Provider Pages

Twilio

Global PSTN via WebSocket Media Streams

Vonage

Global PSTN via WebSocket NCCO

Exotel

India / SEA PSTN

Asterisk

Self-hosted PBX — AudioSocket and WebSocket

SIP

Built-in SIP server, any SIP client

Configure Your Own

Implement the Telephony interface

Getting Started

Dashboard (UI)

Web API

Assistant API

Integration API

Endpoint API

Document API

Telephony — Overview

Provider Comparison

URL Routing

Inbound Call Flow

Provider Pages

Twilio

Vonage

Exotel

Asterisk

SIP

Configure Your Own

​Provider Comparison

​URL Routing

​Inbound Call Flow

​Provider Pages

Twilio

Vonage

Exotel

Asterisk

SIP

Configure Your Own

Provider Comparison

URL Routing

Inbound Call Flow

Provider Pages