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
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
{
"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
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
{ "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
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, vonage, or telnyx |
auth_id | string | Yes (Plivo/Twilio/Telnyx) | - | Plivo Auth ID, Twilio Account SID, or Telnyx API Key |
auth_token | string | Yes (Plivo/Twilio) | - | Provider auth token. For Telnyx this is the Connection ID and is optional, Rymi auto-creates a TeXML app when omitted |
api_key | string | Yes (Vonage) | - | Vonage API key |
api_secret | string | Yes (Vonage) | - | Vonage API secret |
application_id | string | Yes (Vonage) | - | Vonage Voice Application ID |
private_key | string | Yes (Vonage) | - | Vonage Voice private key (PEM) |
auth_secret | string | No | - | Optional webhook signing secret (Telnyx Ed25519 verification) |
signature_secret | string | No | - | Optional Vonage signature secret for webhook verification (required to receive inbound calls) |
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"
}'const result = await rymi.telephony.connect({
provider: "twilio",
auth_id: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
auth_token: "your_twilio_auth_token",
});result = rymi.telephony.connect(
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"
}'const result = await rymi.telephony.connect({
provider: "plivo",
auth_id: "your_plivo_auth_id",
auth_token: "your_plivo_auth_token",
});result = rymi.telephony.connect(
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",
"application_id": "your_vonage_voice_application_id",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
"signature_secret": "your_vonage_signature_secret"
}'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",
});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
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
{
"status": "connected",
"provider": "twilio",
"account_name": "Acme Twilio",
"message": "twilio account connected successfully"
}Errors
| Status | Meaning |
|---|---|
400 | Missing or unsupported provider, missing provider-specific credentials, or invalid carrier credentials (validation failed) |
401 | Missing Rymi auth context |
429 | Too many credential connection attempts in a short window |
500 | Credential storage failed |
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"const status = await rymi.telephony.status();status = rymi.telephony.status()Response 200
{
"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.
| Field | Type | Description |
|---|---|---|
connected | boolean | Whether a telephony provider is currently connected |
provider | string or null | Active provider: plivo, twilio, vonage, or telnyx |
account_name | string or null | Display name from the provider account |
managed_by_rymi | boolean | true when the active line is provisioned and managed by Rymi |
managed_line | object or null | Active managed line summary: { phone_number: string | null, status: string } |
test_pool | object | Shared test-number pool status: { enabled: boolean, countries: string[] } |
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
500 | Provider status lookup failed |
Provider 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
curl https://api.rymi.live/v1/telephony/numbers \
-H "Authorization: Bearer YOUR_API_KEY"const { numbers } = await rymi.telephony.numbers();result = rymi.telephony.numbers()Response 200
{
"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" }
}
]
}| Field | Type | Description |
|---|---|---|
id | string | Internal number record ID |
provider | string | Carrier provider name |
phone_number | string | Phone number in E.164 format |
number_type | string or null | Carrier-reported number type (e.g. local, tollfree) |
number_status | string | active or inactive |
assigned_app_id | string or null | Carrier application/connection the number is bound to, if any |
backend_agent_id | uuid or null | Agent attached to this number, if any |
synced_at | string or null | Timestamp of the last carrier sync for this number |
agents | object or null | Attached agent { id, name }, joined from backend_agent_id |
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
500 | Provider number lookup failed |
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"const result = await rymi.telephony.disconnect();result = rymi.telephony.disconnect()Response 200
{
"status": "disconnected",
"message": "Telephony disconnected."
}Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
500 | Disconnect operation failed |
Search Available Numbers
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.
| Query | Type | Required | Description |
|---|---|---|---|
country | string | Yes | ISO 3166 alpha-2 code, e.g. IN, US |
type | string | No | local, mobile, tollfree, national, or fixed |
pattern | string | No | Digits the number starts with (up to 8) |
offset | integer | No | Pagination offset; each page returns up to 20 |
Response 200
{
"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
| Status | Meaning |
|---|---|
400 | No connected provider, provider does not support search, or expired credentials |
401 | Missing Rymi auth context |
403 | Publishable keys cannot search numbers |
429 | More than 20 searches per minute |
502 | The carrier search failed |
Sync Numbers from Carrier
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.
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
curl https://api.rymi.live/v1/telephony/line \
-H "Authorization: Bearer YOUR_API_KEY"const { has_line, line } = await rymi.telephony.line();result = rymi.telephony.line()Response 200
{
"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 }.
| Field | Type | Description |
|---|---|---|
status | string | pending, active, suspended or released |
phone_number | string or null | E.164 number, once bought |
kyc_status | string | none, collecting, submitted, accepted or rejected |
kyc_missing | string[] | India only. Any of name, addressLine1, city, state, postalCode, registrationNumber, documents. Empty for US |
terms_accepted | boolean | true once you accept the line terms |
outbound_suspended | boolean | Rymi stopped outbound calls on this line; suspended_reason says why |
max_concurrent_calls, max_minutes_per_day | integer | Call limits on the line |
rental_paid_through | date or null | Last day the monthly rental covers |
unpaid_since | date or null | First unpaid day |
release_at | date or null | unpaid_since plus 30 days. Rymi releases the number on this date unless you top up |
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable key |
Request Line
Starts a line, or returns the one you already have, and gives you the Studio page that finishes setup.
| Field | Type | Required | Description |
|---|---|---|---|
country | string | Yes | IN or US |
handoff | string | No | studio (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 |
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" }'const { studio_url } = await rymi.telephony.requestLine({ country: 'IN', handoff: 'both' });result = rymi.telephony.request_line("IN", handoff="both")Response 200
{
"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
| Status | Meaning |
|---|---|
400 | country is not IN or US |
401 | Missing or invalid API key |
403 | Publishable key, or managed_lines_disabled: lines are not available for that country yet |
Accept Terms
Records that you accepted the current line terms. Takes no body. India KYC cannot be submitted until you do.
curl -X POST https://api.rymi.live/v1/telephony/line/accept-terms \
-H "Authorization: Bearer YOUR_API_KEY"await rymi.telephony.acceptLineTerms();rymi.telephony.accept_line_terms()Response 200
{ "ok": true, "line_id": "8c1d2f4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "terms_version": "1", "terms_url": "https://rymi.live/terms/lines" }Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Publishable key |
404 | line_not_found: request a line first |
500 | terms_not_recorded: nothing was saved; retry |
Update 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.
| Field | Type | Required | Description |
|---|---|---|---|
fields.name | string | No | Registered business name (legal_name also accepted) |
fields.addressLine1 | string | No | Street address (address_line1 also accepted) |
fields.city, fields.state | string | No | City and state |
fields.postalCode | string | No | PIN code (postal_code also accepted) |
fields.registrationNumber | string | No | GSTIN or other registration number (registration_number also accepted) |
fields.email | string | No | Contact email. Optional; Rymi uses its own inbox when you leave it out |
document | object | No | One file: { filename, mime_type, content_base64 }. PDF, JPEG or PNG, up to 10 MB |
submit | boolean | No | File the application when nothing is missing |
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
}'const { kyc_status, kyc_missing } = await rymi.telephony.submitLineKyc({
fields: { name: 'Sharma Realty Pvt Ltd', city: 'Pune', state: 'Maharashtra' },
submit: true,
});result = rymi.telephony.submit_line_kyc(
fields={"name": "Sharma Realty Pvt Ltd", "city": "Pune", "state": "Maharashtra"},
submit=True,
)Response 200
{ "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
| Status | Meaning |
|---|---|
400 | unsupported_type (not PDF, JPEG or PNG) or too_large (over 10 MB) |
401 | Missing or invalid API key |
403 | Publishable key |
404 | line_not_found |
409 | kyc_locked: KYC is submitted or accepted and can no longer change |
500 | upload_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.

