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.sendbills per message part, andcalls.createbills per minute from the moment the call is answered. There is no sandbox. - A sender is required, in one of two forms. Send
fromfor a phone number or alphanumeric sender ID, or sendmessaging_profile_idand 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_urlsis rejected before the request, because Telnyx refuses it too. - Paging uses bracketed keys.
page[number]andpage[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, andlimitis one of those filters rather than a top-level value. - Responses are wrapped. Every answer is
{ data }, and a list addsmetawithtotal_pages,total_results,page_numberandpage_size. The one exception ismessages.delete, which answers with the bare message. - Sends, dials and live-call actions are destructive.
messages.send,calls.create,calls.speakandcalls.hangupbill the account, reach a person or cannot be undone.calls.speakneedspayloadandvoice;languageis optional. messages.deletecancels a scheduled message. It only works on a message sent withsend_atthat has not gone out yet.- Number settings.
phoneNumbers.updatechanges 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.createtakes aconnection_id, which is the ID of a call control application. Create one withcallControlApplications.create, which requires awebhook_event_urlbecause Telnyx sends every call event there. - Releasing a number is permanent.
phoneNumbers.deletegives 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.20100is “Insufficient Funds”, which no retry fixes.
- 22 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Telnyx API key before the first call: More: API Key
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.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.
Example API calls
List the numbers on the accountWhat’s next
API reference
Every
telnyx.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.