> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Telnyx plugin

> Voice and SMS with Telnyx - send SMS and MMS, manage messaging profiles and phone numbers, search numbers to buy, place and control calls, and manage the call control applications calls dial through.

Use **Telnyx** through Corsair: one client, typed API calls.

Create a key in the Telnyx portal under API Keys. Send it as `Authorization: Bearer <key>`. A key inherits the permissions of the user who created it, so a restricted user's key cannot manage numbers.

Things to know before you call:

* **Sending charges the account.** `messages.send` bills per message part, and `calls.create` bills per minute from the moment the call is answered. There is no sandbox.
* **A sender is required, in one of two forms.** Send `from` for a phone number or alphanumeric sender ID, or send `messaging_profile_id` and let that profile's number pool pick the sender. The plugin rejects a send with neither.
* **SMS needs text, MMS needs media.** A send with neither text nor `media_urls` is rejected before the request, because Telnyx refuses it too.
* **Paging uses bracketed keys.** `page[number]` and `page[size]` on the messaging profile, number and application lists. `page[size]` runs from 1 to 250. The available-numbers route has no pages: it takes its filters bracketed, `filter[country_code]` and the rest, and `limit` is one of those filters rather than a top-level value.
* **Responses are wrapped.** Every answer is `{ data }`, and a list adds `meta` with `total_pages`, `total_results`, `page_number` and `page_size`. The one exception is `messages.delete`, which answers with the bare message.
* **Sends, dials and live-call actions are destructive.** `messages.send`, `calls.create`, `calls.speak` and `calls.hangup` bill the account, reach a person or cannot be undone. `calls.speak` needs `payload` and `voice`; `language` is optional.
* **`messages.delete` cancels a scheduled message.** It only works on a message sent with `send_at` that has not gone out yet.
* **Number settings.** `phoneNumbers.update` changes the connection, tags, billing group, customer reference and similar fields. Telnyx sets a number's messaging profile and emergency settings on separate routes this plugin does not cover.
* **Call control application first.** `calls.create` takes a `connection_id`, which is the ID of a call control application. Create one with `callControlApplications.create`, which requires a `webhook_event_url` because Telnyx sends every call event there.
* **Releasing a number is permanent.** `phoneNumbers.delete` gives the number back to the pool and it cannot be recovered. Deleting a messaging profile detaches its numbers rather than releasing them.
* **Error codes.** A failure is core's `ApiError`, whose body is `{ errors: [{ code, title, detail }] }`; `telnyxErrorDetails(error)` reads the entries. `20100` is "Insufficient Funds", which no retry fixes.

**What you get:**

* 22 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/telnyx better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/telnyx better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/telnyx better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/telnyx better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { telnyx } from '@corsair-dev/telnyx';

export const corsair = createCorsair({
	plugins: [
		telnyx(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the Telnyx API key before the first call: `pnpm corsair setup --plugin=telnyx --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> telnyx()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'telnyx',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List the numbers on the account**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.telnyx.api.phoneNumbers.list({ pageSize: 25 });
```

**Send an SMS**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.telnyx.api.messages.send({ from: '+13125550001', to: '+13125550002', text: 'Hello from Telnyx' });
```

See the full list on the [API](https://docs.corsair.dev/plugins/telnyx/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/telnyx/api.md)
>
> Every `telnyx.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.