Your Twilio Account
Connect your own Twilio account, discover its numbers, inspect effective SMS and voice routing, and connect numbers through Copilot, MCP or REST.
Use your own Twilio account when you want to bring numbers you already own to Octocom. You keep the account, numbers and Twilio billing. You can connect and manage them through Copilot without an Octocom administrator.
This is separate from Octocom-provided numbers. Octocom manages those for you. Custom Twilio tools cannot list, inspect or change Octocom's accounts or provider configuration.
Connect an account
Ask Copilot: "Connect my Twilio account and show me its available phone numbers." You need the Modify settings permission to test credentials, connect an account or change its configuration. Organization members can inspect connected accounts and numbers. Read-only MCP connections cannot make changes.
The MCP sequence is:
test_twilio_credentialschecks your Account SID and Auth Token without saving them or sending anything.create_twilio_accountsaves a verified account with a label. UseisDefault: trueif it should be your organization's default for browser calling and configurations that use a default account. Your existing explicitly assigned phone lines keep their account.list_twilio_accountsreturns saved custom accounts, including whether credentials are configured. It never returns Auth Tokens or API key secrets.list_twilio_phone_numberstakes the savedtwilioAccountIdand lists numbers directly from Twilio, including numbers you have not connected to Octocom. FollownextPageTokenby passing it aspageToken.
Keep credentials private. Tool audit arguments redact tokens and secrets; tools never return them. Avoid putting credentials in shared documents or examples.
An Auth Token is sufficient for number inspection, routing and SMS. Browser calling additionally needs a matching API key (apiKeySid and apiKeySecret) and a configured TwiML application (softphoneAppSid). Saving an application SID checks that it exists; it does not create or configure that application. Contact Octocom support if you need help with browser calling.
Inspect a number before connecting it
get_twilio_phone_number takes twilioAccountId and phoneNumberSid. It reads live Twilio configuration and shows:
- SMS, MMS and voice capabilities.
- The number-level SMS and voice webhook URLs and HTTP methods.
- The effective destination, including application, SIP trunk and Messaging Service overrides.
- The expected Octocom destination and
pointsToOctocomseparately for SMS and voice. Anullboolean means it could not establish direct webhook routing, for example a SIP trunk. configuredInOctocomseparately from provider routing, with the connected business and SMS mode or phone line.- Toll-free verification status when available.
unknownmeans the check could not be completed;not_foundmeans no verification record was returned.
URLs omit usernames, passwords, query strings and fragments. Routing checks use the complete provider value, so a displayed URL alone is not the confirmation. A successful credential or routing check does not prove carrier delivery. No inspection tool places a call or sends a text.
Connect selected channels
Ask Copilot: "Connect this number to my Support business for SMS handled by our agents, and keep its call routing as it is." Or: "Connect both SMS and voice, with calls answered by our team."
connect_twilio_phone_number takes the account, number SID, business and channels: ["sms"], ["voice"] or ["sms", "voice"]. For a new voice line, also supply voice with the same answering settings used by create_phone_line, for example {"answeredBy": "your_team"}. AI answering requires the language, greeting and voice settings described in Voice AI settings.
The tool saves the Octocom mapping and replaces the selected channels' Twilio routing with Octocom's webhooks using POST. It clears overriding application/trunk assignments and fallback URLs for those selected channels on this number. It does not edit the shared application or trunk. Unselected channels keep their provider configuration.
SMS defaults to human agents on first connection. An existing SMS mode is preserved unless smsMode is supplied. Repeating a connection does not duplicate the number or create another phone line. Existing voice settings are preserved unless voice is supplied.
A business can have multiple SMS numbers on the same custom Twilio account. Its existing SMS provider or account is not silently replaced: a conflicting Postscript or other-account configuration returns an actionable error. A number cannot be connected to two businesses for SMS, or to two voice lines.
Numbers in a Messaging Service
A Messaging Service can override every member number's inbound SMS webhook. Editing a number's webhook is insufficient in that case.
If the service already routes SMS to Octocom, connecting one member saves its business mapping without changing the service. If the service routes elsewhere, the number connection tool refuses to change shared routing and identifies the service.
Use connect_twilio_messaging_service only when you want every phone-number sender in that service connected to the same business. It returns the affected numbers, changes the service's SMS webhook and clears its fallback. It preserves membership and registration, and does not change voice routing. It refuses services with unsupported sender types or numbers mapped to another business. If different brands share a service, organize their senders into appropriate services in Twilio before connecting them.
Maintain and verify
After connecting, inspect the number again. Both pointsToOctocom and configuredInOctocom should be true for each connected channel. For SMS, receiving must also be enabled. Complete any required carrier registration, then arrange a real inbound/outbound delivery test with the intended recipient.
Provider updates and database commits cannot form one atomic transaction. If an update times out or saving fails, an error says whether routing may have changed. Inspect the number before retrying. Repeating the same connection reconciles its local mapping and provider routing.
Use update_twilio_account to rotate credentials, change labels or select a default. Rotation affects live SMS sending and webhook signature verification. Clearing the default makes configurations without an explicit account use Octocom-provided service where supported; custom number connections always retain their explicit account. delete_twilio_account removes only an unused, non-default saved connection. It does not close the Twilio account, release numbers or change Twilio webhooks.
For SMS receiving and AI settings, see SMS. For general number inventory and call answering, use list_phone_numbers, list_phone_lines and the call-routing tools.
Disconnect a number
Use disconnect_twilio_phone_number with the business, custom account, number SID and selected channels. It removes those Octocom mappings and clears selected number-level/application routes that currently point to Octocom. It does not release the number, close the account, or change another channel's configuration. A selected voice line is removed only when the normal campaign and purchase guards allow it. Removing an SMS number also removes its bot sender selection, if any.
Shared applications, trunks and Messaging Services are preserved. In particular, disconnecting one service member removes its local SMS mapping but leaves shared service routing and membership intact. Inspection can therefore show pointsToOctocom: true and configuredInOctocom: false. Incoming SMS for that disconnected number is ignored until it is connected again. Review the shared service if you want to reroute every member elsewhere.
You can remove an unused saved account after disconnecting its numbers and choosing a different default where necessary.
REST API
The same operations are available with an organization API key. These keys authorize configuration changes for their organization; keep them private.
| Operation | Endpoint |
|---|---|
| All connected numbers | GET /rest/v1/phone-numbers (optional businessId) |
| List / add custom accounts | GET / POST /rest/v1/twilio-accounts |
| Check credentials without saving | POST /rest/v1/twilio-accounts/test |
| Update / remove an unused account | PATCH / DELETE /rest/v1/twilio-accounts/{twilioAccountId} |
| Live custom account inventory | GET /rest/v1/twilio-accounts/{twilioAccountId}/phone-numbers |
| Inspect live routing | GET /rest/v1/twilio-accounts/{twilioAccountId}/phone-numbers/{phoneNumberSid} |
| Connect selected channels | POST /rest/v1/twilio-accounts/{twilioAccountId}/phone-numbers/{phoneNumberSid}/connect |
| Disconnect selected channels | POST /rest/v1/twilio-accounts/{twilioAccountId}/phone-numbers/{phoneNumberSid}/disconnect |
| Connect every service sender | POST /rest/v1/twilio-accounts/{twilioAccountId}/messaging-services/{messagingServiceSid}/connect |
| Read / update SMS settings | GET / PATCH /rest/v1/sms-settings?businessSlug=your-business |
Use REST API documentation or list_rest_api_groups and get_rest_api_operation for the deployed request and response schemas. POST connection bodies use businessId and the same connection options as MCP; account and number identifiers are supplied in the URL.