Telefonie Communications

naftiko: "1.0.0-alpha1"

info:
  label: "Telefonie Communications"
  description: >-
    Unified capability combining Telefonie Voice and SMS APIs for comprehensive
    communications workflows. Enables voice calling, SMS messaging, conferencing,
    and call recording from a single interface. Designed for developers building
    customer communication, notification, and engagement platforms.
  tags:
    - Call Recording
    - Communications
    - CPaaS
    - Messaging
    - SMS
    - Telephony
    - Voice
    - VoIP
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      TELEFONIE_API_KEY: TELEFONIE_API_KEY

capability:
  consumes:
    - import: telefonie-voice
      location: ./shared/telefonie-voice.yaml
    - import: telefonie-sms
      location: ./shared/telefonie-sms.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: telefonie-communications-api
      description: "Unified REST API for Telefonie voice and SMS communications."
      resources:
        - path: /v1/calls
          name: calls
          description: "Voice call management"
          operations:
            - method: GET
              name: list-calls
              description: "List voice calls with filtering options"
              call: "telefonie-voice.list-calls"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: initiate-call
              description: "Initiate an outbound voice call"
              call: "telefonie-voice.initiate-call"
              with:
                to: "rest.to"
                from: "rest.from"
                url: "rest.url"
                record: "rest.record"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/conferences
          name: conferences
          description: "Multi-party conference management"
          operations:
            - method: GET
              name: list-conferences
              description: "List all conferences"
              call: "telefonie-voice.list-conferences"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-conference
              description: "Create a new conference room"
              call: "telefonie-voice.create-conference"
              with:
                friendly_name: "rest.friendly_name"
                record: "rest.record"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/messages
          name: messages
          description: "SMS and MMS messaging"
          operations:
            - method: GET
              name: list-messages
              description: "List SMS and MMS messages"
              call: "telefonie-sms.list-messages"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: send-message
              description: "Send an SMS or MMS message"
              call: "telefonie-sms.send-message"
              with:
                to: "rest.to"
                from: "rest.from"
                body: "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: telefonie-communications-mcp
      transport: http
      description: "MCP server for AI-assisted communications using Telefonie voice and SMS APIs."
      tools:
        - name: list-calls
          description: "List voice calls with optional status and direction filtering"
          hints:
            readOnly: true
            openWorld: false
          call: "telefonie-voice.list-calls"
          outputParameters:
            - type: object
              mapping: "$."

        - name: make-call
          description: "Initiate an outbound phone call to a specified number"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "telefonie-voice.initiate-call"
          with:
            to: "tools.to"
            from: "tools.from"
            url: "tools.url"
            record: "tools.record"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-conferences
          description: "List all active and completed conference calls"
          hints:
            readOnly: true
            openWorld: false
          call: "telefonie-voice.list-conferences"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-conference
          description: "Create a new multi-party conference call room"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "telefonie-voice.create-conference"
          with:
            friendly_name: "tools.friendly_name"
            record: "tools.record"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-messages
          description: "List sent and received SMS and MMS messages"
          hints:
            readOnly: true
            openWorld: false
          call: "telefonie-sms.list-messages"
          outputParameters:
            - type: object
              mapping: "$."

        - name: send-sms
          description: "Send an SMS or MMS message to a phone number"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "telefonie-sms.send-message"
          with:
            to: "tools.to"
            from: "tools.from"
            body: "tools.body"
            media_url: "tools.media_url"
          outputParameters:
            - type: object
              mapping: "$."