Twilio Connector (experimental)

Send SMS / MMS and configure Twilio messaging from a Caffeine canister.

⚠️ Experimental (
twilio-client@0.1.2
) — no call has ever been made from this client. Its write path could work at all only recently: before, every write discarded its arguments and posted an empty body. The wire format now matches what Twilio documents (form-encoded body, percent-encoded values, optional fields omitted) and all 118 files typecheck, but structurally correct is not verified. Treat the first successful send as the acceptance test, and do not present Twilio to a user as a fully supported platform feature until one has happened. Sends cost money, so a failed experiment is not free.

Scope — the package is the messaging surface only.
twilio-client
is pruned to 35 API modules (all of Messaging v1 plus the v2010 messaging path: Account, Message, Media, IncomingPhoneNumber and its variants, AvailablePhoneNumber, the A2P registries). Voice/calls, recordings, conferences, queues, applications, SIP and usage records are not in the package — if a build needs those, they are outside this connector. (Counts: 35 API modules, 82 models, 118 files, all typechecking.)

Orchestrator routing notes

Load this skill when the user, spec, or a prior task mentions sending a text message, SMS/MMS, notifying someone by phone, buying or listing phone numbers, or any Twilio messaging concept. Raw

ic.http_request

*.twilio.com

is an anti-pattern that re-implements auth, host routing, percent-encoding and JSON parsing by hand — and, done naively, sends every message ~13 times.

Intent → capability mapping:

User intent	Capability
Send an SMS	`Api20100401MessageApi.createMessage` with `from` = a Twilio number
Send an MMS (image)	same, with `mediaUrl = ["https://…"]` and `sendAsMms = true`
Send via a Messaging Service (recommended for US traffic)	same, `from = ""` + `messagingServiceSid`
Check delivery status	`fetchMessage` ( `status` , `error_code` )
List / search sent messages	`listMessage` (paginated)
Own or browse phone numbers	`Api20100401IncomingPhoneNumberApi` , `…AvailablePhoneNumberCountryApi`
Set up a Messaging Service	`MessagingV1ServiceApi.createService`
Register for US A2P 10DLC	`MessagingV1BrandRegistrationApi` → `MessagingV1UsAppToPersonApi` → `MessagingV1PhoneNumberApi` (in that order — see US A2P 10DLC)
Verify a toll-free number	`MessagingV1TollfreeVerificationApi`

Twilio credentials are something a human must go and fetch from a console, so the build is not done when the backend compiles — it is done when the app tells the admin where to get the credential and gives them somewhere to paste it. See Auth model, then Frontend for the page that MUST ship, and repeat the steps in the completion message.

Ask before writing code: which number sends? A US-bound production app needs a Messaging Service + A2P registration (weeks of lead time, real fees); a demo/internal app can send from a single trial number to verified recipients only. Report the choice and its consequences back to the prompting user.

Auth model — HTTP Basic, two flavours

Both flavours are the same

#basicAuth { user; password }

credential and the client treats them identically; they differ in blast radius.

Flavour	`user` / `password`	When
API Key (default — prefer this)	API Key SID ( `SK…` ) / its Secret	Production. Revocable and scoped: leaking one does not surrender the account.
Account SID + Auth Token	Account SID ( `AC…` ) / Auth Token	Dev only. The Auth Token is the account — it can create sub-accounts, buy numbers, and spend money.

The Account SID (

AC…

) is also a required positional argument to every v2010 operation (it is in the URL path), regardless of which flavour is used. So an app using an API Key stores three values: Account SID, Key SID, Key Secret.

Obtaining credentials

Sign in at https://console.twilio.com.
The Account SID (
```
AC…
```
) is on the console dashboard — copy it.
For production, Account → API keys & tokens → Create API key (Standard); copy the SID (
```
SK…
```
) and the Secret. The Secret is shown once — if the admin navigates away it cannot be recovered, only replaced. For dev only, take the Auth Token from the dashboard instead.
Buy a sending number: Phone Numbers → Manage → Buy a number, with the SMS capability ticked (not every number has it).
On a trial account: verify each recipient under Phone Numbers → Verified Caller IDs, or sends fail with
```
21608
```
; trial messages also carry a "Sent from your Twilio trial account" prefix.

Handing the credentials to the canister

The admin pastes them through an admin-gated setter — gated on

AccessControl.hasPermission(state, caller, #admin)

. They are held by the canister only and never returned to the frontend.

⚠️ Never gate the setter on a first-caller-claims-ownership scheme. On the IC every unauthenticated caller is the same anonymous principal, so if an anonymous call claims ownership first, every anonymous caller passes the
caller == owner
check and can overwrite the credential — and this one spends money.

The canister hands them to the client only through

config.auth = ?#basicAuth { user; password }

, which every method turns into an

Authorization: Basic …

header. No method takes a credential argument and none puts it in the URL, so it cannot leak through a logged query string.

Outcalls are already non-replicated — and this CORRECTS earlier guidance

defaultConfig

ships

is_replicated = ?false

, so anything derived from it by record update is correct as-is. Nothing to remember, nothing to add.

⚠️ Do not set it to
?true
or
null
, and disregard any older advice to do so. An older version of this SKILL claimed writes should stay replicated "so IC consensus dedups retries". That is false and expensive. A replicated outcall is performed by every node in the subnet: the request is sent ~13 times, so ~13 SMS are sent and ~13 are billed, the credential leaves every node, and consensus fails anyway because Twilio stamps each reply with a unique
sid
(so the responses never agree byte-for-byte). This is the same defect that produced ~13 duplicate emails via the Gmail connector and drove
slack-client
0.1.0.

Reads (

fetch*

list*

) are equally fine non-replicated: one node's view of a message log is what you want, and it is the cheaper path.

Backend

Add dependencies

The admin gate in the recipe below needs the authorization component alongside the client:

bash

mops add twilio-client@0.1.2
mops add caffeineai-authorization@1.0.1

Calling shape — free functions or the class facade

Every module offers both. The free function takes

config

first and is

async*

; the

module class

captures

config

and is

async

motoko

// Illustrative sketch, not a file to copy: `cfg`/`accountSid` are assumed to
// exist and the argument lists are elided. Marked motoko-check:skip for that
// reason — the compiled examples are the three mixins below.
import MessageApi "mo:twilio-client/Apis/Api20100401MessageApi";

// free function — config passed explicitly
let m = await* MessageApi.createMessage(cfg, accountSid, /* … */);

// class facade — config captured once
let messages = MessageApi.Api20100401MessageApi(cfg);
let m2 = await messages.createMessage(accountSid, /* … */);

All parameters are positional and there are 27 of them on
createMessage
. Pass

""

false

0.0

[]

/ null
for the ones you do not use — the optional enum parameters are

?T

precisely so that

null

omits them from the wire. Count carefully; a misplaced empty string silently sends the wrong field. The order is:

config, accountSid, to, statusCallback, applicationSid, maxPrice, provideFeedback, attempt, validityPeriod, forceDelivery, contentRetention, addressRetention, smartEncoded, persistentAction, trafficType, shortenUrls, scheduleType, sendAt, sendAsMms, contentVariables, riskCheck, from, fallbackFrom, messagingServiceSid, body, mediaUrl, contentSid

The recipe

motoko

import AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";
import MixinTwilioConfig "mixins/twilio-config";
import MixinTwilioMessaging "mixins/twilio-messaging";

actor {
  let accessControlState = AccessControl.initState();
  include MixinAuthorization(accessControlState, null);

  // Admin-held Twilio credentials — never returned to the frontend.
  let twilioConfig = {
    var accountSid : Text = "";   // AC… — also a positional arg on every v2010 call
    var keySid : Text = "";       // SK… (or the Account SID again, in dev)
    var keySecret : Text = "";    // the API-key secret (or the Auth Token, in dev)
    var fromNumber : Text = "";   // E.164, e.g. "+15551234567"
  };
  include MixinTwilioConfig(accessControlState, twilioConfig);
  include MixinTwilioMessaging(twilioConfig);
};

motoko

import AccessControl "mo:caffeineai-authorization/access-control";
import Runtime "mo:core/Runtime";

mixin (
  accessControlState : AccessControl.AccessControlState,
  twilioConfig : {
    var accountSid : Text;
    var keySid : Text;
    var keySecret : Text;
    var fromNumber : Text;
  },
) {
  // All THREE are required, and this must agree with the guard in
  // twilio-messaging.mo: `keySid` is the Basic-Auth *username*, so a blank one
  // means every request goes out unauthenticated and Twilio answers 20003 —
  // while the UI cheerfully reports "Configured".
  public query func isTwilioConfigured() : async Bool {
    twilioConfig.accountSid.size() > 0 and twilioConfig.keySid.size() > 0 and twilioConfig.keySecret.size() > 0;
  };

  // The sending number is not a secret — the UI may display it.
  public query func getTwilioFromNumber() : async Text {
    twilioConfig.fromNumber;
  };

  // Admin-only. NOTE `#admin` — never a first-caller-claims-ownership check,
  // which the shared anonymous principal would defeat.
  public shared ({ caller }) func setTwilioCredentials(
    accountSid : Text,
    keySid : Text,
    keySecret : Text,
  ) : async () {
    if (not AccessControl.hasPermission(accessControlState, caller, #admin)) {
      Runtime.trap("Unauthorized: Only admins can set Twilio credentials");
    };
    twilioConfig.accountSid := accountSid;
    twilioConfig.keySid := keySid;
    twilioConfig.keySecret := keySecret;
  };

  public shared ({ caller }) func setTwilioFromNumber(number : Text) : async () {
    if (not AccessControl.hasPermission(accessControlState, caller, #admin)) {
      Runtime.trap("Unauthorized: Only admins can set the sending number");
    };
    twilioConfig.fromNumber := number;
  };
};

motoko

import Principal "mo:core/Principal";
import Runtime "mo:core/Runtime";
import { createMessage } "mo:twilio-client/Apis/Api20100401MessageApi";
import { defaultConfig; type Config } "mo:twilio-client/Config";

mixin (
  twilioConfig : {
    var accountSid : Text;
    var keySid : Text;
    var keySecret : Text;
    var fromNumber : Text;
  },
) {
  // Credentials ride config.auth; defaultConfig is already non-replicated.
  func twilioClientConfig() : Config {
    {
      defaultConfig with
      auth = ?#basicAuth { user = twilioConfig.keySid; password = twilioConfig.keySecret };
      max_response_bytes = ?(200_000 : Nat64);
    };
  };

  /// Send an SMS to `to` (E.164). Returns the message SID.
  public shared ({ caller }) func sendSms(to : Text, body : Text) : async Text {
    if (caller.isAnonymous()) Runtime.trap("Sign in to send messages");
    // Same three-way check as isTwilioConfigured(): accountSid goes in the URL
    // path, keySid is the Basic-Auth user, keySecret the password. Missing any
    // one of them fails at Twilio, not here, so check before spending cycles.
    if (
      twilioConfig.accountSid.size() == 0 or twilioConfig.keySid.size() == 0 or twilioConfig.keySecret.size() == 0
    ) {
      Runtime.trap("Twilio is not configured (an admin must set all three credentials)");
    };
    let msg = await* createMessage(
      twilioClientConfig(),
      twilioConfig.accountSid, // accountSid — in the URL path, not the credential
      to,                      // to (E.164)
      "", "",                  // statusCallback, applicationSid
      0.0,                     // maxPrice (0 = no cap)
      false,                   // provideFeedback
      0, 0,                    // attempt, validityPeriod
      false,                   // forceDelivery
      null, null,              // contentRetention, addressRetention (omitted)
      false,                   // smartEncoded
      [],                      // persistentAction
      null,                    // trafficType (omitted)
      false,                   // shortenUrls
      null,                    // scheduleType — MUST be null for an immediate send
      "",                      // sendAt (scheduled sends only)
      false,                   // sendAsMms
      "",                      // contentVariables
      null,                    // riskCheck (omitted)
      twilioConfig.fromNumber, // from  (use EITHER from OR messagingServiceSid)
      "",                      // fallbackFrom
      "",                      // messagingServiceSid
      body,                    // body
      [],                      // mediaUrl (set for MMS)
      "",                      // contentSid (Content API templates)
    );
    // `sid` is optional in the generated model because the spec marks it
    // nullable, though Twilio always sets it on a successful create. Fall back
    // to "" rather than trapping: the outcall has already happened, so a trap
    // would roll back this canister's own state while the SMS stays delivered.
    switch (msg.sid) { case (?sid) sid; case null "" };
  };
};

For MMS:

mediaUrl = ["https://example.com/image.jpg"]

and

sendAsMms = true

. To send through a Messaging Service, leave

from = ""

and set

messagingServiceSid

instead.

Addressing — E.164, and which sender

to
must be E.164:
```
+
```
, country code, no spaces, dashes or parentheses —
```
"+15551234567"
```
.
```
"555-1234"
```
fails with
```
21211
```
. Normalize in the frontend and again in the canister; do not trust either alone.
from
vs
messagingServiceSid
— exactly one. Setting both is an error. A bare
```
from
```
number is fine for non-US traffic and demos; US-bound production traffic should go through a Messaging Service (sender pool, sticky sender, and it is what A2P registration attaches to).
The sending number needs the SMS capability, which not every purchasable number has. Filter on it when browsing
```
Api20100401AvailablePhoneNumberCountryApi
```
.

US A2P 10DLC — three resources, in this order

Before any US long code can text US destinations, all three must exist. Without them US carriers reject the traffic outright.

Brand registration —
```
MessagingV1BrandRegistrationApi.createBrandRegistrations
```
, referencing Trust Hub
```
customerProfileBundleSid
```
+
```
a2PProfileBundleSid
```
(created out of band). Pass
```
mock = true
```
in dev to skip the fee. Status starts
```
PENDING
```
and settles to
```
APPROVED
```
/
```
FAILED
```
over hours to days; it fails if business details are incomplete, inconsistently formatted, or do not match registry data.
A2P campaign —
```
MessagingV1UsAppToPersonApi.createUsAppToPerson
```
, referencing both the Messaging Service and the brand. Most onboarding failures land here. T-Mobile rejects campaigns whose
```
messageFlow
```
does not describe opt-in, or whose
```
messageSamples
```
do not match the declared
```
usAppToPersonUsecase
```
.
Number → service assignment —
```
MessagingV1PhoneNumberApi.createPhoneNumber(cfg, serviceSid, phoneNumberSid)
```
. A number lives in exactly one Messaging Service at a time; reassignment needs
```
deletePhoneNumber
```
first.

Registration deadline in force: campaigns without working

privacyPolicyUrl

and

termsAndConditionsUrl

hard-400 since 2026-06-30. Both are positional arguments on

createUsAppToPerson

and

""

fails; the URLs must resolve to public HTTPS pages, because Twilio fetches them during registration.

Toll-free numbers use a separate flow —

MessagingV1TollfreeVerificationApi

— not A2P.

Available API surface

Documented and messaging-focused (this recipe):

Module	For
`Api20100401MessageApi`	send / fetch / list / update / delete messages
`Api20100401MediaApi` , `…MediaInstanceApi`	MMS media on a message
`Api20100401IncomingPhoneNumberApi` (+ `Local` / `Mobile` / `TollFree` )	numbers you own; delete = release
`Api20100401AvailablePhoneNumberCountryApi`	browse numbers to buy
`Api20100401BalanceApi` , `…AccountApi`	account balance and account records
`Api20100401UserDefinedMessageApi` (+ `Subscription` )	user-defined message events
`MessagingV1ServiceApi`	Messaging Services (sender pools)
`MessagingV1BrandRegistrationApi` (+ `Otp` , `BrandVettingApi` )	A2P brand
`MessagingV1UsAppToPersonApi` (+ `UsecaseApi` )	A2P campaigns
`MessagingV1PhoneNumberApi` , `…ShortCodeApi` , `…AlphaSenderApi` , `…ChannelSenderApi`	sender pool membership
`MessagingV1TollfreeVerificationApi`	toll-free verification
`MessagingV1Linkshortening` , `…DomainConfig` , `…DomainCertsApi`	branded link shortening
`MessagingV1DeactivationsApi`	carrier deactivation list

Not in the package (pruned from the generated surface): calls, recordings, conferences, participants, queues, applications, SIP domains and credentials, usage records and triggers, addresses, keys, tokens, balance transactions. The package ships the messaging surface only — for anything above, this connector is not the path.

Errors and pagination

Methods return the decoded record on 2xx and
```
throw Error.reject("HTTP <status> body[…]: …")
```
on 4xx/5xx.
```
diagnostics
```
is on, so the reject text carries Twilio's own error body (
```
code
```
,
```
message
```
,
```
more_info
```
). Wrap in
```
try { … } catch (e) { Error.message(e) }
```
.
Codes worth mapping to real UI text: 20003 authenticate failed (bad credential), 21211 invalid
```
To
```
, 21408 region not permissioned (enable the destination country's geo permissions in the console), 21608 unverified recipient on a trial account, 21610 recipient has unsubscribed (STOP), 21703 sender pool exhausted, 21704 the Messaging Service has no numbers, 21714 pool size capped.
A 2xx does not mean delivered.
```
createMessage
```
returns
```
status = #queued
```
or
```
#accepted
```
; delivery is asynchronous. Poll
```
fetchMessage
```
for
```
#delivered
```
/
```
#undelivered
```
/
```
#failed
```
and read
```
error_code
```
, or configure a
```
statusCallback
```
URL (needs an inbound HTTP endpoint — out of scope here).
Pagination differs between the two API versions. v2010 lists —
```
listMessage
```
and every other
```
Api20100401*
```
list — return top-level
```
next_page_uri
```
/
```
previous_page_uri
```
(
```
?Text
```
, and a path such as
```
/2010-04-01/…
```
, not a full URL). Messaging v1 lists (
```
listService
```
,
```
listPhoneNumber
```
, the A2P registries) instead nest pagination under
```
meta
```
, as
```
next_page_url
```
/
```
previous_page_url
```
(full URLs) plus
```
page_size
```
. Only 10 of the 70 list responses use the
```
meta
```
form;
```
listMessage
```
is not one of them. The
```
meta
```
field is typed
```
?ListAlphaSenderResponseMeta
```
on every v1 list, including
```
ListServiceResponse
```
— identical records are deduplicated to one shared module at codegen time, so the name reflects whichever list sorted first, not the endpoint you called.
```
pageSize
```
defaults to 50 and caps at 1000. Bound every list call — an unbounded
```
listMessage
```
on a busy account will blow
```
max_response_bytes
```
.

Reading the two shapes:

motoko

// Illustrative sketch, not a file to copy — `res` is assumed to be the decoded
// list response. Marked motoko-check:skip for that reason.

// v2010 (listMessage and every other Api20100401* list): top-level, a path
switch (res.next_page_uri) { case (?path) { /* fetch the next page */ }; case null {} };

// Messaging v1 (listService, listPhoneNumber, the A2P registries): nested, a full URL
switch (res.meta) { case (?m) { m.next_page_url }; case null null };

Field gotchas

usecase

createService

is Text
, not a variant. Valid:

notifications

marketing

verification

discussion

poll

undeclared

. Anything else 400s.

```
usAppToPersonUsecase
```
is a different, brand-tier-dependent enum — query
```
MessagingV1UsAppToPersonUsecaseApi.fetchUsAppToPersonUsecase
```
for what a given brand may use.
Optional enum arguments are
?T
— pass
null
to omit them, and prefer that. The variants are closed:
```
contentRetention
```
```
#retain
```
/
```
#discard
```
,
```
addressRetention
```
```
#retain
```
/
```
#obfuscate
```
,
```
trafficType
```
```
#free
```
,
```
scheduleType
```
```
#fixed
```
,
```
riskCheck
```
```
#enable
```
/
```
#disable
```
. There is no
#Text
escape hatch — a value the spec does not list cannot be expressed. Passing
```
?#fixed
```
for
```
scheduleType
```
on an immediate send is a 400: Twilio reads it as a scheduled message and then finds no
```
SendAt
```
.
```
null
```
is the correct value for every one of these unless you specifically want the behaviour.
maxPrice
is omitted when
0.0
, which is what you want. Sending
```
MaxPrice=0
```
would cap the message price at zero and make Twilio refuse paid delivery; omitting it means "no cap". Pass
```
0.0
```
to omit.
```
xTwilioApiVersion
```
(on the
```
UsAppToPerson
```
methods) — pass
```
""
```
unless Twilio support asks otherwise.
Throughput is per sender: long code 1 message/second, toll-free ~3, international long code ~10, short code 100. Per-number MPS cannot be raised — scale by adding numbers to the Messaging Service's sender pool.
```
stickySender
```
/
```
areaCodeGeomatch
```
are US + Canada only.
```
Config.baseUrl
```
is unused. Every operation carries a hardcoded host (
```
api.twilio.com
```
for v2010,
```
messaging.twilio.com
```
for v1), pinned at codegen time from the merged spec. Do not set it and do not expect it to redirect traffic.

Frontend

Twilio needs no OAuth: the credential is a long-lived pair the admin pastes, so there is no redirect URI, no

/connect/twilio

route, and no per-user handshake. Do not build one. What a Twilio build MUST ship is the page that lets the admin get and enter the credentials — acceptance criteria, not suggestions; a build missing them is broken, not merely incomplete:

The credentials page exists and is reachable. A "send SMS" feature with nowhere to enter a credential is unusable. A signed-in admin must reach
```
/settings/twilio
```
from the nav or from the not-configured prompt.
The console steps are in the UI, not only in the chat reply — the admin returns weeks later, after the chat is gone.
The API-Key secret is shown once by Twilio. Say so next to the input, or admins will navigate away and have to create a second key.

A login flow — required.
```
setTwilioCredentials
```
gates on
```
#admin
```
, so the app needs non-anonymous callers. Take login,
```
useInternetIdentity
```
/
```
useActor
```
plumbing and the admin-role gate from
extension-authorization
.
An admin settings page —
```
/settings/twilio
```
(admin-gated). Required:
- A "How to get your Twilio credentials" panel above the inputs, framed as a one-time ~5-minute setup, with these numbered steps (the completion message must repeat them verbatim):
  1. sign in at https://console.twilio.com;
  2. copy the Account SID (
    AC…
    ) from the dashboard;
  3. Account → API keys & tokens → Create API key (Standard); copy the SID (
    SK…
    ) and the Secret — the Secret is displayed only once;
  4. Phone Numbers → Manage → Buy a number with the SMS capability;
  5. paste the three values plus the number below and save;
  6. on a trial account, verify each recipient under Verified Caller IDs. Include a convenience link that opens the Twilio console.
- Three inputs: Account SID (plain text — not a secret), Key SID, Key Secret (password input). Bound to
```
setTwilioCredentials
```
  ; clear the secret on success; keep the form re-submittable, because keys get rotated.
- A sending-number field bound to
```
setTwilioFromNumber
```
  , with an E.164 example (
```
+15551234567
```
  ) beside it and client-side validation.
- Status driven by
```
isTwilioConfigured()
```
  (
```
Bool
```
  ) — "Configured" / "Not configured". That predicate requires all three values, Key SID included: it is the Basic-Auth username, so a blank one means every request is unauthenticated and Twilio answers
```
20003
```
  while the page claims to be configured. Never render the secret back, not even masked. The sending number may be displayed (
```
getTwilioFromNumber
```
  ); it is not a secret.
- Make the page reachable. The shared Layout nav MUST link here when
```
isCallerAdmin
```
  is true and hide it otherwise. Add the link where the nav is defined, not inside this page.
Empty-state nudges. When
```
isTwilioConfigured()
```
is
```
false
```
, never render a dead "Send" button: admins get a "Set up Twilio" link to
```
/settings/twilio
```
; non-anonymous non-admins get an explanation — e.g. "Texting isn't set up yet — an administrator needs to add Twilio credentials in Settings."
Translate Twilio's errors. Failures arrive as rejected calls carrying Twilio's
```
code
```
. Map at least these to an action rather than showing the raw reject:
- ```
20003
```
  → "The Twilio credentials are wrong — an admin should re-paste them"
- ```
21211
```
  → "That phone number isn't valid — use the +15551234567 format"
- ```
21408
```
  → "Texting that country isn't enabled on this Twilio account"
- ```
21608
```
  → "On a trial account the recipient must be verified in Twilio first"
- ```
21610
```
  → "That number has replied STOP and cannot be texted"
Never promise delivery. A successful call means queued, not delivered. Word the UI accordingly ("Message queued") and, if delivery matters, show the polled
```
status
```
from
```
fetchMessage
```
.

Suggested route layout:

/                 →  Main UI (any signed-in user; empty-state when unconfigured)
/settings/twilio  →  Admin credentials + sending number (admin-only)
# No /connect/twilio: Twilio uses pasted long-lived credentials, not a redirect flow.

What the composer must tell the Caffeine user

The app cannot send anything until a human creates a Twilio account, buys a number and pastes credentials — so the completion message is part of the deliverable, not a summary of it. It MUST contain, in this order:

That credentials are required, and who enters them — an admin, on
```
/settings/twilio
```
, reachable from the nav once signed in.
The six numbered steps verbatim from Frontend item 2, including that the API-key Secret is shown only once.
That Twilio costs money — per-message pricing plus a monthly number fee, and that a trial account can only text verified numbers and prefixes every message with a trial notice.
For US-bound traffic: the A2P 10DLC requirement, named as weeks of lead time and additional fees, with the three ordered resources — otherwise the user will ship an app that silently fails to reach US phones.
The failure map, one line each:
```
20003
```
→ re-paste credentials;
```
21211
```
→ E.164 format;
```
21408
```
→ enable the destination country;
```
21608
```
→ verify the recipient (trial);
```
21610
```
→ recipient unsubscribed.

Do not compress this to "configure Twilio in Settings" and do not substitute a link to Twilio's documentation. Use the same wording here as in the settings-page panel so the two cannot drift.

Known limitations

Only the messaging surface is shipped. The package is pruned to the messaging path; voice/recordings/SIP/usage and the rest are not in it.
Inbound messages are out of scope. Receiving SMS, and
```
statusCallback
```
delivery receipts, need an inbound HTTP endpoint on the canister — a different component, not this client.
Binary media is not uploadable.
```
mediaUrl
```
takes a public URL Twilio fetches; the canister cannot POST image bytes through this client.
No idempotency key. Twilio's messaging API has none, so a retry after a timeout may send twice. Guard at the application level (a stable-variable dedupe key per logical send) rather than retrying blindly. The non-replicated default removes the ~13× amplification, not retry semantics.
One dropped field.
```
POST …/IncomingPhoneNumbers/{Sid}.json
```
accepts an
```
AccountSid
```
form field (used to move a number between subaccounts) while
```
AccountSid
```
is also its path parameter. The generator has a single namespace for both, so the form copy is dropped and transferring a number to a subaccount is not reachable through this client. Every other endpoint is unaffected.
Nothing here has been exercised against live Twilio. The wire format is at least structurally right — writes send an
```
application/x-www-form-urlencoded
```
body with percent-encoded parameters, which is what Twilio requires — but no call has been made. Treat a first successful send as the real acceptance test.
Spec vintage: generated from Twilio's published OpenAPI specs merged by
```
spec-merge
```
(Messaging v1 + API v2010), then pruned to the messaging surface. Newer Twilio features absent from those specs are absent here.

```
mops add twilio-client@0.1.2
```
— the generated Twilio REST bindings (35 messaging modules).
Twilio Messaging docs — the API this wraps.
```
chat
```
-free quickstart: sending SMS
— the
```
Message
```
resource, its fields and statuses.
Twilio error codes — the numeric codes surfaced in reject messages.
A2P 10DLC overview — brand, campaign, number assignment.
API keys vs Auth Token — why production uses
```
SK…
```
.
extension-authorization — required prerequisite. Internet Identity login,
```
useInternetIdentity
```
/
```
useActor
```
plumbing, and the
```
#admin
```
gate the credential setter needs.

connector-twilio

NPX Install

Tags

SKILL.md Content

Twilio Connector (experimental)

Orchestrator routing notes

Auth model — HTTP Basic, two flavours

Obtaining credentials

Handing the credentials to the canister

Outcalls are already non-replicated — and this CORRECTS earlier guidance

Backend

Add dependencies

Calling shape — free functions or the class facade

The recipe

Addressing — E.164, and which sender

US A2P 10DLC — three resources, in this order

Available API surface

Errors and pagination

Field gotchas

Frontend

What the composer must tell the Caffeine user

Known limitations

Related