naftiko: 1.0.0-alpha2
info:
  label: Twilio Customer Communications
  description: Unified capability for customer-facing communications combining SMS/MMS messaging, outbound voice calls, and
    verification workflows. Used by customer engagement teams, marketing platforms, and notification systems to communicate
    with users across multiple channels.
  tags:
  - Twilio
  - Messaging
  - Voice
  - Customer Engagement
  - Notifications
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    TWILIO_ACCOUNT_SID: TWILIO_ACCOUNT_SID
    TWILIO_AUTH_TOKEN: TWILIO_AUTH_TOKEN
capability:
  consumes:
  - type: http
    namespace: twilio-messaging
    baseUri: https://api.twilio.com/2010-04-01
    description: Twilio Messaging API for SMS and MMS
    authentication:
      type: basic
      username: '{{TWILIO_ACCOUNT_SID}}'
      password: '{{TWILIO_AUTH_TOKEN}}'
    resources:
    - name: messages
      path: /Accounts/{AccountSid}/Messages.json
      description: Send and retrieve SMS/MMS messages
      operations:
      - name: list-messages
        method: GET
        description: Retrieve a list of messages
        inputParameters:
        - name: AccountSid
          in: path
          type: string
          required: true
          description: Twilio Account SID
        - name: To
          in: query
          type: string
          required: false
          description: Filter by recipient phone number
        - name: From
          in: query
          type: string
          required: false
          description: Filter by sender phone number
        - name: PageSize
          in: query
          type: integer
          required: false
          description: Records per page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: send-message
        method: POST
        description: Send an SMS or MMS message
        inputParameters:
        - name: AccountSid
          in: path
          type: string
          required: true
          description: Twilio Account SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: form
          data:
            To: '{{tools.to}}'
            From: '{{tools.from}}'
            Body: '{{tools.body}}'
      - name: fetch-message
        method: GET
        description: Retrieve details of a specific message
        inputParameters:
        - name: AccountSid
          in: path
          type: string
          required: true
          description: Twilio Account SID
        - name: MessageSid
          in: path
          type: string
          required: true
          description: Message SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: delete-message
        method: DELETE
        description: Delete a message record
        inputParameters:
        - name: AccountSid
          in: path
          type: string
          required: true
          description: Twilio Account SID
        - name: MessageSid
          in: path
          type: string
          required: true
          description: Message SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: twilio-voice
    baseUri: https://api.twilio.com/2010-04-01
    description: Twilio Voice API
    authentication:
      type: basic
      username: '{{TWILIO_ACCOUNT_SID}}'
      password: '{{TWILIO_AUTH_TOKEN}}'
    resources:
    - name: calls
      path: /Accounts/{AccountSid}/Calls.json
      description: Initiate and manage voice calls
      operations:
      - name: list-calls
        method: GET
        description: Retrieve a list of calls
        inputParameters:
        - name: AccountSid
          in: path
          type: string
          required: true
          description: Twilio Account SID
        - name: To
          in: query
          type: string
          required: false
          description: Filter by destination number
        - name: From
          in: query
          type: string
          required: false
          description: Filter by source number
        - name: Status
          in: query
          type: string
          required: false
          description: Filter by call status
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: make-call
        method: POST
        description: Initiate an outbound voice call
        inputParameters:
        - name: AccountSid
          in: path
          type: string
          required: true
          description: Twilio Account SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: form
          data:
            To: '{{tools.to}}'
            From: '{{tools.from}}'
            Url: '{{tools.url}}'
      - name: fetch-call
        method: GET
        description: Retrieve details for a specific call
        inputParameters:
        - name: AccountSid
          in: path
          type: string
          required: true
          description: Twilio Account SID
        - name: CallSid
          in: path
          type: string
          required: true
          description: Call SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: twilio-verify
    baseUri: https://verify.twilio.com/v2
    description: Twilio Verify API v2
    authentication:
      type: basic
      username: '{{TWILIO_ACCOUNT_SID}}'
      password: '{{TWILIO_AUTH_TOKEN}}'
    resources:
    - name: verifications
      path: /Services/{ServiceSid}/Verifications
      description: Send verification codes
      operations:
      - name: start-verification
        method: POST
        description: Start a verification by sending a code
        inputParameters:
        - name: ServiceSid
          in: path
          type: string
          required: true
          description: Verify Service SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: form
          data:
            To: '{{tools.to}}'
            Channel: '{{tools.channel}}'
      - name: fetch-verification
        method: GET
        description: Fetch a verification status
        inputParameters:
        - name: ServiceSid
          in: path
          type: string
          required: true
          description: Verify Service SID
        - name: Sid
          in: path
          type: string
          required: true
          description: Verification SID or phone number
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: verification-checks
      path: /Services/{ServiceSid}/VerificationCheck
      description: Check verification codes
      operations:
      - name: check-verification
        method: POST
        description: Check a verification code
        inputParameters:
        - name: ServiceSid
          in: path
          type: string
          required: true
          description: Verify Service SID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: form
          data:
            To: '{{tools.to}}'
            Code: '{{tools.code}}'
  exposes:
  - type: rest
    port: 8080
    namespace: twilio-communications-api
    description: Unified REST API for Twilio customer communications.
    resources:
    - path: /v1/messages
      name: messages
      description: Send and manage SMS/MMS messages
      operations:
      - method: GET
        name: list-messages
        description: List messages
        call: twilio-messaging.list-messages
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: send-message
        description: Send an SMS or MMS message
        call: twilio-messaging.send-message
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/calls
      name: calls
      description: Make and manage voice calls
      operations:
      - method: GET
        name: list-calls
        description: List calls
        call: twilio-voice.list-calls
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: make-call
        description: Make an outbound call
        call: twilio-voice.make-call
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/verifications
      name: verifications
      description: Send verification codes
      operations:
      - method: POST
        name: start-verification
        description: Start a verification
        call: twilio-verify.start-verification
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/verification-checks
      name: verification-checks
      description: Check verification codes
      operations:
      - method: POST
        name: check-verification
        description: Check a verification code
        call: twilio-verify.check-verification
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: twilio-communications-mcp
    transport: http
    description: MCP server for AI-assisted Twilio customer communications.
    tools:
    - name: list-messages
      description: List SMS/MMS messages for the account
      hints:
        readOnly: true
        openWorld: true
      call: twilio-messaging.list-messages
      outputParameters:
      - type: object
        mapping: $.
    - name: send-sms
      description: Send an SMS or MMS message to a customer
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: twilio-messaging.send-message
      outputParameters:
      - type: object
        mapping: $.
    - name: fetch-message
      description: Fetch details of a specific message
      hints:
        readOnly: true
        openWorld: false
      call: twilio-messaging.fetch-message
      outputParameters:
      - type: object
        mapping: $.
    - name: list-calls
      description: List voice calls for the account
      hints:
        readOnly: true
        openWorld: true
      call: twilio-voice.list-calls
      outputParameters:
      - type: object
        mapping: $.
    - name: make-call
      description: Initiate an outbound voice call
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: twilio-voice.make-call
      outputParameters:
      - type: object
        mapping: $.
    - name: start-verification
      description: Send a verification code to a user via SMS, voice, or email
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: twilio-verify.start-verification
      outputParameters:
      - type: object
        mapping: $.
    - name: check-verification
      description: Verify a code submitted by a user to complete 2FA
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: twilio-verify.check-verification
      outputParameters:
      - type: object
        mapping: $.