X-API-KEY, which keeps it out of URLs and logs; TelTEL also accepts the same key as an apikey query value.
Things to know before you call:
- Sending charges the account.
sms.send,sms.sendBulkandcalls.createbill per message part or per minute. There is no test mode. - The sender must be verified. A numeric sender must be a DID on the account, and an alphanumeric sender ID must be 3 to 11 characters. Dynamic sender IDs need to be enabled on the account first.
- Every body is wrapped in
data. TelTEL refuses an unwrapped request body, so each endpoint builds the wrapper for you. The bulk routes take an array as thedatavalue rather than an object. - Bulk sends can partly fail.
sms.sendBulkanswers 200 with the created IDs, or 207 with asuccessarray and anerrorsarray. Both parse, so a partial result does not throw. Checkdatafor the split on a 207. - 401 and 403 mean different things. A 401 means no credential reached the API. A 403 means one was sent and refused, or the account cannot use that section yet (a new account without credit gets 403 on SMS, campaigns and contacts). Errors are core’s
ApiError;teltelErrorDetails(error)reads TelTEL’serrorsentries. - Filters go in one
filtervalue. The list inputs (state,from,to,direction, the time ranges and so on) become a comma-separatedfilterquery value such asstate=DONE,created_at>2024-03-01T00:00:00. TelTEL ignores filters sent as separate query keys. - Users come without their API keys. TelTEL’s user list includes each user’s key;
users.listdrops that field before returning. - Paging is by offset.
limitruns from 1 to 5000 and defaults to 500;offsetskips. A list answer is{ data: [...] }with no total count, so keep requesting until a page comes back short. - Deletes and most updates answer
meta. A delete is{ meta: { deleted: true } }and a campaign, contact or group update is{ meta: { updated: true } }. The plugin returns that envelope rather than inventing asuccessflag, and fails a call whose body has nometa.numbers.updateis the exception: it answers with the updated number underdata. - A campaign does not send until it starts.
campaigns.createonly records the campaign.campaigns.actionwithstartsends to every contact in the campaign groups,pausestops it temporarily andstopends it. - A click-to-call needs both display names.
calls.createrequiresdestination_displaynamealongside the two numbers.
- 34 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 TelTEL API key before the first call: More: API Key
pnpm corsair setup --plugin=teltel --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
Read the account balanceWhat’s next
API reference
Every
teltel.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.