Skip to content

Telephony Service API

☎️

A comprehensive voice and telecommunications REST API built with Java, Spring Boot, and PostgreSQL. Manages phone calls, SMS, voicemail, call recording, and communication tracking.

Features

Feature Description Icon
Voice Calling Initiate and manage voice calls via SIP/VoIP 📞
SMS Management Send and receive SMS messages 💬
Call Recording Record calls with consent and compliance 🎙️
Voicemail Manage voicemail messages and transcription 📮
IVR System Interactive voice response for call routing 🤖
Call Analytics Track call duration, quality, and performance metrics 📊
Multi-Tenant Support Isolate communication data per tenant 🏢

Architecture Overview

flowchart TD
    A[Client] -->|REST API| B(TelephonyController)
    B --> C[CallService]
    C --> D[SMSService]
    C --> E[VoicemailService]
    D --> F[CallRepository]
    D --> G[SMSRepository]
    E --> H[VoicemailRepository]
    F --> I[(PostgreSQL)]
    G --> I
    H --> I
    C --> J[Telephony Provider]
Hold "Alt" / "Option" to enable pan & zoom

API Endpoints

Note: Real API endpoints to be provided and included here.

Method Endpoint Description Notes/Parameters
POST /api/v1/calls/initiate Initiate a call tenantId header, from/to numbers
GET /api/v1/calls/{callId} Get call details
POST /api/v1/sms/send Send SMS message Phone number, message content
POST /api/v1/voicemail/{callId} Save voicemail Audio file, metadata

Sequence: Initiate Phone Call

sequenceDiagram
    participant U as User
    participant API as TelephonyController
    participant C as CallService
    participant P as TelephonyProvider
    participant R as CallRepository
    U->>API: POST /calls/initiate (from, to)
    API->>C: validate call parameters
    C->>P: initiate call via provider
    P-->>C: call initiated
    C->>R: save call record
    R-->>C: call recorded
    C-->>API: CallResponse
    API-->>U: 201 Created + call details
    Note over P: Call in progress...
    P->>API: Webhook: call completed
    API->>R: update call status
Hold "Alt" / "Option" to enable pan & zoom

Database Schema

erDiagram
    calls {
        UUID id PK
        UUID tenant_id
        VARCHAR from_number
        VARCHAR to_number
        VARCHAR call_status
        TIMESTAMP start_time
        TIMESTAMP end_time
        INTEGER duration_seconds
        BOOLEAN recorded
        VARCHAR recording_url
        TIMESTAMP created
    }

    sms_messages {
        UUID id PK
        UUID tenant_id
        VARCHAR from_number
        VARCHAR to_number
        TEXT message_content
        VARCHAR delivery_status
        TIMESTAMP sent_at
        TIMESTAMP delivered_at
        TIMESTAMP created
    }

    voicemail_messages {
        UUID id PK
        UUID tenant_id
        VARCHAR from_number
        VARCHAR to_number
        TEXT transcription
        VARCHAR audio_url
        TIMESTAMP received_at
        BOOLEAN listened
        TIMESTAMP created
    }

    call_recordings {
        UUID id PK
        UUID call_id FK
        VARCHAR recording_url
        DECIMAL duration_seconds
        VARCHAR format
        TIMESTAMP created
    }

    calls ||--o{ call_recordings : "has"
Hold "Alt" / "Option" to enable pan & zoom

Getting Started

Prerequisites

  • Java 17+
  • PostgreSQL
  • Gradle
  • Telephony Provider Account (Twilio, Vonage, etc.)

Setup

git clone https://github.com/Olanna-tech/telephony-service-java.git
cd telephony-service-java
./gradlew build

Database

  • Configure your PostgreSQL credentials in src/main/resources/application.yml.
  • Run Flyway migrations (auto on startup).

Run

./gradlew bootRun

Configuration

Set the following environment variables in application.yml: 

telephony:
  provider: twilio
  twilio-account-sid: your-account-sid
  twilio-auth-token: your-auth-token
  recording-enabled: true
  sms-enabled: true
  voicemail-enabled: true

Contributing

Pull requests are welcome! For major changes, please open an issue first.

License

MIT

Contact