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.

List Available Providers

GET /v1/telephony/providers

Returns the full carrier catalog with the credential field shapes the dashboard uses to render dynamic connect forms. No auth required — field metadata is not sensitive.

Response 200

{
  "providers": [
    {
      "id": "twilio",
      "displayName": "Twilio",
      "credentialFields": [
        { "name": "auth_id", "label": "Account SID", "required": true },
        { "name": "auth_token", "label": "Auth token", "secret": true, "required": true }
      ]
    }
  ]
}

---

Validate Without Saving

POST /v1/telephony/validate

Dry-run credential check — pings the carrier's API and returns whether the credentials authenticate, without storing them. Rate-limited to 3 attempts per 5 minutes per tenant.

Request Body

Same shape as Connect Provider.

Response 200

{ "valid": true, "accountName": "Acme Twilio" }

{ "valid": false, "error": "Invalid credentials — could not authenticate with the provider" }

Errors

Status	Meaning
400	Unsupported provider
401	Missing Rymi auth context
429	Too many validation attempts — wait and retry

---

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

---

Sync Numbers from Carrier

POST /v1/telephony/sync-numbers

Pulls phone-number inventory from the connected carrier and upserts it into provider_numbers. Numbers no longer present in the carrier inventory are removed locally. Rate-limited to one sync per 2 minutes per tenant.

Example Request

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

Response 200

{
  "numbers": [
    {
      "phone_number": "+15551234567",
      "number_type": "local",
      "provider": "twilio"
    }
  ],
  "synced_at": "2026-04-01T10:00:00Z"
}

Errors

Status	Meaning
400	No active telephony provider connected, or provider doesn't support sync
429	Sync rate-limited — wait 2 minutes between syncs
500	Carrier API call failed

---

Number Management

Rymi does not search or purchase carrier numbers. Provision numbers in your carrier account, sync them via POST /v1/telephony/sync-numbers, then use the Numbers API to attach them to agents.