Skip to content

Telephony ​

Connect your Plivo, Twilio, Vonage, or Telnyx 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 agent's per-minute rate. Managed from $0.035/min, or BYO providers at cost plus $0.02/min runtime.

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, since field metadata is not sensitive.

Response 200 ​

json
{
  "providers": [
    {
      "id": "twilio",
      "displayName": "Twilio",
      "credentialFields": [
        { "key": "auth_id", "label": "Account SID", "type": "text", "required": true },
        { "key": "auth_token", "label": "Auth Token", "type": "secret", "required": true }
      ]
    }
  ]
}

Validate Without Saving ​

POST/v1/telephony/validate

Pings the carrier's API and returns whether the credentials authenticate, without storing them. Rate-limited to 3 attempts per 300 seconds per tenant.

Request Body ​

Same shape as Connect Provider.

Response 200 ​

json
{ "valid": true, "accountName": "Acme Twilio" }
json
{ "valid": false, "error": "Invalid credentials: could not authenticate with the provider" }

Errors ​

StatusMeaning
400Unsupported provider
401Missing Rymi auth context
429Too 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 ​

FieldTypeRequiredDefaultDescription
providerstringYes-plivo, twilio, vonage, or telnyx
auth_idstringYes (Plivo/Twilio/Telnyx)-Plivo Auth ID, Twilio Account SID, or Telnyx API Key
auth_tokenstringYes (Plivo/Twilio)-Provider auth token. For Telnyx this is the Connection ID and is optional, Rymi auto-creates a TeXML app when omitted
api_keystringYes (Vonage)-Vonage API key
api_secretstringYes (Vonage)-Vonage API secret
application_idstringYes (Vonage)-Vonage Voice Application ID
private_keystringYes (Vonage)-Vonage Voice private key (PEM)
auth_secretstringNo-Optional webhook signing secret (Telnyx Ed25519 verification)
signature_secretstringNo-Optional Vonage signature secret for webhook verification (required to receive inbound calls)

Example: Twilio ​

bash
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"
  }'
ts
const result = await rymi.telephony.connect({
  provider: "twilio",
  auth_id: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  auth_token: "your_twilio_auth_token",
});
python
result = rymi.telephony.connect(
    provider="twilio",
    auth_id="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    auth_token="your_twilio_auth_token",
)

Example: Plivo ​

bash
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"
  }'
ts
const result = await rymi.telephony.connect({
  provider: "plivo",
  auth_id: "your_plivo_auth_id",
  auth_token: "your_plivo_auth_token",
});
python
result = rymi.telephony.connect(
    provider="plivo",
    auth_id="your_plivo_auth_id",
    auth_token="your_plivo_auth_token",
)

Example: Vonage ​

bash
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",
    "application_id": "your_vonage_voice_application_id",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    "signature_secret": "your_vonage_signature_secret"
  }'
ts
const result = await rymi.telephony.connect({
  provider: "vonage",
  api_key: "your_vonage_api_key",
  api_secret: "your_vonage_api_secret",
  application_id: "your_vonage_voice_application_id",
  private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  signature_secret: "your_vonage_signature_secret",
});
python
result = rymi.telephony.connect(
    provider="vonage",
    api_key="your_vonage_api_key",
    api_secret="your_vonage_api_secret",
    application_id="your_vonage_voice_application_id",
    private_key="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    signature_secret="your_vonage_signature_secret",
)

Example: Telnyx ​

bash
curl -X POST https://api.rymi.live/v1/telephony/connect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "telnyx",
    "auth_id": "your_telnyx_api_key",
    "auth_token": "your_telnyx_connection_id",
    "auth_secret": "your_telnyx_webhook_signing_secret"
  }'

Response 200 ​

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

Errors ​

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

Status ​

GET/v1/telephony/status

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

Example Request ​

bash
curl https://api.rymi.live/v1/telephony/status \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const status = await rymi.telephony.status();
python
status = rymi.telephony.status()

Response 200 ​

json
{
  "connected": true,
  "provider": "twilio",
  "account_name": "Acme Twilio",
  "managed_by_rymi": false,
  "managed_line": null,
  "test_pool": { "enabled": true, "countries": ["US", "IN"] }
}

test_pool is always present, on both the connected and disconnected branches, and reports the shared test-number pool for the tenant.

FieldTypeDescription
connectedbooleanWhether a telephony provider is currently connected
providerstring or nullActive provider: plivo, twilio, vonage, or telnyx
account_namestring or nullDisplay name from the provider account
managed_by_rymibooleantrue when the active line is provisioned and managed by Rymi
managed_lineobject or nullActive managed line summary: { phone_number: string | null, status: string }
test_poolobjectShared test-number pool status: { enabled: boolean, countries: string[] }

Errors ​

StatusMeaning
401Missing or invalid API key
500Provider status lookup failed

Provider Numbers ​

GET/v1/telephony/numbers

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

Example Request ​

bash
curl https://api.rymi.live/v1/telephony/numbers \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const { numbers } = await rymi.telephony.numbers();
python
result = rymi.telephony.numbers()

Response 200 ​

json
{
  "numbers": [
    {
      "id": "num_123",
      "provider": "twilio",
      "phone_number": "+15551234567",
      "number_type": "local",
      "number_status": "active",
      "assigned_app_id": null,
      "backend_agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "synced_at": "2026-04-01T10:00:00Z",
      "agents": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Support Bot" }
    }
  ]
}
FieldTypeDescription
idstringInternal number record ID
providerstringCarrier provider name
phone_numberstringPhone number in E.164 format
number_typestring or nullCarrier-reported number type (e.g. local, tollfree)
number_statusstringactive or inactive
assigned_app_idstring or nullCarrier application/connection the number is bound to, if any
backend_agent_iduuid or nullAgent attached to this number, if any
synced_atstring or nullTimestamp of the last carrier sync for this number
agentsobject or nullAttached agent { id, name }, joined from backend_agent_id

Errors ​

StatusMeaning
401Missing or invalid API key
500Provider number lookup failed

Disconnect ​

POST/v1/telephony/disconnect

Deactivates the current telephony provider. No request body required.

Example Request ​

bash
curl -X POST https://api.rymi.live/v1/telephony/disconnect \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const result = await rymi.telephony.disconnect();
python
result = rymi.telephony.disconnect()

Response 200 ​

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

Errors ​

StatusMeaning
401Missing or invalid API key
500Disconnect operation failed

Search Available Numbers ​

GET/v1/telephony/numbers/search?country=IN&type=local&pattern=8044

Searches the connected carrier's purchasable inventory using your own carrier credentials. Plivo only. This is read-only: Rymi does not buy numbers. Buy the number in your Plivo console (your KYC, your bill), then run Sync Numbers from Carrier.

QueryTypeRequiredDescription
countrystringYesISO 3166 alpha-2 code, e.g. IN, US
typestringNolocal, mobile, tollfree, national, or fixed
patternstringNoDigits the number starts with (up to 8)
offsetintegerNoPagination offset; each page returns up to 20

Response 200 ​

json
{
  "provider": "plivo",
  "numbers": [
    {
      "phone_number": "+918044001234",
      "city": "Bangalore",
      "number_type": "local",
      "monthly_rate": "4.00000",
      "setup_rate": "0.00000",
      "restriction": null
    }
  ]
}

Rates are Plivo's quote in USD and are billed by Plivo. A non-null restriction means Plivo needs verification documents before the number activates. Indian numbers need an approved KYC application on an India-region Plivo account.

Errors ​

StatusMeaning
400No connected provider, provider does not support search, or expired credentials
401Missing Rymi auth context
403Publishable keys cannot search numbers
429More than 20 searches per minute
502The carrier search 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 ​

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

Response 200 ​

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

Errors ​

StatusMeaning
400No active telephony provider connected, or provider doesn't support sync
429Sync rate-limited; wait 2 minutes between syncs
500Carrier 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.


Phone Line from Rymi ​

These four routes manage a phone line from Rymi, a number Rymi rents for you in IN or US instead of a number on your own carrier. A workspace has at most one active line. Publishable keys get 403 on all of them. MCP exposes the first two as get_phone_line and request_phone_line.

Get Line ​

GET/v1/telephony/line
bash
curl https://api.rymi.live/v1/telephony/line \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
const { has_line, line } = await rymi.telephony.line();
python
result = rymi.telephony.line()

Response 200 ​

json
{
  "has_line": true,
  "line": {
    "id": "8c1d2f4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "country": "IN",
    "status": "pending",
    "phone_number": null,
    "kyc_status": "collecting",
    "kyc_rejection_reason": null,
    "kyc_missing": ["registrationNumber", "documents"],
    "terms_accepted": true,
    "terms_version": "1",
    "outbound_suspended": false,
    "suspended_reason": null,
    "max_concurrent_calls": 2,
    "max_minutes_per_day": 300,
    "rental_paid_through": null,
    "unpaid_since": null,
    "release_at": null
  }
}

With no line, the response is { "has_line": false, "line": null }.

FieldTypeDescription
statusstringpending, active, suspended or released
phone_numberstring or nullE.164 number, once bought
kyc_statusstringnone, collecting, submitted, accepted or rejected
kyc_missingstring[]India only. Any of name, addressLine1, city, state, postalCode, registrationNumber, documents. Empty for US
terms_acceptedbooleantrue once you accept the line terms
outbound_suspendedbooleanRymi stopped outbound calls on this line; suspended_reason says why
max_concurrent_calls, max_minutes_per_dayintegerCall limits on the line
rental_paid_throughdate or nullLast day the monthly rental covers
unpaid_sincedate or nullFirst unpaid day
release_atdate or nullunpaid_since plus 30 days. Rymi releases the number on this date unless you top up

Errors ​

StatusMeaning
401Missing or invalid API key
403Publishable key

Request Line ​

POST/v1/telephony/line/request

Starts a line, or returns the one you already have, and gives you the Studio page that finishes setup.

FieldTypeRequiredDescription
countrystringYesIN or US
handoffstringNostudio (default), whatsapp or both. With whatsapp, Rymi also sends the terms prompt with Accept and Decline buttons to the WhatsApp number you last used with the Rymi assistant
bash
curl -X POST https://api.rymi.live/v1/telephony/line/request \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "country": "IN", "handoff": "both" }'
ts
const { studio_url } = await rymi.telephony.requestLine({ country: 'IN', handoff: 'both' });
python
result = rymi.telephony.request_line("IN", handoff="both")

Response 200 ​

json
{
  "line_id": "8c1d2f4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "country": "IN",
  "status": "pending",
  "studio_url": "https://studio.rymi.live/numbers/rymi?line=8c1d2f4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "whatsapp_handoff_sent": true
}

whatsapp_handoff_sent is false when you asked for studio or Rymi has no WhatsApp conversation for your account.

Errors ​

StatusMeaning
400country is not IN or US
401Missing or invalid API key
403Publishable key, or managed_lines_disabled: lines are not available for that country yet

Accept Terms ​

POST/v1/telephony/line/accept-terms

Records that you accepted the current line terms. Takes no body. India KYC cannot be submitted until you do.

bash
curl -X POST https://api.rymi.live/v1/telephony/line/accept-terms \
  -H "Authorization: Bearer YOUR_API_KEY"
ts
await rymi.telephony.acceptLineTerms();
python
rymi.telephony.accept_line_terms()

Response 200 ​

json
{ "ok": true, "line_id": "8c1d2f4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "terms_version": "1", "terms_url": "https://rymi.live/terms/lines" }

Errors ​

StatusMeaning
401Missing or invalid API key
403Publishable key
404line_not_found: request a line first
500terms_not_recorded: nothing was saved; retry

Update KYC ​

POST/v1/telephony/line/kyc

India lines need business KYC before Rymi can buy the number. Send fields as you collect them; each call merges into what is already saved. Once kyc_missing is empty, send submit: true to file the application.

FieldTypeRequiredDescription
fields.namestringNoRegistered business name (legal_name also accepted)
fields.addressLine1stringNoStreet address (address_line1 also accepted)
fields.city, fields.statestringNoCity and state
fields.postalCodestringNoPIN code (postal_code also accepted)
fields.registrationNumberstringNoGSTIN or other registration number (registration_number also accepted)
fields.emailstringNoContact email. Optional; Rymi uses its own inbox when you leave it out
documentobjectNoOne file: { filename, mime_type, content_base64 }. PDF, JPEG or PNG, up to 10 MB
submitbooleanNoFile the application when nothing is missing
bash
curl -X POST https://api.rymi.live/v1/telephony/line/kyc \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "name": "Sharma Realty Pvt Ltd",
      "addressLine1": "14 FC Road",
      "city": "Pune",
      "state": "Maharashtra",
      "postalCode": "411004",
      "registrationNumber": "27AABCS1234F1Z5"
    },
    "document": { "filename": "gst.pdf", "mime_type": "application/pdf", "content_base64": "JVBERi0xLjQK..." },
    "submit": true
  }'
ts
const { kyc_status, kyc_missing } = await rymi.telephony.submitLineKyc({
  fields: { name: 'Sharma Realty Pvt Ltd', city: 'Pune', state: 'Maharashtra' },
  submit: true,
});
python
result = rymi.telephony.submit_line_kyc(
    fields={"name": "Sharma Realty Pvt Ltd", "city": "Pune", "state": "Maharashtra"},
    submit=True,
)

Response 200 ​

json
{ "ok": true, "line_id": "8c1d2f4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "kyc_status": "submitted", "kyc_missing": [], "submitted": true }

submitted stays false when fields are still missing, you have not accepted the terms, or the filing failed. Check kyc_missing and call Get Line.

Errors ​

StatusMeaning
400unsupported_type (not PDF, JPEG or PNG) or too_large (over 10 MB)
401Missing or invalid API key
403Publishable key
404line_not_found
409kyc_locked: KYC is submitted or accepted and can no longer change
500upload_failed: the document was not stored; retry

Two related routes live with their resources: held edits for agents on a line, and recording voice consent by phone number.