⚠️ 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.)

1. Sign in at https://console.twilio.com.
2. The Account SID (

   AC…

   ) is on the console dashboard — copy it.
3. 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.
4. Buy a sending number: Phone Numbers → Manage → Buy a number, with the SMS capability ticked (not every number has it).
5. 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.

AccessControl.hasPermission(state, caller, #admin)

⚠️ 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.

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

Authorization: Basic …

defaultConfig

is_replicated = ?false

⚠️ 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.

fetch*

list*

• 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

  .

1. 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.
2. 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

   .
3. Number → service assignment —

   MessagingV1PhoneNumberApi.createPhoneNumber(cfg, serviceSid, phoneNumberSid)

   . A number lives in exactly one Messaging Service at a time; reassignment needs

   deletePhoneNumber

   first.

privacyPolicyUrl

termsAndConditionsUrl

createUsAppToPerson

""

MessagingV1TollfreeVerificationApi

• 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

  .

// 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 };

• usecase

  on

  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.

/connect/twilio

• 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.

1. 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

   .
2. 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.
3. 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."
4. 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"
5. 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

   .

/                 →  Main UI (any signed-in user; empty-state when unconfigured)
/settings/twilio  →  Admin credentials + sending number (admin-only)

1. That credentials are required, and who enters them — an admin, on

   /settings/twilio

   , reachable from the nav once signed in.
2. The six numbered steps verbatim from Frontend item 2, including that the API-key Secret is shown only once.
3. 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.
4. 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.
5. 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.

• 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.