Number Masking Template

Anonymous communication between two parties using a virtual Sinch number as an intermediary.

Overview

This function enables secure, anonymous communication by routing calls between two parties through a virtual Sinch number. When Party A calls the virtual number, they are connected to Party B, and vice versa, without revealing their actual phone numbers to each other.

Key Features

• Anonymous Calling: Both parties only see the virtual Sinch number, protecting privacy
• Bidirectional Routing: Calls work in both directions (A→B and B→A)
• Session Management: Create, retrieve, and delete masking sessions via REST API
• Automatic Expiration: Sessions expire after a configurable duration with TTL cleanup
• Unauthorized Caller Protection: Rejects calls from numbers not part of the session
• Call Analytics: Tracks call counts and last call timestamps

Caller Experience

Creating a Session

1. Use the REST API to create a masking session with two phone numbers
2. Receive a virtual Sinch number and session ID
3. Share the virtual number with both parties

Making Calls

1. Either party calls the virtual Sinch number
2. System looks up the active session
3. Caller is automatically routed to the other party
4. Both parties see the virtual number as the caller ID
5. Normal conversation proceeds with masked identities

API Endpoints

Create Session

POST /v1/mask

{
  "numberA": "+15551234567",
  "numberB": "+15559876543", 
  "sessionDurationMinutes": 240,
  "metadata": {}
}

Get Session Status

GET /v1/mask/

Delete Session

DELETE /v1/mask/

Configuration

Set these environment variables in your function:

Voice Flow

sequenceDiagram
    participant Client as Client App
    participant API as Mask API
    participant Storage as TTL Storage
    participant A as Party A
    participant VN as Virtual Number
    participant ICE as ICE Handler
    participant B as Party B
    participant ACE as ACE Handler
    participant DICE as DICE Handler

    Note over Client,Storage: Session Creation
    Client->>API: 1. POST /v1/mask
    API->>Storage: 2. Store Session
    API->>Client: 3. Return Virtual Number

    Note over A,B: Call Routing
    A->>VN: 4. Call Virtual Number
    VN->>ICE: 5. ICE Event
    ICE->>Storage: 6. Lookup Session
    ICE->>B: 7. Connect to Party B

    Note over B,Storage: Call Events
    B->>ACE: 8. Answer Call
    ACE->>Storage: 9. Update Stats
    
    Note over A,B: Call Ends
    A->>DICE: 10. Hangup
    DICE->>Storage: 11. Log Call Data

Error Handling

• No Session Found: Plays message and hangs up
• Session Expired: Automatically cleans up expired sessions and hangs up
• Unauthorized Caller: Rejects calls from numbers not in the session
• Invalid API Parameters: Returns 400 with error details
• Session Not Found: Returns 404 for API requests

Project Structure

number-masking/
├── function.js              # Core masking logic with session management  
├── template.json            # Template metadata
├── README.md               # This documentation
└── examples/               # API request examples
    ├── create-session.json
    ├── ice-callback.json
    ├── ice-callback-reverse.json
    ├── ice-callback-unauthorized.json
    ├── ace-callback.json
    └── dice-callback.json

Example Usage

1. Create a Session

curl -X POST http://localhost:3000/v1/mask \
  -H "Content-Type: application/json" \
  -d '{
    "numberA": "+15551111111",
    "numberB": "+15552222222", 
    "sessionDurationMinutes": 60
  }'

2. Both Parties Call

• Party A calls the virtual number → automatically connected to Party B
• Party B calls the virtual number → automatically connected to Party A
• Both see only the virtual number as caller ID

3. Session Expires

• After the configured duration, calls to the virtual number are rejected
• Session data is automatically cleaned up via TTL

Use Cases

• Ride-sharing: Connect drivers and passengers without revealing personal numbers
• Marketplaces: Enable buyer-seller communication for transactions
• Dating Apps: Allow initial conversations with privacy protection
• Healthcare: Secure patient-provider communication
• Customer Service: Temporary connections for support cases

Ready to enable anonymous communication with privacy protection? This template provides everything needed for secure, temporary connections between two parties.