Skip to content
← Public packages

@kody/twilio

Look up Twilio accounts, incoming numbers, and SMS logs, and send messages as a dry-run by default.

FollowFork

Files

AGENTS.md

105 lines · 3.3 KB · Markdown

@kody/twilio — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by name only — never paste SID or Auth Token values. Do not disable live webhooks or jobs (this package declares none). There is no Twilio OAuth path — do not open /connect/oauth for Twilio.

Secrets

NamePurpose
twilioAccountSidAccount SID (AC…); Basic username + REST path
twilioAuthTokenAuth Token; Basic password
twilioAccountSid-<label> / twilioAuthToken-<label>Extra account via account: "<label>" or explicit secret overrides

Host: api.twilio.com (approve for both secrets).

Import paths

ExportImport
overview / safety metadatakody:@kody/twilio
guidekody:@kody/twilio/guide
smoke-testkody:@kody/twilio/smoke-test
accountkody:@kody/twilio/account
incoming-numberskody:@kody/twilio/incoming-numbers
messageskody:@kody/twilio/messages
send-messagekody:@kody/twilio/send-message
configkody:@kody/twilio/config
requestkody:@kody/twilio/request

Prefer static kody:@kody/twilio/... imports from execute. Do not lead with packages.invoke. If a forked package runtime must bind the caller's secret mounts and a static import does not resolve placeholders, a dynamic invoke of bare kody id twilio with exportName: './smoke-test' is acceptable.

Smoke test (read-only)

Safe before credentials exist: returns { ok: true, live: false } and setup URLs. After both secrets and host approval, a live result is account + one page of numbers and message logs. It does not send SMS.

import smokeTest from 'kody:@kody/twilio/smoke-test'

export default async function main() {
	return await smokeTest()
}

Static overview (no secret mounts required):

import twilio from 'kody:@kody/twilio'

export default async function main() {
	return await twilio()
}

dryRun / confirm (sends)

send-message and other POST helpers default to dry-run. They return the Twilio form payload without calling the API unless confirm: true (and dryRun is not true). Live sends also need from or messagingServiceSid.

import sendMessage from 'kody:@kody/twilio/send-message'

export default async function main() {
	return await sendMessage({
		to: '+15555550100',
		from: '+15555550101',
		body: 'Hello from Kody',
	})
	// preview only
}

A live send only after explicit user approval of the exact destination and body:

import sendMessage from 'kody:@kody/twilio/send-message'

export default async function main() {
	return await sendMessage({
		to: '+15555550100',
		from: '+15555550101',
		body: 'Hello from Kody',
		confirm: true,
	})
}

Edge cases

  • No default sender. Pass from (E.164) or a Messaging Service SID. Optional Messaging Service SID may live in forked packageStorage() via ./config — never on the live @kody/twilio platform bucket.
  • Errors: 401 → save both secrets and approve api.twilio.com; 403 → SID and token must belong to the same account; 404 → confirm Account SID / path; 400 missing From → pass from or Messaging Service SID.
  • Keep LICENSE (MIT), ## Intent, and community-icon.svg for community listing.