{
  "schema": "aaes/capability-pack/1",
  "provider": "twilio",
  "version": "1.0.0",
  "description": "Twilio messaging and voice: read message logs and phone numbers, send SMS, and place calls under a consent gate.",
  "notes": "Use a Twilio API key or the account auth token with only the access these capabilities need; the pack does not create one. Sending an SMS and placing a call both reach a person outside AAES's control and cannot be taken back, so both carry the send action at the minimum R3 tier, and send is one of the designated actions requiring human approval. SMS is registered over the HTTP connector because the telephony connector models calls, not messages; the call capability uses the telephony connector, which refuses any call whose request carries no consent record reference, and whose dialed number must itself be in the capability's egress allowlist — the '+1REPLACE-WITH-CONSENTED-NUMBER' entry is a placeholder that passes nothing until the reviewer replaces it with the real consented E.164 numbers, so this capability fails closed as shipped. ACCOUNT_SID is a placeholder to replace in every endpoint.\n\nMessage bodies and phone numbers are personal data, so the pack registers at the pii class throughout; it says nothing about Twilio Verify, Lookup, recordings or transcription, which carry their own data classes. AAES has not been certified by Twilio; the endpoints here are configuration to review and test; the vendor has not endorsed it.",
  "credential": {
    "secret_ref_id": "secret-ref-twilio-auth-token",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "The Twilio account's HTTP Basic credential — an API key pair or the account SID and auth token — held in the client's own secret manager. Twilio authenticates the REST API with HTTP Basic, so the stored material must be the complete Authorization header value (scheme included): 'Basic ' followed by the base64 of ACCOUNT_SID:AUTH_TOKEN (or the API key SID and secret). Prefer an API key over the account auth token: a key can be revoked without rotating the account's root credential."
  },
  "capabilities": [
    {
      "capability_id": "twilio.messages.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.twilio.com"
      ],
      "endpoint": "https://api.twilio.com/2010-04-01/Accounts/ACCOUNT_SID/Messages.json",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-twilio-auth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "twilio-account",
      "description": "Read the account's message log. Message bodies and the numbers at both ends are personal data, so the read is classified as pii (personal data). ACCOUNT_SID is a placeholder to replace before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "twilio.messages.send",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.twilio.com"
      ],
      "endpoint": "https://api.twilio.com/2010-04-01/Accounts/ACCOUNT_SID/Messages.json",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-twilio-auth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "send"
      ],
      "resource_id": "twilio-account",
      "description": "Send an SMS. A message cannot be recalled after delivery, and send is one of the designated actions requiring human approval, which is why it carries the minimum R3 tier. The recipient's number is personal data and the body may carry more, so the capability registers classified as pii (personal data).",
      "requires_review": true
    },
    {
      "capability_id": "twilio.numbers.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.twilio.com"
      ],
      "endpoint": "https://api.twilio.com/2010-04-01/Accounts/ACCOUNT_SID/IncomingPhoneNumbers.json",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-twilio-auth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "twilio-phone-number",
      "description": "List the phone numbers the account holds. Phone numbers are personal data, so the read is classified as pii (personal data). ACCOUNT_SID is a placeholder to replace before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "twilio.calls.create",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.twilio.com",
        "+1REPLACE-WITH-CONSENTED-NUMBER"
      ],
      "endpoint": "https://api.twilio.com/2010-04-01/Accounts/ACCOUNT_SID/Calls.json",
      "method": "call",
      "connector": "telephony",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-twilio-auth-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "send"
      ],
      "resource_id": "twilio-phone-number",
      "description": "Place an outbound call. A call reaches a person and cannot be taken back, so the action is send at the minimum R3 tier; send is one of the designated actions requiring human approval. The telephony connector refuses a call whose request carries no consent record reference, and the dialed number must be in this capability's egress allowlist: replace '+1REPLACE-WITH-CONSENTED-NUMBER' with the real consented E.164 numbers, because the placeholder passes nothing. ACCOUNT_SID is a placeholder to replace before enabling.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "twilio-account",
      "kind": "api",
      "locator": "https://api.twilio.com/2010-04-01/Accounts/ACCOUNT_SID",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    },
    {
      "resource_id": "twilio-phone-number",
      "kind": "number",
      "locator": "tel:+1REPLACE-WITH-TWILIO-NUMBER",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-09-23",
    "sources": [
      "https://www.twilio.com/docs/messaging/api/message-resource (retrieved 2026-09-20)",
      "https://www.twilio.com/docs/voice/api/call-resource (retrieved 2026-09-20)",
      "https://www.twilio.com/docs/phone-numbers/api/incomingphonenumber-resource (retrieved 2026-09-20)",
      "https://www.twilio.com/docs/iam/api-keys (retrieved 2026-09-20)",
      "https://www.twilio.com/docs/usage/requests-to-twilio (retrieved 2026-09-23)"
    ],
    "reviewer_id": "aaes-eng"
  }
}