Telephony

Connect your Plivo, Twilio, or Vonage account to use for outbound and inbound PSTN legs. Rymi encrypts provider credentials before storage.

Self-serve BYOC carrier costs are not bundled into Rymi's platform minute price. Your carrier bills PSTN minutes, number rental, taxes, and add-ons directly. Rymi bills at the selected Operator/Specialist/Executive agent-role rate. Enterprise plans can bundle telecom under a custom agreement.

Connect Provider

POST /v1/telephony/connect

Only one active telephony carrier is used per tenant at a time. Connecting a new provider deactivates the previous active carrier.

Request Body

Field	Type	Required	Default	Description
provider	string	Yes	—	plivo, twilio, or vonage
auth_id	string	Yes (Plivo/Twilio)	—	Plivo Auth ID or Twilio Account SID
auth_token	string	Yes (Plivo/Twilio)	—	Provider auth token
api_key	string	Yes (Vonage)	—	Vonage API key
api_secret	string	Yes (Vonage)	—	Vonage API secret
signature_secret	string	No	—	Optional Vonage signature secret for webhook verification

Example — Twilio

curl -X POST https://api.rymi.live/v1/telephony/connect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "twilio",
    "auth_id": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_twilio_auth_token"
  }'

Example — Plivo

curl -X POST https://api.rymi.live/v1/telephony/connect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "plivo",
    "auth_id": "your_plivo_auth_id",
    "auth_token": "your_plivo_auth_token"
  }'

Example — Vonage

curl -X POST https://api.rymi.live/v1/telephony/connect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "vonage",
    "api_key": "your_vonage_api_key",
    "api_secret": "your_vonage_api_secret",
    "signature_secret": "your_vonage_signature_secret"
  }'

Response 200

{
  "status": "connected",
  "provider": "twilio",
  "account_name": "Acme Twilio",
  "message": "twilio account connected successfully"
}

Errors

Status	Meaning
400	Missing or unsupported provider, or missing provider-specific credentials
401	Missing Rymi auth context or provider credential validation failed
429	Too many credential connection attempts in a short window
500	Credential storage failed

---

Status

GET /v1/telephony/status

Returns the current telephony connection state for the authenticated tenant. No query parameters.

Example Request

curl https://api.rymi.live/v1/telephony/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "connected": true,
  "provider": "twilio",
  "account_name": "Acme Twilio",
  "account_country": null
}

Field	Type	Description
connected	boolean	Whether a telephony provider is currently connected
provider	string or null	Active provider: plivo, twilio, or vonage
account_name	string or null	Display name from the provider account
account_country	string or null	Account country when reported by the provider

Errors

Status	Meaning
401	Missing or invalid API key
500	Provider status lookup failed

---

Provider Numbers

GET /v1/telephony/numbers

Returns carrier-owned numbers synced into Rymi for the connected provider. This is read-only — it does not search, buy, release, assign, or unassign carrier numbers.

Example Request

curl https://api.rymi.live/v1/telephony/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "numbers": [
    {
      "id": "num_123",
      "provider": "twilio",
      "phone_number": "+15551234567",
      "number_status": "active",
      "backend_agent_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Field	Type	Description
id	string	Internal number record ID
provider	string	Carrier provider name
phone_number	string	Phone number in E.164 format
number_status	string	active or inactive
backend_agent_id	uuid or null	Agent attached to this number, if any

Errors

Status	Meaning
401	Missing or invalid API key
500	Provider number lookup failed

---

Disconnect

POST /v1/telephony/disconnect

Deactivates the current telephony provider. No request body required.

Example Request

curl -X POST https://api.rymi.live/v1/telephony/disconnect \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "status": "disconnected",
  "message": "Telephony disconnected."
}

Errors

Status	Meaning
401	Missing or invalid API key
500	Disconnect operation failed

---

Number Management

Rymi does not search or purchase carrier numbers. Provision numbers in your carrier account, then use the Numbers API to register, attach, and remove local BYOC number registrations.