Telephony — Overview

Provider comparison, URL routing pattern, and inbound call flow for assistant-api telephony.

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